Examples Overview · Chio Docs

Choose your example

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

"I want to see one governed call with the smallest setup" 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

Example pages use the same four sections:

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.
Success criteria. The exact assertions in smoke.sh that decide whether the run passed. Status codes, JSON fields, header values, exit codes.
Inspect after.commands you run after the smoke passes to confirm state landed: cat .artifacts/.../bridge-call.json, chio receipt list, header extraction. Commands include expected output.
Decision rule. A short callout that says when to use the example and which sibling to use instead.

Getting the source

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

bash

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 supported flows.

Run a single smoke

From examples/ the runner ./run-hello-smokes.sh --list prints every smoke target. Pass names to run a subset: ./run-hello-smokes.sh hello-fastapi hello-fastify. Run with no arguments to execute the full set.

Integration matrix

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

Example	Kind	Integration covered	Page
`hello-tool`	Native service	`NativeChioServiceBuilder`, signed manifests, manifest pricing	Hello Tool
`hello-mcp`	Protocol edge	MCP edge over stdio JSON-RPC, kernel-mediated `tools/call`	Hello MCP
`hello-a2a`	Protocol edge	A2A edge with deferred task lifecycle	Hello A2A
`hello-acp`	Protocol edge	ACP invoke plus stream/resume	Hello ACP
`hello-openapi-sidecar`	HTTP sidecar	`chio api protect` with OpenAPI	OpenAPI Sidecar
`hello-fastapi`	HTTP framework	`chio-asgi`, `chio-fastapi`	Python HTTP
`hello-django`	HTTP framework	`chio-django` middleware	Python HTTP
`hello-express`	HTTP framework	`@chio-protocol/express`	Node HTTP
`hello-fastify`	HTTP framework	`@chio-protocol/fastify`	Node HTTP
`hello-elysia`	HTTP framework	`@chio-protocol/elysia`	Node HTTP
`hello-chi`	HTTP framework	`chio-go-http`	Go and C++ HTTP
`hello-spring-boot`	HTTP framework	`chio-spring-boot` servlet filter	JVM and .NET HTTP
`hello-dotnet`	HTTP framework	`ChioMiddleware` for ASP.NET	JVM and .NET HTTP
`hello-drogon`	HTTP framework	`chio::drogon::ChioMiddleware`	Go and C++ HTTP
`hello-trust-control`	Control-plane adjunct	Capability lifecycle, `chio check`, `chio evidence verify`	Trust Control
`hello-receipt-verify`	Control-plane adjunct	Offline evidence verification, tamper detection	Receipt Verification
`docker`	Quickstart topology	`trust serve` + hosted MCP edge + receipt dashboard	Upstream only
`anthropic-sdk`	Ecosystem client	Claude tool use over hosted Chio session	LangChain and Provider SDKs
`openai-compatible`	Ecosystem client	OpenAI function calling over hosted Chio session	LangChain and Provider SDKs
`langchain`	Ecosystem client	Python Chio SDK with LangChain `StructuredTool`	LangChain and Provider SDKs
`guards/tool-gate`	Guard example	`chio-guard-sdk` verdict logic	Building Guards
`guards/enriched-inspector`	Guard example	Enriched WASM guard with host functions	Building Guards
`cross-provider-policy`	Policy demo	One policy evaluated across eight native provider adapters (OpenAI, Anthropic, Bedrock, Gemini, Mistral, Groq, Ollama, Cohere)	Cross-Provider Policy
`otel-genai`	Observability integration	`gen_ai.tool.call` span and signed receipt bidirectional lookup	OpenTelemetry
`istio-ext-authz`	Mesh integration	`chio-envoy-ext-authz` gRPC adapter behind an Istio CUSTOM `AuthorizationPolicy`	Istio ext_authz
`agent-commerce-network`	Multi-organization workflow	Multi-party economic workflow: approvals, budgets, settlement, disputes	Agent Commerce Network
`internet-of-agents-incident-network`	Multi-organization workflow	Recursive cross-org delegation with OpenAI SDK orchestration, MCP, ACP	Incident Network
`internet-of-agents-web3-network`	Multi-organization workflow	Four-org Chio-mediated commerce with RFQ routing and web3 settlement	Web3 Network

Recommended order

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

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

The hello contract

Each hello-* example uses the same structure:

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

Directories use this layout:

text

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 CI pipeline, include those helpers 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.

examples/docker

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: examples run 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.

Quickstart: install the CLI and run a single tool call.
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.