SDK Overview

Install

One package per language, from that language's registry. Each one exports the Computer API.

Distributions and imports

The low-level clients ship in the same packages or beside them. These are the exact strings, with the version each manifest declares and the runtime floor it requires.

HTTP interception in application code

A service that keeps its own HTTP stack puts the kernel in front of its routes with a framework adapter. Each excerpt below is your pricing service in that framework, behind the same sidecar: GET /healthz excluded from evaluation, POST /v1/quote allowed for a caller whose grant covers quotes, and POST /v1/refund refused unless the grant names refunds. Each adapter installs from its registry under its own name.

from chio_asgi import ChioASGIMiddleware, ChioASGIConfig

app.add_middleware(
    ChioASGIMiddleware,
    config=ChioASGIConfig(
        sidecar_url="http://127.0.0.1:9090",
        exclude_paths=frozenset({"/healthz"}),
    ),
)

import { chio } from "@chio-protocol/express";

app.use(
  chio({
    sidecarUrl: "http://127.0.0.1:9090",
    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("/v1/quote", "/v1/refund")
            order = Ordered.HIGHEST_PRECEDENCE
        }
    }

using Backbay.Chio;

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

var app = builder.Build();
app.UseChioProtection();

app.MapPost("/v1/quote", (QuoteRequest request) => Pricing.Quote(request.Sku, request.Percent));
app.MapPost("/v1/refund", (RefundRequest request) => Pricing.Refund(request.Order));

app.Run();

What a refusal returns

A refusal is a record. The two middlewares that front an application, the Python ASGI one and the Node interception layer every JavaScript adapter shares, both answer a denied request with a JSON body and a receipt id on a response header.

The ASGI status is the receipt verdict's own HTTP status when it carries one and 403 otherwise. The Node layer sends chio_access_denied on a deny and chio_invalid_receipt with status 502 when the sidecar answers with a receipt that fails verification. Both paths fail closed.

Choose an SDK

Choose the language that already hosts your application, then the package that matches its enforcement boundary. Core verification libraries and framework adapters expose different APIs.

The common verification vocabulary is defined by the Bindings API, the low-level binding contract: canonical JSON, hashing, signing, receipt and capability and manifest verification, delegation chains, Merkle proofs, and the stable error taxonomy. Read it if you are porting to a new language or writing an offline verifier.

Shared functionality

Every SDK carries the Computer API. Beneath it, the TypeScript, Python, and Go packages carry MCP clients and sessions, and Rust’s binding helpers provide local verification. The JVM and .NET low-level clients are sidecar clients: they evaluate, verify, and filter HTTP requests, and they open no MCP session.

• Computer API. Computer.open, fork, grant, run, history, policy, service, and treaty, with the same semantics in every language.
• Invariants. Pure functions for canonical JSON, SHA-256, Ed25519, and verification of receipts, capabilities, and signed manifests. They make no network call.
• Transport. Streamable HTTP MCP transport with an explicit session lifecycle.
• Client and session. Opening a session against a Chio edge and calling tools over it.
• Receipt query. A typed client over GET /v1/receipts/query with pagination. From Go or Rust, call the endpoint directly.
• DPoP proof signing. signDpopProof builds and signs a proof bound to a capability, a tool, and an action-argument hash. The Python sidecar client accepts a caller-supplied dpop_proof on pre-execution evaluation but constructs none. Signing a proof does not attach it to a hosted MCP call.
• Cognition market. Buyer, seller, and hosted clients for the Finding market, plus the buyer-local bid ceiling.

Platform SDKs

Two integrations govern infrastructure rather than application code. Neither calls the sidecar over POST /chio/evaluate.

• chio-tower. A Rust tower::Layer that wraps any Tower or Axum HTTP service and runs the kernel in process. It exports ChioLayer, ChioService, ChioEvaluator, EvaluationResult, ChioTowerError, extract_identity, IdentityExtractor, DEFAULT_MAX_BODY_BYTES, and the KernelService stack (build_layered, KernelTraceLayer, TenantConcurrencyLimitLayer, TenantId). It fails closed.
• Kubernetes controller and webhooks. The controller watches Jobs labeled chio.world/governed: "true", reads the requested scopes off chio.world/scopes, mints a capability grant at creation, writes chio.world/capability-id, chio.world/capability-token, and chio.world/capability-expires-at onto the pod template, holds the Job with the chio.world/capability-finalizer finalizer, and harvests the chio.world/receipt annotations the sidecar posted. The validating webhook admits a pod only when the token on chio.world/capability-token verifies against the operator's configured trust set, and it denies any pod that carries chio.world/required-scopes or chio.world/exempt, because a workload must not set its own policy. The mutating webhook runs the same verification and emits no patch. A namespaced ChioPolicy custom resource in the chio.world group carries the operator's policy.

Everything under sdks/

Most directories under sdks/ hold one language. Three do not: guard/ holds the WASM guard guest SDKs, which are built out of tree and loaded as components rather than linked as host clients; k8s/ holds the Kubernetes controller, its custom resource, and the admission webhooks; and lambda/ holds the AWS Lambda pair. Every package, module, and project the manifests declare appears below.

The C++ and Swift references cover those packages.

Source

Package names, versions, imports, dependencies, and runtime floors come from the SDK manifests. The public SDK tree contains the implementations; examples/ contains the worked applications.

The Bindings API defines the shared verification contract; the Protocol Reference defines the wire semantics.

Cross-language conformance

TypeScript, Python, Go, and Rust run the same conformance vectors: canonical JSON, hashing, signature verification, receipt parsing, capability parsing, and manifest parsing. Rust is the reference, and the other three produce byte-identical output against its vectors. The JVM SDK asserts the same byte-equality under a parity JUnit tag on canonical JSON, the DLQ router, and synthetic deny receipts.

Signed protocol records use RFC 8785 canonical JSON. Fixture parity applies to the tested inputs and does not establish that every SDK serializer has the same contract. The JVM streaming serializer, for example, follows its Python-compatible escaping rules. The Bindings API carries the binding contract; each language reference names its supported verification surface.

The installed CLI runs the corpus against the published packages:

chio conformance run --peer all

Related