How Akson is built.

This page is the technical map. The normative source of truth is the design document (§ references below point into it) and the threat model; the state machines drawn here are also model-checked against the code.

The system, drawn

Everything lives in aksond. Peers reach it over pinned mTLS; the operator reaches it over a Unix socket; a model is reachable only through the broker.

Three structural choices do most of the security work:

• The receive path cannot act. The function that accepts a proposal is handed a database handle and nothing else — no transport, no processor client, no filesystem, no worker. "Arrival is not execution" is not a policy check that could be forgotten; the capability to do anything else simply is not in scope. (§6.3)
• Authority is constructed, not inherited. Approving a task issues a one-shot work order carrying an explicit capability vector. The worker is built from nothing to match exactly that grant — rather than built powerful and then restricted. (§12.3)
• Every effect is durable first. The store commits running/dispatching before the first byte of any effect leaves. Crash recovery marks anything mid-flight ambiguous — reported as uncertain, never retried automatically, never claimed done. (§13.1, §15.5)

One task's life

Twelve steps, in order, with the commit points where they belong. (§7.2)

1. The network endpoint authenticates the peer's pinned certificate before reading a request body.
2. Connection, content-length, rate, and parse limits are enforced.
3. The standard A2A object and the recognized Akson extension are validated.
4. The encrypted object and its stable digest are stored transactionally.
5. The A2A response is returned only after the durability commit — a receipt you can hold the sender to.
6. A human (or a standing policy, for non-disclosing work) evaluates the exact immutable contract revision — the risk card.
7. Contract acceptance is signed separately from local authorization.
8. The local issuer creates a one-shot work order for a clean executor.
9. The executor receives only the selected input manifest and typed capabilities.
10. Results pass through size, media-type, recipient, and schema gates.
11. The evidence engine signs statements over the exact inputs, attempt, outputs, and verifier results.
12. The requester validates the bundle independently and signs its own outcome.

Execution is tracked as an attempt with a small, closed state machine — the same one the TLA+ model checks against the code:

The two permission domains

Your authority and a peer's grant never share a mechanism — different sockets, different keys, different processes, different rules.

Akson's core principle is that a peer's commands run in a separate, enforced, reduced-authority domain, and your own user-granted authority is never touched. Four mechanisms realize it:

The sandbox, layer by layer

Defense in depth, each layer independent, all of it probed by akson doctor and refused rather than degraded. (§13.1)

The broker: processor calls are effects

Sending plaintext to a model discloses data and costs money — so every call is a durable sub-attempt with the same crash honesty as execution itself.

The confined worker inherits exactly one already-connected file descriptor. It writes a typed request; the daemon makes the real HTTPS call. On the daemon's side of that descriptor, the broker enforces:

• The approved processor and budgets — bound into the one-shot work order at approval. The broker snapshots that processor's currently configured origin when dispatching, so a configuration change between approval and dispatch is an acknowledged gap rather than a bound value;
• An egress allowlist and address re-check — https only, the resolved address re-validated before dialing (global unicast unless a local processor opted in), redirects and ambient proxies disabled — so neither a task nor a DNS rebind can choose a different destination;
• Credential injection — the API key is added daemon-side and never enters the worker's domain;
• A budget — a per-work-order operation count, response-size cap, and wall-clock limit, counted in the same transaction that admits the call.

prepared ──> dispatching ──> completed | failed | ambiguous | cancelled

durable-before-wire: "dispatching" commits before the first byte leaves.
a crash mid-call resolves to ambiguous — possible disclosure and cost are
reported to the operator, and never silently retried.

Evidence and outcomes

A result is not "some bytes arrived" — it is a signed claim the requester re-verifies from scratch before recording anything.

When the performer delivers, two things travel: the output bytes, and a canonical result manifest naming each output with its role, media type, size, and SHA-256 — signed as a DSSE envelope (§14.1–14.2). Findings use plain SARIF, validated against the profile before they are emitted, so a model answering with malformed or oversized findings fails closed on the performer's side.

