Examples Overview

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.

One contract, every stack

Nine of the examples are the same application written nine times: hello-fastapi, hello-django, hello-express, hello-fastify, hello-elysia, hello-chi, hello-spring-boot, hello-dotnet, and hello-drogon. Each serves GET /healthz, GET /hello, and POST /echo against the same EchoRequest schema, behind the same sidecar. Only the registration line changes.

    if enable_chio:
        app.add_middleware(
            ChioASGIMiddleware,
            config=chio_config or build_chio_config(),
        )

  if (enableChio) {
    app.use(
      chio({
        sidecarUrl,
        skip: ["/healthz"],
      }),
    );
  }

func protectedHandler(sidecarURL string) http.Handler {
	return chio.Protect(
		newRouter(),
		chio.WithSidecarURL(sidecarURL),
	)
}

    @Bean
    fun chioFilterRegistration(): FilterRegistrationBean<ChioFilter> {
        val filter = ChioFilter(
            ChioFilterConfig(
                sidecarUrl = System.getenv("CHIO_SIDECAR_URL") ?: "http://127.0.0.1:9090",
            ),
        )

        return FilterRegistrationBean<ChioFilter>().apply {
            setFilter(filter)
            addUrlPatterns("/hello", "/echo")
            order = Ordered.HIGHEST_PRECEDENCE
        }
    }

        var builder = WebApplication.CreateBuilder(args);
        builder.Services.AddChioProtection();

        var app = builder.Build();
        app.MapGet("/healthz", HelloEndpoints.Health);
        app.UseWhen(
            context => RequiresChioProtection(context.Request.Path),
            branch => branch.UseChioProtection());

void configure_chio_from_env() {
  chio::drogon::Options options;
  options.sidecar_url = env_or_default("CHIO_SIDECAR_URL", "http://127.0.0.1:9090");
  options.sidecar_failure_mode = chio::drogon::SidecarFailureMode::FailClosed;
  chio::drogon::configure(std::move(options));
}

Everything downstream of that line is shared, including the policy, and the way it is shared is worth being precise about. Eight of the nine ship a policy.yaml next to the app, in two byte sequences that differ by one trailing blank line; hello-chi ships none. Nothing reads any of them. chio api protect has no policy option of any kind, no runner or smoke passes one, and repo-wide those eight files appear only in their own READMEs' file listings. So all nine inherit the same sidecar default, and the file is there as a starting point to edit rather than as the thing in force:

kernel:
  max_capability_ttl: 3600

capabilities:
  default:
    tools:
      - server: "*"
        tool: "*"
        operations: [invoke]
        ttl: 900

What actually governs the nine is the sidecar's method default. Safe methods get a session-scoped allow and side-effect methods are denied until a capability arrives, which is why GET /hello passes and POST /echo does not, in every one of them, with no policy file present:

pub fn for_method(method: HttpMethod) -> PolicyDecision {
    if method.is_safe() {
        PolicyDecision::SessionAllow
    } else {
        PolicyDecision::DenyByDefault
    }
}

The command that puts the kernel in front of the app is byte-identical in all nine smoke.sh scripts:

(
  export CHIO_TRUSTED_ISSUER_KEY="${TRUSTED_ISSUER_KEY}"
  exec "${CHIO_BIN}" \
    --control-url "${CONTROL_URL}" \
    --control-token "${SERVICE_TOKEN}" \
    api protect \
    --upstream "${APP_URL}" \
    --spec "${EXAMPLE_ROOT}/openapi.yaml" \
    --listen "127.0.0.1:${SIDECAR_PORT}" \
    --receipt-store "${RECEIPT_STORE}"
) >"${LOG_DIR}/sidecar.log" 2>&1 &

So the choice of language decides which page you read, not which features you get. Each of them refuses POST /echo without a capability, and the refusal belongs to the sidecar rather than to the application, so the receipt names the same guard, CapabilityGuard, and carries the same reason, side-effect route requires a capability token.

What does differ is the JSON envelope that reason arrives in, and it varies by SDK family rather than by language. The six that sit on a shared substrate ( hello-express, hello-fastify, hello-elysia, hello-chi, hello-spring-boot, hello-dotnet) return four keys, error, message, receipt_id, suggestion. The two Python middlewares each shape their own. That is eight of the nine. hello-drogon is the fourth shape: the C++ SDK builds the body by hand and emits error, message and, only when the receipt id is non-empty, receipt_id, with no suggestion key at all (sdks/cpp/chio-drogon/src/drogon.cpp:358-376).

{"error":"chio_access_denied","message":"side-effect route requires a capability token","receipt_id":"e653e2621575a9e38e030e8e13bc9c05803eb95db8c1ccdd15652b9df0ca4078","suggestion":"provide a valid capability token in the X-Chio-Capability header or chio_capability query parameter"}

{"error": "CapabilityGuard", "message": "side-effect route requires a capability token", "status": 403}

{"error": {"code": "CHIO_GUARD_DENIED", "message": "side-effect route requires a capability token", "guard": "CapabilityGuard"}}

Read the deny body from the page for your stack, not from a sibling. The receipt behind it is one shape everywhere, and that is the thing an auditor reads.

How to read these pages

Example pages use the same four sections:

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.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.
4. 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. Clone the repo, build the workspace once, then run any example from its directory.

git clone https://github.com/bb-connor/arc.git
cd arc
cargo build --workspace
cd examples/hello-tool

What an example directory holds varies, so read its own run path from the matrix below rather than assuming. The long-lived service examples ship a runner (run.sh, run-edge.sh, or run-trust.sh) and a smoke script (smoke.sh), and the one-shot ones do not: hello-tool is a Cargo crate with a README, an ARCHITECTURE.md and src/ and nothing else, hello-receipt-verify has a smoke and no runner, and the two guard examples and bilateral-invocation are crates you build.

Integration matrix

Every row below is read out of examples/EXAMPLE_SURFACE_MATRIX.md upstream, so the example name, its kind, and the surfaces it teaches are the matrix's own words rather than a copy of them. There are 33 examples in the matrix. 27 of them have a page in this section, 3 are written up elsewhere in these docs, and 3 have no page at all: read those upstream from the run path in their own directory.

The 3 with no page are bilateral-invocation, eval-receipt-ingest, tee-sidecar. Each ships a README at its own run path, and the matrix row above is the whole of what these docs currently say about it.

Recommended order

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 protocol examples.
6. hello-tool when you want to move from wrapped adapters to a native Chio service.
7. The multi-organization examples once the entries above are familiar.

The hello contract

The nine HTTP examples, the three protocol edges, and hello-openapi-sidecar use the same structure:

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.

The three remaining hello-* examples do not. hello-trust-control drives the trust plane with no app in front of it, hello-receipt-verify verifies a captured evidence package offline and has no runner, and hello-tool is a Cargo crate with no runner and no smoke at all.

The thirteen that do follow it use this layout:

hello-<surface>/
  README.md
  ARCHITECTURE.md
  run.sh, run-edge.sh, or run-trust.sh
  smoke.sh
  openapi.yaml    # the nine HTTP examples and hello-openapi-sidecar
  policy.yaml     # eight of the nine; hello-chi ships none and nothing reads any
  the app itself  # app.py, server.mjs, main.go, main.cpp, 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.

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.

Next

• 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.