Coco
Get started

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

  1. Sign in at app.trustcoco.ai.
  2. Finish onboarding. Coco creates your project and shows your API key once.
  3. 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-sdk

Windows 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-sdk

uv 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-agent

Windows PowerShell

coco init payments-agent --key $env:COCO_API_KEY
cd payments-agent

Coco 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.py and tools/: A sample agent with one tool, send_payment.
  • contracts/ and policies/: The rules your agent runs under, and the documents they come from. From trustcoco-sdk 0.1.3, policies/ starts with sample_policy.pdf, a two-page Payment Controls Policy. On 0.1.2, policies/ holds only a README.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.

FieldDescription
verdictWhat Coco decided: AUTO_EXECUTE, OBSERVE, ESCALATE, or DENY.
effectWhat happens to the call: run, escalate, or deny.
reasonWhy Coco decided this, in words.
audit_id, receipt_hashThe 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

  1. Open your project at app.trustcoco.ai.
  2. Select Audit Logs.
  3. Find the payments.send decision.

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.


Need Help?

We want your first check to go smoothly. If you get stuck, contact us at trustcoco.ai.

On this page