The requester's daemon then re-verifies the claim independently: the delivery must match an outstanding request, verify under the performer's pinned task-result key, and every output the manifest names must re-hash to the digest it signs. One missing output, one altered byte, one extra part — the whole delivery is refused before anything is recorded (T8). Only then does the requester sign its own outcome, a durable disposition grounded in the verified bundle (§14.5). Two honest limits, tracked in the threat model: the manifest is not yet cross-checked against the contract's declared deliverables, and referenced in-toto evidence bytes are not delivered or independently verified in v1.

Before any renderable artifact leaves the performer, it is checked inert: SVG, HTML, Markdown, Mermaid, and Graphviz outputs are refused if they carry scripts, event handlers, script-bearing data URIs, external fetches, or DOCTYPE/ENTITY declarations (§11, T4). That is defense in depth for the supported renderable types — not a warranty for arbitrary media or a vulnerable viewer.

First contact

The pinned mTLS the rest of this page assumes has to be established somehow. It is established out of band, by a public token — never by a bearer secret on the wire. (§8.2, ADR-0013/0015)

Each endpoint has one identity token: a printable, QR-able line (akson1…, bech32m) that commits to its identity root key — the key that signs its Agent Card. The token is public: possession grants nothing, so it travels over any channel whose integrity you trust, needing no confidentiality. Two operators exchange tokens and each runs akson peer add <token> <label> — the import is the whole trust decision, and the label is a local name you choose, never one the peer declares.

A relationship is keyed by the root's thumbprint, not by the self-declared name, so two peers who both call themselves claude simply coexist. On first connection the two daemons run the introduction: a mutual, fail-closed verification bound to that TLS session (RFC 9266 exporter), in a fixed order so a hijacked endpoint learns nothing.

From then on the identity is everything downstream binds to: the signed contract carries each party's root (ADR-0014), and the receiver refuses a proposal whose signed requester root does not match the channel it arrived on. There is no invitation, no bearer secret, no pending-confirm dance — deleted, along with AKSON_PAIR_ADDR and its listener. The public /.well-known/agent-card.json is the one surface an unimported stranger may read; it is display-only until an introduction verifies it against a root you imported.

The wire

Standard A2A 1.0 where a standard exists; a small, versioned extension surface where Akson needs stronger promises. (§3, §10)

The control plane

The CLI, the MCP server, and any client you write all speak one tiny protocol to the daemon: one JSON line in, one JSON line out, over a Unix socket.

printf '{"op":"who_am_i"}\n' | socat - UNIX-CONNECT:"$XDG_RUNTIME_DIR/akson/admin.sock"
# {"outcome":"ok","result":{"issuer":"orgB","agent":"bob", …}}

Every exchange has that shape; akson whoami is exactly this request. The daemon checks two things before running any op: the connecting process's UID (via SO_PEERCRED) must be one that socket admits — the rule is per-socket, not one rule for all three — and the op must be allowed on the socket it arrived at:

Dominance is deliberately asymmetric: an admin connection may invoke the narrow surfaces' ops (so an operator can diagnose them without a second account), while worker and coord dominate nothing — including each other. And admission is a UID, never an attested process identity: SO_PEERCRED says which user connected, not which program. That is the developer assurance profile, and the default profile has no UID separation in it at all — separate identities per role are an opt-in fleet arrangement.

Because a different principal sits on the coordination socket, its request line is bounded at 1 MiB; admin and worker are the daemon's own UID and stay unbounded. Connections on each socket are served concurrently, up to 16 at a time — beyond that the next is served on the accept thread, so the socket serialises rather than refusing anyone. Within the ceiling, an op that blocks on the network — dispatch carries bytes to a pinned peer — delays only itself rather than the whole surface.

The framing, problem shapes, and operation tables: spec/control-protocol.md. The coordination surface in full — the registry, the envelope, the receiver's checks, and its limits — is its own page.

The crate map

A workspace of small crates, each owning one concern — the boundaries in the code mirror the boundaries in the design.

Beyond the runtime crates: proof/ holds the TLA+ models, and its conformance harness is itself a workspace member so plain cargo test --workspace runs it (see Proofs); xcheck/ is the independent Python cross-checker (deliberately not sharing the workspace); fuzz/ carries the contract, I-JSON, and SARIF fuzz targets; spec/ the golden vectors, control protocol, and ADRs.