Quickstart
Install the Coco SDK, connect a project to the hosted gate, check the API is healthy and send it a test transaction.
Install the Coco SDK, connect a project, and send your first check to the hosted gate.
The hosted gate is the Coco service that decides each tool call and keeps a record of every decision. In this guide, you install the SDK, connect a new project to the gate, confirm the API is healthy, and send a test transaction to see a decision come back.
Prerequisites: Python 3.10 or later, and uv, which installs from Coco's package index. To run the sample agent at the end, a model with tool calling and its API key, read from COCO_MODEL and COCO_MODEL_API_KEY.
Get your API key
- Sign in at app.trustcoco.ai.
- Finish onboarding. Coco creates your project and shows your API key once.
- Copy the key before you leave the page.
Install the SDK
Your API key is also the password to Coco's package index, so the install uses it directly.
Set your key, then install the packages:
macOS and Linux
export COCO_API_KEY=coco_live_...
GATE=coco-gate-1065150778011.australia-southeast1.run.app
export COCO_INDEX="https://coco:$COCO_API_KEY@$GATE/v1/sdk/simple/"
uv venv && source .venv/bin/activate
uv pip install --index "coco=$COCO_INDEX" coco-framework trustcoco-sdkWindows PowerShell
$env:COCO_API_KEY = "coco_live_..."
$GATE = "coco-gate-1065150778011.australia-southeast1.run.app"
$env:COCO_INDEX = "https://coco:$env:COCO_API_KEY@$GATE/v1/sdk/simple/"
uv venv
.venv\Scripts\Activate.ps1
uv pip install --index "coco=$env:COCO_INDEX" coco-framework trustcoco-sdkuv prints Installed 35 packages. This installs the SDK and the coco command from Coco's index, and coco-framework, the agent runtime with its chat models, from PyPI. For other options, see Install.
Good to know: The next steps use COCO_API_KEY and GATE, so keep this terminal open.
Create a connected project
Create the project with your key:
macOS and Linux
coco init payments-agent --key "$COCO_API_KEY"
cd payments-agentWindows PowerShell
coco init payments-agent --key $env:COCO_API_KEY
cd payments-agentCoco writes the project, checks your key with the gate, and connects the two. When it finishes, you'll see these lines:
Connected to https://coco-gate-1065150778011.australia-southeast1.run.app as project <your project id> (monitor).
50 free checks left
key written to .env as COCO_API_KEY; the gate now decides and keeps the receipts.
documents go to https://coco-policy-1065150778011.australia-southeast1.run.app (coco policy upload).
coco.yaml names the project by its id; receipts name the agent payments-agent.They confirm that the SDK is installed and the gate accepted your key. The free checks line appears only on an account with free checks. On a project whose contracts already live on the gate, a contracts differ line follows; a new project has none.
Your project now contains:
coco.yaml: The project's settings..env: Your API key.agent.pyandtools/: A sample agent with one tool,send_payment.contracts/andpolicies/: The rules your agent runs under, and the documents they come from. Fromtrustcoco-sdk0.1.3,policies/starts withsample_policy.pdf, a two-page Payment Controls Policy. On 0.1.2,policies/holds only aREADME.md, so add your own policy PDF before you upload one.
Check the API health
Ask the gate whether it's up:
macOS and Linux
curl -sS "https://$GATE/health"Windows PowerShell
Invoke-RestMethod "https://$GATE/health"The gate responds with ok set to true:
{"ok":true,"database":"postgresql","classifier":false,"platform":true}Send a test transaction
Post your first check to the gate. The request describes a sample payment, in the same form the SDK sends for every tool call.
macOS and Linux
curl -sS -X POST "https://$GATE/v1/check" \
-H "Authorization: Bearer $COCO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "payments.send", "args": {"amount": 900, "payee": "Sunrise Capital", "memo": "Quickstart test"}, "session_id": "quickstart", "call_id": "quickstart-1"}'Windows PowerShell
Invoke-RestMethod -Method Post "https://$GATE/v1/check" `
-Headers @{ Authorization = "Bearer $env:COCO_API_KEY" } `
-ContentType "application/json" `
-Body '{"action": "payments.send", "args": {"amount": 900, "payee": "Sunrise Capital", "memo": "Quickstart test"}, "session_id": "quickstart", "call_id": "quickstart-1"}'On a new project, the gate responds with a decision like this one. curl prints it on one line, PowerShell prints it as a list, and your receipt number and hash will differ:
{
"verdict": "ESCALATE",
"effect": "run",
"mode": "monitor",
"reason": "No live contract governs payments.send, and whether it changes anything is unknown",
"action": "payments.send",
"rule": null,
"deciding_check": null,
"checks": [],
"audit_id": 1,
"receipt_hash": "sha256:788920f9...",
"escalation": null,
"impact": {"impactful": null, "source": "unknown", "why": "No classifier is configured"},
"obligations": null
}Your API is set up correctly when audit_id holds a number. It means the gate accepted your key, decided the transaction, and recorded a receipt.
| Field | Description |
|---|---|
verdict | What Coco decided: AUTO_EXECUTE, OBSERVE, ESCALATE, or DENY. |
effect | What happens to the call: run, escalate, or deny. |
reason | Why Coco decided this, in words. |
audit_id, receipt_hash | The receipt the gate wrote, chained to the one before it. |
Why ESCALATE? A new project has no contracts, so nothing governs payments.send yet. Coco takes the cautious verdict for a tool it can't classify. The effect is run because new projects start in Monitor, which records what Enforce would have done and stops nothing. Once a live contract governs payments.send, the verdict comes from that contract.
Good to know: Each request spends one check from your account's allowance.
View the decision in the dashboard
- Open your project at app.trustcoco.ai.
- Select Audit Logs.
- Find the
payments.senddecision.
The entry shows the verdict and the reason for your test transaction.
Congratulations! Your SDK is installed, your project is connected, and the gate has recorded your first decision.
Run the sample agent
To run the sample agent with a real model, set the model and its key, add them to .env beside the API key already there, and run the agent:
Keep in mind: The agent calls your model provider, which charges for the tokens, and the gate records the decision on your project.
macOS and Linux
export COCO_MODEL=gpt-6-luna # any model with tool calling
export COCO_MODEL_API_KEY=sk-... # the model provider's key
cat >> .env <<EOF
COCO_MODEL=$COCO_MODEL
COCO_MODEL_API_KEY=$COCO_MODEL_API_KEY
EOF
coco run "Pay Sunrise Capital 900 for invoice 88"Windows PowerShell
$env:COCO_MODEL = "gpt-6-luna" # any model with tool calling
$env:COCO_MODEL_API_KEY = "sk-..." # the model provider's key
Add-Content .env "COCO_MODEL=$env:COCO_MODEL", "COCO_MODEL_API_KEY=$env:COCO_MODEL_API_KEY"
coco run "Pay Sunrise Capital 900 for invoice 88"The agent answers in one line, such as Paid Sunrise Capital 900 for invoice 88., and the gate records the decision on your project. For a model other than OpenAI's, also add COCO_MODEL_BASE_URL, its OpenAI-compatible endpoint.
Troubleshooting
In PowerShell, the messages below appear in the error text.
uv pip install returns 401
If uv gives the hint could not be queried due to a lack of valid authentication credentials (401 Unauthorized), the package index refused your key. Check COCO_API_KEY, then set COCO_INDEX again.
PowerShell won't run the activation script
If you see running scripts is disabled, PowerShell's execution policy is blocking the script. Run Set-ExecutionPolicy -Scope Process RemoteSigned, then activate again.
coco isn't found
The virtual environment isn't active. Activate .venv and run the install again.
coco init says the gate did not accept the key
If the message includes unknown or revoked key, the key is wrong or revoked. The project is still created. Run cd payments-agent, then coco connect --key <a valid key>.
coco init says the key is not bound to a project
Your account has no project yet, or it has several. Run coco connect --project <id> --key <key>. You'll find the id in the dashboard's address: /projects/<id>/overview.
curl can't reach the gate
Errors such as curl: (3), (6), (7), or Could not resolve host mean the gate couldn't be reached. Check your network and proxy. If this is a new terminal, set GATE again.
The request returns send a key or token
COCO_API_KEY isn't set in this terminal. Set it again, as in Install the SDK.
The request returns unknown or revoked key
The key is wrong or revoked. Use a valid key from the dashboard.
The request returns this key is not bound to a project
Your key covers several projects. Add -H "X-Coco-Project: <id>" to the request. In PowerShell, add "X-Coco-Project" = "<id>" to -Headers.
The request returns Your free checks are used up
Your account's free checks are spent and it has no plan. In the dashboard, go to Settings → Billing and choose a plan.
Related Resources
Turn policies into contracts
Upload the sample policy, or put your own under Coco.
Choose an integration
Send this same check for every tool call your agent makes.
Your first governed agent
Learn the whole loop on a sample policy, with no key.
Connect to the gate
Manage keys and projects, and see what changes once you're connected.
HTTP API
Look up every field of the check.
How Coco enforces
Follow one tool call from proposal to receipt.
Need Help?
We want your first check to go smoothly. If you get stuck, contact us at trustcoco.ai.