Chio/Docs
LOGIN · JOIN

The Computer and the Kernel

Every Computer SDK call lowers to kernel objects: capability tokens, mediated calls, receipts, compiled policy, and federation peers.

Concept chio@5f63e6e

On this page

The Quickstart works with projects, forks, grants, and runs. The kernel works with capability tokens, mediated calls, and receipts. They are one system at two levels: each SDK call produces kernel objects, so every kernel page in these docs describes something your project already did.

The fixer's refused read of /secrets/.env from part 1 shows the correspondence. The SDK printed one event and one receipt summary. Underneath are a signed token, a checked call, and a signed record, and the kernel pages explain each of them.

Each SDK object is a kernel object

The SDK names what you work with. The kernel names what it checks and signs. Read the table left to right to find the kernel page behind an SDK call.

In the SDKIn the kernelRead more
Computer.openAn environment owned by your operator identity. Its kernel holds key 4f1c…a2e9 and signs every decision.Architecture
fork.grantA capability token your kernel signs: tool grants with path constraints, a spend ceiling, an expiry, and the agent's key as subject.Capabilities
fixer.run, events()A sequence of mediated calls. Each operation the agent attempts is a tool call the kernel checks before dispatch.The mediated call
project.historyThe receipt store. receipts() queries it, and export() writes an evidence package.Receipts
project.policy.addA rule compiled into the HushSpec policy the kernel evaluates at admission. Each change produces a new policy hash.Guards
pricing.requireAn approval requirement. A matching call pauses until a signed approval binds that exact request.Human-in-the-loop
project.service, publishAn MCP edge and an HTTP sidecar in front of your code, attached to the project's kernel.Connect an Application
Computer.connect, treatyA federation peer pinned from its partner card, and the intersection of both operators' governance ladders.Federation
reissue, revokeA new token with the same scope on a new fork; a revocation of a token ID, which ends every token delegated from it.Revocation

A grant is a capability token

In step 3 of the Quickstart, fork.grant gave the fixer the workspace, the model route, and two dollars for twenty minutes. The grant object carries the token the kernel checks. Print it.

quickstart.tsquickstart.pysrc/main.rs · in main
// quickstart.ts, after step 3 of the Quickstart
console.log(JSON.stringify(authority.token, null, 2));
Output
{
  "id": "cap-01a8…31f2",
  "issuer": "4f1c…a2e9",
  "subject": "b81e…40c7",
  "scope": {
    "grants": [
      { "server_id": "quickstart", "tool_name": "read", "operations": ["invoke"],
        "constraints": [{ "type": "path_prefix", "value": "/workspace" }] },
      { "server_id": "quickstart", "tool_name": "write", "operations": ["invoke"],
        "constraints": [{ "type": "path_prefix", "value": "/workspace" }] },
      { "server_id": "quickstart", "tool_name": "invoke", "operations": ["invoke"],
        "constraints": [{ "type": "path_prefix", "value": "/models/default" }],
        "max_total_cost": { "units": 200, "currency": "USD" } }
    ]
  },
  "issued_at": 1791763200,
  "expires_at": 1791764400,
  "signature": "a3f9…0d52"
}

Each resource in the grant became tool grants on the computer's server, quickstart, with a path_prefix constraint. /workspace with read and write became two grants; the model route became a third, with the two dollars as max_total_cost of 200 cents, because the model route is the only priced resource. Twenty minutes is the distance from issued_at to expires_at. The subject is the public key behind did:chio:z6MkrT2…8wd, so only the fixer can present the token.

No grant names /secrets, and nothing in the token can be widened without a new signature from your kernel.

A run is a sequence of mediated calls

Each line of run.events() is one operation the fixer attempted, and each attempt reached the kernel as a tool call carrying the token. The refusal at 00:09:

run.events() · fix issue #412text
00:05  read       /workspace/tests/test_pricing.py
00:09  refused    read /secrets/.env: outside the grant
00:12  invoke     /models/default, USD 0.21
The call behind 00:09 · as the kernel received it, with the token shown by its IDjson
{
  "request_id": "req-01a8…77b0",
  "capability": "cap-01a8…31f2",
  "server_id": "quickstart",
  "tool_name": "read",
  "agent_id": "b81e…40c7",
  "arguments": { "path": "/secrets/.env" }
}

The kernel looks for a grant in the token whose server, tool, and constraints cover the call. One grant names the read tool, and its constraint limits paths to /workspace. /secrets/.env falls outside it, so the scope check fails at the authority stage. No guard runs, and nothing opens the file.

