Quick Start · Chio Docs

1. Install the CLI

Chio ships as a single binary. Install it with the hosted installer:

bash

$ curl -fsSL https://www.chio.world/install.sh | sh

Or install with Cargo if you already have Rust:

bash

$ cargo install chio

Verify the installation:

bash

$ chio --version
chio-cli 0.1.0

SDK alternatives

If you prefer to embed Chio directly in your application, use one of the language SDKs instead: @chio-protocol/sdk (TypeScript), chio-sdk (Python), chio-go (Go), or the chio-core crate (Rust). The CLI is the fastest way to get started.

2. Write a minimal policy

A policy pins the guard rules; a capability scopes the agent. Create a policy.yaml that allows reading files under a project directory and not much else:

policy.yaml

hushspec: "0.1.0"
name: workspace-readonly

rules:
  # Only allow access to files under ./workspace
  path_allowlist:
    enabled: true
    read:
      - ./workspace/**

  # Block access to secrets and credentials
  forbidden_paths:
    enabled: true
    patterns:
      - "**/.env"
      - "**/*.pem"
      - "**/credentials*"

  # Limit to read-only filesystem tools
  tool_access:
    enabled: true
    default: block
    allow:
      - read_file
      - list_directory
      - search_files

  # No shell commands
  shell_commands:
    enabled: false

  # No network egress
  egress:
    enabled: true
    allow: []

  # Cap invocations
  velocity:
    enabled: true
    max_invocations: 100
    window_seconds: 60

  # Validate patches (auto-enabled)
  patch_integrity:
    enabled: true

  # Scan for leaked secrets
  secret_patterns:
    enabled: true

These rules are conjunctive: a deny from one enabled rule denies the call.

3. Check a single tool call

Before running a live server, you can dry-run a tool invocation against your policy using chio check:

bash

# This should be ALLOWED: reading a file under ./workspace
$ chio check --policy ./policy.yaml \
    --tool read_file --server srv-files \
    --params '{"path": "./workspace/README.md"}'

verdict:    ALLOW
tool:       read_file
server:     srv-files
receipt_id: rcpt-019dbbf8-33db-7f21-81c7-aab0427616c8
policy:     a40c24d0930d773e060fac86dd77e24e68af4cb0a59b1b836759ed63fbaa23b8
source:     d14550004f854d4131839bd2388b3ec9aa3784c898a47f261d434bffbc88d799
mode:       preflight
fixture:    false

bash

# This should be DENIED: reading a .env file
$ chio check --policy ./policy.yaml \
    --tool read_file --server srv-files \
    --params '{"path": "./workspace/.env"}'

verdict:    DENY
tool:       read_file
server:     srv-files
reason:     guard denied the request: guard "forbidden-path" denied the request: path matches forbidden pattern **/.env
receipt_id: rcpt-019dbbf8-3405-74b2-86b5-07ac94779b39
policy:     a40c24d0930d773e060fac86dd77e24e68af4cb0a59b1b836759ed63fbaa23b8
source:     d14550004f854d4131839bd2388b3ec9aa3784c898a47f261d434bffbc88d799
mode:       preflight
fixture:    false

bash

# This should be DENIED: tool not in the allowlist
$ chio check --policy ./policy.yaml \
    --tool write_file --server srv-files \
    --params '{"path": "./workspace/output.txt", "content": "hello"}'

verdict:    DENY
tool:       write_file
server:     srv-files
reason:     requested tool write_file on server srv-files is not in capability scope
receipt_id: rcpt-019dbbf8-33ef-7dc3-9143-25968ddd18e9
policy:     a40c24d0930d773e060fac86dd77e24e68af4cb0a59b1b836759ed63fbaa23b8
source:     d14550004f854d4131839bd2388b3ec9aa3784c898a47f261d434bffbc88d799
mode:       preflight
fixture:    false

Denial details

The command reports the guard that denied a call and the associated reason.

Exit codes for scripting

chio check exits 0 on an allow, 2 on a deny, and 3 when the call needs human approval. Branch on the exit status rather than treating every non-zero code as a crash: a clean deny is expected policy behavior, not an error.

4. Wrap an MCP server

Now run an MCP server through Chio. This example wraps the official filesystem MCP server:

bash

$ chio --receipt-db ./receipts.sqlite mcp serve \
    --policy ./policy.yaml --server-id srv-files \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace

Chio starts the MCP server as a subprocess and intercepts its tool calls. Your agent connects to Chio as it would to any MCP server. The top-level --receipt-db flag persists each decision to ./receipts.sqlite so you can inspect them in the next step.

Any MCP server works

Chio is server-agnostic. Swap in any MCP server (databases, APIs, browsers) and the same policy governs all tool calls through it.

5. View receipts

After your agent makes a few tool calls, inspect the cryptographic receipt log:

bash

$ chio --receipt-db ./receipts.sqlite receipt list --admin-all \
    --tool-server srv-files --limit 3

{"id":"rcpt-019dbbf8-4cfe-...","timestamp":1776975105,"capability_id":"cap-019dbbf8-4cdd-...","tool_server":"srv-files","tool_name":"read_file","action":{"parameters":{"path":"./workspace/README.md"},"parameter_hash":"a3c8a200..."},"decision":{"verdict":"allow"},"content_hash":"42e9fd40...","policy_hash":"a40c24d0...","kernel_key":"25403c1e...","signature":"7be63cdb..."}
{"id":"rcpt-019dbbf8-4d46-...","timestamp":1776975105,"capability_id":"cap-...","tool_server":"srv-files","tool_name":"read_file","action":{"parameters":{"path":"./workspace/.env"},"parameter_hash":"..."},"decision":{"verdict":"deny","reason":"guard \"forbidden-path\" denied the request","guard":"forbidden-path"},...}
{"id":"rcpt-019dbbf8-4d78-...","timestamp":1776975106,"capability_id":"cap-...","tool_server":"srv-files","tool_name":"list_directory","action":{"parameters":{"path":"./workspace"},...},"decision":{"verdict":"allow"},...}

The default output is JSON Lines (one receipt per line). Pipe to jq for summaries or filter by server, tool, outcome, or cost using the flags on chio receipt list --help.

Local reads against a --receipt-db fail closed: pass --admin-all to read every tenant's receipts, or --tenant <id> to scope the read to one tenant. The two flags are mutually exclusive, and omitting both is an error.

Each receipt is cryptographically signed. It records the request, decision, and guards evaluated. Verify the signature before relying on a receipt as evidence.

Receipts are append-only

Once a receipt is committed, it cannot be modified or deleted. The append-only log ensures any tampering is detectable. Export receipts to external storage for long-term retention.

What just happened

You wrapped an existing MCP server without changing its code. Calls that pass through Chio produce signed receipts that security and finance teams can inspect. Similar integrations are available for other MCP servers, A2A endpoints, and HTTP APIs behind Envoy. Adapt the policy to the workload you govern.

Next steps

Explore the full capabilities of Chio:

Architecture: understand the kernel, guard pipeline, and trust model
Capabilities: scoped, time-bounded, delegatable authority
Policy Schema: full guard configuration options
Receipts: cryptographic audit trail deep dive

PreviousIntroduction NextInstallation