Onboarding
Bring your agent.
We'll bring the ground rules.
Connect an agent, watch what it actually does, see what it costs, and switch on the controls your route supports. Not every control exists on every route — this walks you to the ones that do.
Takes about five minutes. You can leave and come back — it remembers where you were.
Your tools are taking the Navige route. Model calls outside the proxy are a different story.
Stage 2
What are you bringing aboard?
Pick the thing your agent runs on. Everything after this adapts to it — the instructions, the diagram, and which controls you'll actually be offered.
Stage 3
Make yourself at home
An account, an agent, and one key. The key part is the part people get wrong, so it's worth thirty seconds.
nv_Aet-44Cqz… and is shown once.Navige stores only a hash. Nobody, including us, can recover the original.
Lost it? You don't have to break anything. Open the agent's Keys panel and add a second key — every key already in use keeps working. Replace key is the other option, and it revokes every key that agent holds; that one is for a key you think has leaked.
An agent can hold up to ten keys at once, so give each machine its own — CI runner, Mark's laptop. The Keys panel lists each by prefix and when it was last used, which answers "which key is in which config?" without revealing anything. A key that has never been used is the safe one to revoke.
The John Cena bit: you can't see me. In this case, neither can our support team recover your key.
Stage 4
Connect your environment
Exactly the steps for what you picked. Nothing for the eleven setups you didn't.
Stage 5
Connected is a start
Now find out what actually happened. These four are different questions, and a green tick on one says nothing about the others.
Verifying your connection from here would mean asking you to paste a live agent key into a public web page. We're not going to do that, and you shouldn't do it anywhere else either. The console is signed in and can see your traffic — this checklist tells you exactly what to look at once you're there.
Stage 6
The dashboard isn't broken
On day one most tiles say "No data yet", with a reason. That's deliberate — $0.00 would make a claim the data doesn't support.
| What you'll see | Why |
|---|---|
| "No data yet" on most tiles | An empty result gets an honest label rather than a zero. |
| Evidence routing doing nothing | It waits for 200 judged jobs on each of at least two models. Per-call mode acts from the first call. Meanwhile Cost Shadow shows what routing would have done, priced from your traffic. |
| Runaway detection off | Enable it in Cost Control. Its spend-velocity ceiling is derived weekly from your completed jobs — the 95th percentile of per-minute burn, times three — and it abstains until about twenty measurable jobs exist. |
| Budgets reporting, not blocking | Switch one to "Refuse further calls" to make it a ceiling. Not a prepaid reservation: a call in flight can still incur cost. |
| Some models unpriced | Unpriced doesn't mean free. An unpriced model contributes nothing rather than contributing a guess. Prices sync nightly from two independent feeds and only change when both agree. |
| Registry asking about a few tools | If a tool calls a vendor that charges per call, enter that price so duplicate suppression can count what it avoided. Navige won't guess a number that could end up on your invoice. |
Every money figure is labelled. Measured comes from real token counts at real prices. Modelled is a counterfactual — what another model would have cost. They never get added together, because one is a fact and the other is an argument.
Stage 7
You're holding the switches
Everything is off until you turn it on, apart from prompt caching on new organisations. A proxy that silently truncates a result your agent needed is a correctness bug wearing a saving's clothes.
Well, look at that. Your agent's on board.
You can come back to any stage from the rail above — nothing here starts over.
Section 01
Before you start
Create your account at app.navige.ai/signup. Organisation name is optional; leave it blank and Navige uses your name. Confirm your email before entering the console.
Then Agents → Add agent. The key looks like nv_Aet-44Cqz… and is shown once.
Only a hash is stored, so nobody — including us — can recover the original. Lost it? Open the agent's Keys panel and add a second key: everything already in use keeps working. Replace key revokes every key that agent holds and is for a suspected leak. An agent may hold up to ten live keys, each listed by prefix and last use.
MCP users: bring the tools
Registry → Connected MCP servers. Name your server, paste its URL, then check the discovered tool count.
Navige's /mcp endpoint forwards tool calls to your server. Register none and a client connects successfully to an empty tool list. The connection works; the toolbox is empty.
Section 02
Give the work a name
One label for the kind of work. One identity for the run. Keeping those apart saves a lot of head-scratching later.
x-navige-workflow: support.triage
x-navige-transaction: <one id per job, reused across its calls>A workflow name is the kind of work, not the identity of one run. Reuse a transaction id across that job's calls and retries; use a different one for the next job. Without an external reference, a workflow-only request opens a new transaction per call.
Without recognised correlation, model usage is recorded as uncorrelated usage — no cost-per-job, no job budgets, no runaway analysis. Navige can also correlate through a valid traceparent, and Claude Code's session header supplies an identity automatically.
For an MCP client that supports request metadata the equivalents are navige/workflow and navige/transaction in _meta. That needs real client support; the connector recipes here do not establish it.
Section 03
Pick your setup
Four route archetypes. The guided mode picks one for you from your environment; this is all of them side by side.
| Route | What Navige carries | What it gets you |
|---|---|---|
| Tools (MCP) | Tool calls, and their results | Governance, audit, duplicate suppression, result capping, tool scoping |
| Models (proxy) | Model requests and responses | Usage measurement and every cost control |
| Both | Both, joined by job identity | Cost per job across tools and models — only with matching correlation |
| Decisions | A decision, before you act | Governance and approvals. No result is seen, so no savings are reported |
Anthropic, OpenAI, Google Gemini, AWS Bedrock and xAI. Other providers aren't supported yet — we'd rather say so than let you find out in production.
Section 04
MCP clients
Your MCP client → Navige MCP → your MCP server. Tool results return through Navige to the client, which is what lets it cap, cache and withhold.
Claude.ai — Team and Enterprise
Claude.ai, meet Navige. Let's introduce them properly. Organization settings → Connectors → Add → Custom → Web. Team needs an Owner or Primary Owner; Enterprise also accepts a custom role with Manage access to Libraries.
https://api.navige.ai/mcp?api_key=nv_YOUR_KEYMembers sharing one connector reach Navige with the same agent credential. Give each connector its own key from the agent's Keys panel if you want to revoke them separately.
Added doesn't mean enabled. Each member goes to Customize → Connectors → Connect, then enables it per conversation from the + → Connectors menu.
A Claude.ai-hosted agent runs its model inside Anthropic's infrastructure. Navige cannot proxy that call or show its token spend. Model token spend appears when API model calls use Navige's model proxy. Don't expect this connector to turn a subscription into a per-token bill.
Claude Desktop, Cursor, Windsurf, Cline, Zed
Same URL, wherever your client stores MCP servers. Configuration formats differ between clients and versions and have not all been tested with Navige — check your client's own remote-MCP instructions first.
Section 05
Always-on agents
A hosted agent runs on the vendor's model, inside the vendor's machine. Navige governs the tools you route through it, and nothing else.
For ChatGPT custom MCP apps the workspace must permit developer mode and custom apps; Business admins or owners can create them, Enterprise and Edu can authorise developers. Use Apps → Create, supply the remote endpoint, and test the draft.
The Grok Bot and Dots setup instructions are still being verified. Don't assume a hosted agent accepts this URL just because another MCP client does.
There is no model-cost saving on this path. The model is bundled into the subscription and its calls aren't available to route. You get governance, approvals, audit and duplicate suppression on the tools you connect — and nothing on the ones the agent reaches through its own built-in connectors.
Section 06
Claude Code
export ANTHROPIC_BASE_URL="https://api.navige.ai/proxy/anthropic"
export ANTHROPIC_CUSTOM_HEADERS="x-navige-key: nv_YOUR_KEY
x-navige-workflow: engineering.codegen"This configures Navige routing and authentication only. Your Anthropic provider credential still comes from ANTHROPIC_API_KEY. Windows PowerShell uses $env:NAME = "value" rather than export.
Context trimming, the output ceiling, model routing and prompt caching are disabled when Navige identifies Claude Code — its capability headers and body fields only work as matched pairs. Measurement, configured budgets, kill switch and spend caps still apply.
If the gateway is unreachable this route stops until connectivity returns, or until you deliberately restore a direct provider route — which bypasses Navige. Claude Code's documentation also notes a non-Anthropic base URL disables Remote Control.
Section 07
SDKs and frameworks
Your application → Navige model proxy → your model provider. Change the address; keep your provider key. Gemini uses /proxy/google; xAI uses /proxy/xai, with /proxy/grok as an alias.
from anthropic import Anthropic
client = Anthropic(
base_url="https://api.navige.ai/proxy/anthropic",
default_headers={"x-navige-key": "nv_YOUR_KEY",
"x-navige-workflow": "support.triage"},
)import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic({
baseURL: "https://api.navige.ai/proxy/anthropic",
defaultHeaders: {
"x-navige-key": "nv_YOUR_KEY",
"x-navige-workflow": "support.triage",
},
});LangChain, LangGraph and LlamaIndex take base_url and default_headers on the model object, and everything built on top inherits it. CrewAI uses ANTHROPIC_API_BASE plus extra_headers; AutoGen uses base_url and default_headers. If a version won't accept custom headers, put the key in the URL: …?api_key=nv_YOUR_KEY.
LangChain, CrewAI and AutoGen are frameworks. The provider is still whoever your key belongs to, and that is what Navige proxies. Model availability depends on your provider account, and each example should be checked against your installed version.
Section 08
AWS Bedrock
AWS signs the request including its host, so forwarding a signed request invalidates it. Navige re-signs using your connected AWS account — your account, your bill, your model access. Connect the account before using this route.
curl -X POST "https://api.navige.ai/proxy/bedrock/model/us.anthropic.claude-haiku-4-5-20251001-v1:0/converse?region=us-east-1" \
-H "Content-Type: application/json" \
-H "x-navige-key: nv_YOUR_KEY" \
-H "x-navige-workflow: support.triage" \
-d '{"messages":[{"role":"user","content":[{"text":"hello"}]}],
"inferenceConfig":{"maxTokens":256}}'Newer Claude models need the inference-profile ID, including the us. prefix. /invoke also works with that family's own body format — Navige forwards what you send and does not translate between Bedrock's per-family shapes.
"Resource": [
"arn:aws:bedrock:*::foundation-model/*",
"arn:aws:bedrock:*:YOUR_ACCOUNT_ID:inference-profile/*"
]Both resource types are needed: an inference-profile ARN carries an account id, a foundation-model ARN does not. That is a fragment, not a complete policy.
Section 09
Salesforce and AWS platforms
Discovery inventories an agent; it does not by itself put an enforcement check before that agent's actions. Complete platform-specific setup still needs verification.
| Platform | Setup |
|---|---|
| Salesforce Agentforce / Einstein Bots | Connect in Settings, then install the Apex package from salesforce/; it calls /enforce before each action. |
| AWS Bedrock Agents (Classic) | Connect your AWS account. Discovery inventories the agents. |
| AWS AgentCore | Create a Gateway Target pointed at the Navige MCP URL. Calls routed through that target use MCP; calls that bypass it stay outside Navige. |
Section 10
The decision API
For anything you can't put a proxy in front of. Ask before acting, then handle the answer.
curl -X POST https://api.navige.ai/enforce \
-H "Authorization: Bearer nv_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"tool":"refund_customer","system":"billing",
"arguments":{"amount":420},
"transaction":{"workflowKey":"billing.refund"}}'allow and approved permit the action. deny, rejected and expired do not. pending means wait — poll /enforce/status/:approvalId. A 400, a 404 or a 503 authorises nothing. The request waits for approval by default and can hold the connection up to five minutes; set wait: false for an immediate reply.
Your system performs the action. Navige never sees the result, so this route provides governance and reports no savings. The n8n-nodes-navige community package has not been verified — don't install it on the strength of these instructions alone.
Section 11
Check the first call
Make one call, then open Transactions. Look for the correlated job and inspect its steps and usage.
A successful response does not judge whether the job delivered the right answer. Token counts and cost depend on the route, the credential type and the prices available.
A workflow name alone does not group several calls. A trace or a Claude Code session can correlate without that header. A wrong key produces 401; valid calls with no recognised correlation are recorded as uncorrelated usage. A successful connection and a useful transaction are two different checks — do both.
Section 12
Turn on the controls
Settings → Cost Control. Each lever shows what your last 30 days say, with the switch beside it. Money figures are labelled measured or modelled; where only the condition can be detected, it says that instead. Navige won't estimate a saving it can't measure.
| Lever | What changes |
|---|---|
| Duplicate suppression | Identical reads reuse a result within the window. Reads only; errors never cached. A reused result can be older than a fresh read. |
| Result capping | Oversized tool results truncated before entering context. Start from Recommendations — it proposes a size per tool. |
| Tool scoping | Unused schemas withheld. Schemas return every turn, so the reduction compounds. |
| Context trimming | Stale tool results removed before the conversation is re-sent. Invalidates the prompt cache from that point, so on long loops the two work against each other. |
| Prompt caching | Anthropic only. Adds markers where none exist and a read is likely. Cannot change an answer; your own markers are left alone. On by default for new organisations. |
| Output ceiling | Provider-enforced, so the only real ceiling. Only ever lowers a limit you set. Not a guarantee against job-budget overshoot. |
| Model routing | Per call acts from the first call; evidence waits for 200 judged jobs on each of at least two models. Your model is the ceiling — only down, same provider, kept when unsure. |
A routed answer is checked before delivery. A nonexistent tool, unparseable arguments, a missing required field or truncated JSON triggers a re-run on your original model, and that answer is the one delivered; the rejected call is booked as a loss. Repeated failures stop routing to that model for the agent, with a small probe so it can recover.
Steps whose kind usually acts go straight to your model, and a delete, pay, send or exec call from a cheaper model is re-run on yours before your agent sees it. That does not guarantee the decision is right, or that every dangerous action can be recognised.
Sampled comparisons have a share of routed requests also answered by your own model, in the background, to compare decisions. Those extra calls cost real money. Off by default, capped, opt-in.
Section 13
Did the job work?
Navige sees the status code. It can't infer whether the answer was right.
curl -X POST https://api.navige.ai/v1/transactions/<id>/outcome \
-H "Authorization: Bearer nv_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"succeeded": true}'Prefer the console? Open a job under Transactions and answer "Did this job get the right answer?" — Correct, Wrong, or Clear. Same evidence, same effect, no integration work. Per-call routing doesn't need these labels; evidence-mode routing and holdout comparisons do.
Jobs marked Wrong are excluded from the measured savings used to calculate Navige's share when the period closes. Unjudged jobs are not automatically excluded. It does not refund provider charges or remove a paid plan's minimum fee, and a later change is not a promise to revise a closed invoice.
Section 14
Check against the bill
Settings → Provider billing. Connect a provider account and your Billing page shows the provider's actual charge beside Navige's measurement.
| Provider | Access needed |
|---|---|
| AWS Bedrock | No new key — the discovery role plus ce:GetCostAndUsage. The request filters to Bedrock; the rest of your AWS bill is never returned. |
| Anthropic | A key that isn't scoped to a single workspace. Prefer a service-account key over an Admin key — an Admin key can also manage members and API keys, and Navige has no use for either. |
Reconciliation supports AWS Bedrock and Anthropic. OpenAI and Google publish billing APIs we could not verify from their documentation, and xAI publishes none at all, so its spend is measured like any other and simply cannot be checked against an invoice. Disconnecting deletes the stored figures as well as the access.
Same account, same scope, same period. A gap can mean traffic bypassing Navige — but late-settling figures, missing collection days, unpriced usage and pricing differences all need ruling out first. Reconciliation is a coverage check; it does not prove how much an intervention saved.
Section 15
Day one
The dashboard isn't broken. Most tiles say "No data yet", with a reason — $0.00 would make a claim the data doesn't support.
An unpriced model contributes nothing to a spend figure rather than contributing a guess. Common prices sync nightly from two independent feeds; a gap can be filled, and a price won't change unless both feeds agree.
Its spend-velocity ceiling is derived weekly from your own completed jobs — the 95th percentile of per-minute burn, times three — and recalculated, because the levers change the rate it was calibrated against. It abstains until about twenty measurable jobs exist and never overwrites a figure you set yourself.
Budgets report by default. Switch one to "Refuse further calls" to block once recorded spend reaches the threshold. Not a prepaid reservation and not a guarantee against overshoot: a call already in flight can still incur cost.
Section 16
Troubleshooting
| What you see | What it means |
|---|---|
401 missing | No key reached Navige. Check the header name or the ?api_key= parameter. |
401 not_found | Wrong or deleted key. |
401 revoked | The agent was revoked in the console. |
401 malformed | Wrong key shape — a stray character or a truncated paste. |
agent_inactive / agent_expired | Check the agent's status and expiry. No configuration makes an inactive agent valid. |
| One client stopped, the rest work | That client's key was revoked on its own. The Keys panel lists it as revoked — add a new key for that machine; the others are unaffected. |
| You lost a copy of a key | Keys → Add key. Nothing stops working. Replace key is for a suspected leak and revokes every key the agent holds. |
| MCP connects, no tools | Register your MCP server in Registry → Connected MCP servers. |
403 kill switch active | The kill switch is on. |
429 monthly budget | A blocking budget was reached. The model proxy answers 429 rather than 403 because a quota resets. |
| Calls work, Transactions empty | Check recognised correlation — transaction id, trace, or Claude Code session — plus workflow attribution. A missing workflow name is not the only cause. |
| Routing never changes model | In evidence mode, Recommendations → Model routing names the blocker. Pick per-call mode for routing from the first call. |
404 unknown provider | Valid: anthropic, openai, google (alias gemini), xai (alias grok), bedrock. |
security token invalid | Malformed AWS credential — check for stray characters before investigating IAM. |
on-demand throughput isn't supported | Use the us. inference-profile ID. |
not authorized: bedrock:InvokeModel | IAM policy missing the inference-profile resource. |
| Provider billing rejects credential | Anthropic: a workspace-scoped key won't work. AWS: the role needs ce:GetCostAndUsage. |
| Signed in, but a page errors | Send us the digest number shown. It identifies the exact failure. |
Section 17
Limits, and the references
Every control fails open: if Navige is unreachable or something inside it breaks, your call proceeds unmetered. The exceptions are the ones you configured — a kill switch, a blocking budget, a deny policy. On the tool path, write, destructive and financial actions fail closed instead, organisation settings can override those defaults, and a degraded decision is logged with its cause rather than counted as a normal allow.
A reachable gateway can bypass a failing cost lever and continue the request. An unreachable gateway cannot forward it at all — that needs restored connectivity or a separately configured and tested fallback, and a direct provider route bypasses Navige entirely.
Official references
An official client guide explains that client. It does not establish that every Navige integration has been tested end to end — the platform-specific checks flagged above still apply.