The admitted read at 00:05 took the same path and matched the first grant. Its receipt carries the same token ID and policy hash under a different receipt ID.

Read more in The mediated call.

History is the receipt store

In step 5, refusal.describe() printed six lines. The receipt behind them is a signed JSON record in the project's receipt store. Print its canonical bytes.

quickstart.tsquickstart.pysrc/main.rs · in main
// quickstart.ts, after step 5 of the Quickstart
console.log(refusal.raw);
Output
{"action":{"parameter_hash":"5e0d…71c2","parameters":{"path":"/secrets/.env"}},"capability_id":"cap-01a8…31f2","decision":{"reason":"not in capability scope","verdict":"deny"},"evidence":[],"id":"rcpt-01a8…9c04","kernel_key":"4f1c…a2e9","policy_hash":"3c7b…8010","receipt_kind":"mediated_decision","signature":"9d2e…07b4","tool_name":"read","tool_server":"quickstart"}

The same record, laid out by field:

A refusal receiptSelect a field to read what it records.
ρrecord identitykreceipt kindrthe requestvdecision and evidenceκauthority checkedπpolicy in forceσsignerρkrvκπσ

decision and evidence

decision holds the verdict and the kernel’s reason. evidence lists each guard that ran and its verdict. It is empty here because the scope check refused the read before any guard ran. Read more in Guards.

The fixer’s refused read of /secrets/.env from the Quickstart, trimmed to the fields that identify the call, its decision, and its signer, with digests shortened. The complete record also carries a timestamp, a content hash, and metadata; the receipt format lists every field.

Every line of the summary comes from a field. verdict deny: outside the grant is decision.reason, not in capability scope. The grant is capability_id, the policy is policy_hash, and the signer is kernel_key. project.history.receipts() queries this store, and chio receipt list reads the same records from the CLI.

Read more in Receipts.

Policy compiles into the kernel's policy

In step 7, project.policy.add added tests-are-evidence. The SDK compiles each rule into the HushSpec policy the kernel evaluates at admission, beside the defaults every computer starts with.

quickstart.tsquickstart.pysrc/main.rs · in main
console.log(await project.policy.describe());
Output
policy     sha256 9e42…c5d1, was 3c7b…8010
rules      tests-are-evidence   deny write /workspace/tests/**
base       forbidden paths      **/.env, **/.env.*, **/.ssh/** and 27 more
compiled   HushSpec 0.1.0, evaluated at admission

The new hash is the one the second refusal carries. A rule runs after the scope check, which is why the test write, inside the grant, reached it and the secrets read did not. A tool server you run yourself takes the same policy as a YAML file, whose fields the policy schema defines.

Read more in Write a Policy.

A service is an edge and a sidecar

In part 2, pricing.publish served the pricing functions over MCP and HTTP. Each protocol is a serving process with the kernel linked in: the MCP edge checks every tools/call, and the HTTP sidecar maps every request to an operation in the service's OpenAPI document. The outside buyer's grant is a capability token for the quote tool on the pricing server, with a rate limit and a spend ceiling.

The same processes run from the CLI in front of a service you deploy yourself. chio mcp serve-http --computer quickstart and chio api protect --computer quickstart attach to the project's kernel state, so the buyer's grant admits the same calls and the receipts land in the same history.

Read more in Connect an Application.

Partners are federation peers

In part 3, chio partner add pinned your partner's kernel key from its card, and Computer.connect opened the peer. The treaty is the signed intersection of both governance ladders; each kernel computes it on its own. The partner's agents received a token from your kernel under that treaty, delegated narrower tokens to each other, and every call they made in your fork reached your kernel. The merge receipt carries both kernels' signatures.

Revoking the treaty revoked the token issued under it. The kernel checks every ancestor in a token's delegation chain at admission, so the tokens the partner's agents delegated stopped at their next call.

Read more in Treaties and admission.

Work at either level, on the same records

Use the Computer SDK to run agents on a project and serve it to other agents. Work with the kernel directly when you embed it in your own host, put it in front of an API you already run, or operate it across nodes. Both levels sign with the same kernel key and append to the same receipt store, so an evidence export covers work done at either one.

Next: narrow every grant at once

Write a policyAdd a rule that refuses a poisoned dependency fetch in the next issue.CapabilitiesRead the token that bounds what the scope check admits.Embed the kernelLink the kernel into a host you control.

Start Here · 6 of 14

PreviousWork With Their AgentsNextWrite a Policy