Examples Overview

The examples/ tree teaches Chio one surface at a time. Small hello-* examples isolate a single integration shape; flagship examples compose them into multi-org workflows. This page is the index.

Choose your example

Pick the page that matches the question you're actually asking:

• "I want to see one governed call, end to end, with the smallest moving parts" go to Hello Tool (native Rust service, no protocol, no HTTP).
• "I have an MCP server and want to govern it" go to Hello MCP (stdio JSON-RPC edge with a bridge call that prints the receipt id).
• "I run Express, Fastify, or Elysia (Bun)" go to Node HTTP Frameworks.
• "I run FastAPI or Django" go to Python HTTP Frameworks.
• "I run Spring Boot or ASP.NET Core" go to JVM and .NET HTTP Frameworks.
• "I run Go (chi, gorilla, net/http) or C++ (Drogon)" go to Go and C++ HTTP Frameworks.
• "I want zero code change, just put a sidecar in front of an existing OpenAPI service" run examples/hello-openapi-sidecar upstream and read Protect an API.
• "I want to verify a receipt offline, with no kernel running" run examples/hello-receipt-verify upstream.
• "I want a multi-org topology with budgets, settlement, and disputes" run examples/agent-commerce-network upstream.

How to read these pages

Every example page in this section follows the same four-part shape so you can scan any of them in under two minutes:

1. Walkthrough. The shape of the example: what it builds, what it wires together, and the few lines of code or config that do the work.
2. Success criteria. The exact assertions in smoke.sh that decide whether the run passed. Status codes, JSON fields, header values, exit codes.
3. Inspect after. Concrete commands you run after the smoke passes to confirm state landed: cat .artifacts/.../bridge-call.json, chio receipt list, header extraction, and so on. Every command shows expected output.
4. Decision rule. A short callout that says when to use the example and which sibling to use instead.

Getting the source

Every example lives in the upstream chio repo (working name chio). Clone the repo, build the workspace once, then run any example from its directory.

git clone https://github.com/backbay-labs/chio.git
cd chio
cargo build --workspace
cd examples/hello-tool

Each example ships with a README.md, a runner (run.sh, run-edge.sh, or run-trust.sh), and a smoke script (smoke.sh) that exercises the supported flows end-to-end.

Surface matrix

Each example teaches a specific Chio surface. Use this table to find the example that matches the integration shape you need.

Recommended order

The repo lists a supported sequence for new users. Pick the entry point that matches your stack.

1. hello-openapi-sidecar for the zero-code reverse-proxy shape.
2. hello-fastapi for the first framework-native follow-on.
3. One additional HTTP framework hello that matches your stack.
4. hello-trust-control and hello-receipt-verify for the control-plane and evidence model.
5. hello-mcp, hello-a2a, or hello-acp for the protocol surfaces.
6. hello-tool when you want to move from wrapped adapters to a native Chio service.
7. The flagship examples once the surfaces above are familiar.

The hello contract

Every hello-* example converges on the same shape so you can read any of them quickly:

1. One safe read path (GET /hello or a discovery call).
2. One governed path (POST /echo, tool/invoke, or message/send).
3. A deny path without a capability token.
4. An allow path with a trust-issued capability token.
5. At least one Chio receipt or receipt id captured in the response.
6. A single smoke.sh that runs all of the above.

Directory layout is consistent too:

hello-<surface>/
  README.md
  policy.yaml or config/
  run.sh or run-edge.sh
  smoke.sh
  app/ or src/

Shared helpers

The HTTP framework smokes share Bash helpers in examples/_shared/hello-http-common.sh for picking free ports, waiting for HTTP endpoints, and starting a local chio trust service plus chio api protect sidecar. If you copy a smoke into a real CI pipeline, lift those helpers along with it.

Docker quickstart topology

For a containerized smoke that you can hand to a teammate, use examples/docker/. It builds two images from the repo root Dockerfile targets and runs them with one compose command.

docker compose up -d --build
python3 smoke_client.py
# open http://127.0.0.1:8940/?token=demo-token to view the receipt
docker compose down -v

The compose file starts chio trust serve with the receipt dashboard on 127.0.0.1:8940 and chio mcp serve-http on 127.0.0.1:8931. The smoke script performs one governed echo_text call through the hosted edge, queries the receipt from the trust service, and prints the viewer URL.

Platform notes

• Linux and macOS: every example runs on both. The smokes assume bash, python3, curl, and jq are on PATH.
• Drogon: hello-drogon needs CMake and the Drogon C++ framework installed. Both run.sh and smoke.sh skip with a clear message when CMake or Drogon is missing.
• JVM: hello-spring-boot uses the Gradle wrapper; you need a JDK on the path.
• .NET: hello-dotnet requires the .NET SDK that the HelloChio.csproj targets.
• Python: hello-fastapi and hello-django are managed with uv. Their run.sh scripts call uv run directly.

Next

• Quickstart: install the CLI and run a single tool call end-to-end.
• Hello Tool: the simplest native Chio service.
• Hello MCP: authoritative MCP edge over stdio.
• Node HTTP Frameworks, Python HTTP Frameworks, JVM and .NET, Go and C++: stack-specific walkthroughs.