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.

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 equal its own, and the op must be allowed on the socket it arrived at:

The framing, problem shapes, and operation tables: spec/control-protocol.md.

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.