Connect to the gate
Point a project at the hosted gate and document service, manage keys and projects, and see what changes once connected.
Point a project at the hosted gate and document service.
The hosted gate decides each tool call over HTTP and keeps the record, and the dashboard shows that record. Connecting a project changes no agent code.
Prerequisites: An API key from the dashboard.
Connect a project
Connect a new project, or one you already have:
coco init payments-agent --key coco_live_... # a new project, connected
coco connect --key coco_live_... # a project you have alreadyCoco checks the key with the gate, writes gate.url and policy.url to coco.yaml, and writes the key to .env as COCO_API_KEY, readable by you alone. You'll see:
Connected to <gate URL> as project <project> (<mode>).
<N> free checks left
key written to .env as COCO_API_KEY; the gate now decides and keeps the receipts.
documents go to <document service URL> (coco policy upload).To confirm it works, run a health check and a test transaction.
Good to know: If the gate refuses the key during coco init --key, the project is still created. Run coco connect once the cause is fixed.
--url and --policy-url name other services. Without them, the command takes COCO_GATE_URL and COCO_POLICY_URL, then the URLs in coco.yaml, then the hosted services.
Keys
An agent authenticates with a project key: coco_live_ for production and coco_test_ for everything else. The key is shown once, and only its SHA-256 hash and a short prefix are stored. Find your keys on the dashboard's SDK & API Keys page.
An agent's key asks for verdicts, and polls or withdraws the escalations its own calls opened. It never approves one. A person approves.
Which project a key reaches
- A key bound to a project: Reaches that project.
- A key bound to none: Reaches your account's only project. Onboarding gives you this kind of key.
- An account with no project or several: The gate refuses and asks for
coco connect --project <id>. The project's id is in the dashboard's address:/projects/<id>/overview.
--project also works on coco init, and writes project: in coco.yaml.
When the gate names the project by its id, coco connect writes the id and keeps the name you gave as agent:, the agent id on every receipt:
project: "<the project's id from the dashboard>"
agent: "payments-agent"The Python client sends the id as X-Coco-Project. The TypeScript client sends no such header, so use a key bound to one project there.
What changes once connected
- The gate decides:
load().engine()andload().guard()decide through the gate with the same methods, and the record lives there. - The gate holds the settings: Mode,
ungoverned, limits,verdict_timeout, and contracts come from the gate. The values incoco.yamlapply only when you decide in process. - Monitor today: Every hosted project runs in Monitor. The Overview page shows the mode in its Enforcement Configuration card and can't change it yet, so
mode: enforceincoco.yamlhas no effect on a connected project. - No key, no run: A connected project never falls back to deciding on your machine. Without the key,
load().engine()raises an error naming the.envto put it in, andcoco ledger,coco escalations, andcoco verifystop unless you pass--local. - Unreachable means DENY: See Fail closed.
Contracts on a connected project
coco policy upload writes each draft to the project's Contracts page. A person reviews and activates them there, and active means live. coco contracts activate edits local files, so it doesn't change the gate. See Turn policies into contracts.
coco connect warns when your local live and testing contracts differ from the gate's. Contracts written by hand reach the gate through an administrator, with coco contracts push, so contact us to send them.
Read the record and decide
- Audit Logs: Lists each decision with its checks.
- Escalations: Lets a person approve or reject. The agent picks up the decision the next time it asks.
coco ledger, coco escalations, and coco verify read the gate too, with a reviewer's sign-in token in COCO_REVIEWER_TOKEN. The dashboard doesn't issue these tokens yet. To read this machine's ledger instead, pass --local.
Keep in mind: coco status always counts decisions from the local ledger, so on a connected project its counts stay at zero.
Free checks
Each call that records a verdict spends one of your account's free checks, then needs a plan in good standing. With neither, the gate returns 402 and records nothing, and the SDK turns that into DENY with the reason. The call runs in Monitor and stops in Enforce. Polling an escalated call again is free. coco connect prints how many checks are left.
What the dashboard doesn't do yet
- The Overview page shows a project's mode but can't change it, so every hosted project runs in Monitor.
- The Audit Logs doesn't run the chain check. Use
coco verify. - The dashboard has no
testingstatus. A contract there is draft or active, and active means live. - Uploading a policy from the dashboard is built and not released.