Protected native hosts

1. Start the edge in front of the filesystem server

chio mcp serve-http wraps a stdio MCP filesystem server behind a kernel-mediated edge. Its signed cage policy pins the wrapped command's absolute path and exact arguments; the edge resolves the command on PATH, canonicalizes it, and refuses to start unless both match.

# Replace every quoted <placeholder>. Both signers are bare 64-character hex Ed25519 public keys.
export CHIO_AUTH_TOKEN='<session-bearer>'
export CHIO_ADMIN_TOKEN='<distinct-admin-bearer>'
chio --session-db /srv/larkfield/edge/sessions.sqlite \
  --receipt-db /srv/larkfield/edge/receipts.sqlite \
  --authority-db /srv/larkfield/edge/authority.sqlite \
  mcp serve-http \
  --policy /srv/larkfield/edge/filesystem-policy.yaml \
  --server-id workspace \
  --signed-manifest /srv/larkfield/edge/workspace-manifest.signed.json \
  --manifest-public-key '<manifest-signer-64-hex>' \
  --cage-policy /srv/larkfield/edge/workspace-cage-policy.json \
  --cage-policy-signer '<cage-policy-signer-64-hex>' \
  --resume-hmac-keyring /srv/larkfield/edge/resume-hmac-keyring.json \
  --shared-hosted-owner \
  --listen 127.0.0.1:8931 \
  -- /opt/mcp/bin/mcp-server-filesystem /srv/larkfield/pricing
# The signed cage policy pins this canonical command path and these exact arguments.

The edge serves on 127.0.0.1:8931. Once the policy's migration stage is enforced, the kernel launches the server inside a cage that confines it to what the policy grants, whatever the host asks for; stages before enforcement launch it without the cage, as shadow migration describes. The cage runs on Linux, and so does the edge's durable session storage. McpCommands::ServeHttp parses only with the first four inputs below, and the edge starts only with an authentication mode and a signed manifest:

2. Exchange the session for an expiring credential

With a session established, the operator exchanges it for a session credential under the wire schema chio.mcp.session-credential.v1, so the host stops presenting its own client credential on every call. The exchange takes an explicit ttlSeconds and a bounded allowedTools list.

pub(super) struct SessionCredential {
    schema: String,
    token_hash: String,
    session_id: String,
    subject_key: String,
    capability_ids: Vec<String>,
    server_id: String,
    endpoint_path: String,
    auth_mode_fingerprint: String,
    policy_fingerprint: String,
    allowed_tools: Vec<String>,
    issued_at: u64,
    expires_at: u64,
}

Each listed tool must be covered by an unexpired capability issued to the session's subject for an Invoke operation and must appear in the wrapped server's tool inventory. ttlSeconds runs from 1 to 3600 (MAX_TTL_SECONDS), otherwise HTTP 400, and the credential expires no later than the session's earliest issued capability. Without a static session bearer, a distinct admin bearer, --shared-hosted-owner, durable session storage, and durable admission, the exchange returns HTTP 409.

The returned bearer token is opaque. The operator-owned session database keeps only its hash and the signed record, which pins the session id, subject key, capability ids, server id, endpoint path, and the session's authentication-mode and policy fingerprints; the response carries Cache-Control: no-store. When the token is presented, the edge reloads the record, verifies the kernel's signature, and compares every field and the request's Origin against the caller's current session before accepting the call.

3. Read once, acknowledge the result, and withdraw the credential

Continue an initialized, retained MCP session on the edge from step 1, whose signed grant and discovered inventory cover read_file. The client exchanges a 120-second read-only credential, submits one immutable read, acknowledges the delivered result, withdraws the credential, and checks that redelivery is refused.

import http.client
import json
from urllib.parse import urlsplit, quote


def review_with_session(base_url, session_id, admin_token, read_arguments,
                        original_request_id, persist_evidence, origin=None):
    """Use one already initialized, retained session on the configured fs host.
    read_arguments is the original admitted read_file argument object.
    persist_evidence must durably store each private observation before returning.
    Credentials are never printed or included in that evidence.
    """
    base = urlsplit(base_url)
    if base.scheme not in ("http", "https") or base.path not in ("", "/") or base.query or base.fragment:
        raise ValueError("supply the exact trusted host origin")

    def request(method, path, token, body=None, session=False):
        cls = http.client.HTTPSConnection if base.scheme == "https" else http.client.HTTPConnection
        conn = cls(base.hostname, base.port, timeout=20)
        headers = {"Authorization": "Bearer " + token, "Accept": "application/json, text/event-stream"}
        if session:
            headers["Mcp-Session-Id"] = session_id
            if origin is not None:
                headers["Origin"] = origin
        if body is not None:
            headers["Content-Type"] = "application/json"
        try:
            conn.request(method, path, None if body is None else json.dumps(body), headers)
            response = conn.getresponse()
            # http.client does not follow redirects to another credential recipient.
            if 300 <= response.status < 400:
                raise RuntimeError("trusted host redirected the request")
            content_type = response.getheader("Content-Type", "").split(";", 1)[0].strip()
            if content_type == "text/event-stream":
                data = []
                expected_id = body.get("id") if isinstance(body, dict) else None
                while True:
                    line = response.readline()
                    if not line:
                        raise RuntimeError("stream ended before the original terminal response")
                    line = line.decode("utf-8").rstrip("\r\n")
                    if line.startswith("data:"):
                        data.append(line[5:].lstrip(" "))
                    elif not line and data:
                        payload = "\n".join(data); data = []
                        if not payload.strip():
                            continue  # MCP may send an initial empty SSE event.
                        event = json.loads(payload)
                        if event.get("id") == expected_id and ("result" in event or "error" in event):
                            return response.status, event
            raw = response.read()
            try:
                body = json.loads(raw)
            except json.JSONDecodeError:
                body = raw.decode("utf-8", errors="replace")
            return response.status, body
        finally:
            conn.close()

    admin_path = "/admin/sessions/" + quote(session_id, safe="") + "/credential"
    status, issued = request("POST", admin_path, admin_token,
                             {"ttlSeconds": 120, "allowedTools": ["read_file"]})
    if status != 200:
        raise RuntimeError("session credential exchange refused: " + str(status))
    token = issued["bearerToken"]
    original = {"jsonrpc": "2.0", "id": original_request_id, "method": "tools/call",
                "params": {"name": "read_file", "arguments": read_arguments,
                           "_meta": {"chioRequestId": original_request_id}}}
    evidence = {"binding": {k:v for k,v in issued.items() if k != "bearerToken"},
                "request": original}
    status, result = request("POST", "/mcp", token, original, session=True)
    evidence["original_status"] = status; evidence["original"] = result
    persist_evidence(evidence)  # Must return only after private durable storage.
    if status != 200 or not isinstance(result, dict) or "error" in result:
        raise RuntimeError("original read needs retained-session diagnosis")
    # Keep the original result before acknowledging delivery. Acknowledge an
    # authenticated terminal tool error too; acknowledgement does not mean success.
    acknowledgement = result["result"]["_meta"]["chioDelivery"]
    status, acknowledged = request("POST", "/mcp", token,
        {"jsonrpc": "2.0", "id": "ack-" + original_request_id, "method": "chio/acknowledge",
         "params": acknowledgement}, session=True)
    evidence["ack_status"] = status; evidence["acknowledged"] = acknowledged
    persist_evidence(evidence)
    if status != 200 or not isinstance(acknowledged, dict) or not acknowledged.get("result", {}).get("acknowledged"):
        raise RuntimeError("retain original result and acknowledgement for recovery")
    status, revoked = request("POST", admin_path + "/revoke", admin_token)
    evidence["revoke_status"] = status; evidence["revoked"] = revoked
    persist_evidence(evidence)
    if status != 200:
        raise RuntimeError("revocation not established")
    status, rejected = request("POST", "/mcp", token, original, session=True)
    evidence["refused_status"] = status; evidence["refusal"] = rejected
    persist_evidence(evidence)
    assert status == 401, "revoked session credential reached the call path"
    return evidence

Call review_with_session with the trusted host origin, the retained session ID, the operator credential, the original read arguments, their retained request ID, and a private durable evidence writer. persist_evidence must finish durable storage before returning, so a failure stops the client before it acknowledges anything. The stable operation key travels in params._meta.chioRequestId, apart from the JSON-RPC correlation ID, and an optional Origin must match the session's original origin. Download the complete client. On a configured host, the protocol returns:

1. Exchange. HTTP 200 with a bounded binding and an opaque bearer for one retained session; it mints no capability and grants no admin power.
2. Read. The original tool response with a delivery acknowledgement token, returned as a terminal JSON-RPC event over SSE. Tool success or error is read separately from authenticated delivery.
3. Acknowledge. acknowledged: true; the delivery latch advances and no new effect occurs. An authenticated terminal tool error is acknowledged too.
4. Withdraw and redeliver. HTTP 401, often as plain text; the revoked credential cannot reach the tool again.

You should see each response recorded before the next transition, so a later error still leaves the original result and acknowledgement for recovery. Admin, acknowledgement, and cached responses use JSON. The evidence excludes the bearer token, and the one-use acknowledgement belongs in private caller storage. Authenticate receipt signatures against your independent kernel pin before trusting their claims. If a response is uncertain or lacks a verified acknowledgement, inspect the original credential's status and latch: a new credential cannot reset pending custody.

4. Revoke the credential before it expires

Revocation is an explicit operator action. POST /admin/sessions/{session_id}/credential issues the credential; POST /admin/sessions/{session_id}/credential/revoke and GET /admin/sessions/{session_id}/credential/status are suffixes of that same path. All three require the configured admin bearer before the session id in the path is resolved.

Revoke deletes the session's stored credential row, invalidating any bearer issued for that session regardless of its remaining TTL. Status reports whichever call is latched against the credential, with a fixed recovery instruction to inspect and revoke instead of waiting for automatic unfencing.

5. Launch Hermes in restricted mode

chio_hermes.restricted.prepare() composes three constraints before the Hermes process starts, and refuses to run anywhere but macOS with sandbox-exec installed. It disables Hermes's Python plugin hook and points Hermes at exactly one MCP server, an explicit gateway whose tool allowlist comes from the operator-prepared gateway configuration and must match the session credential's allowedTools, so a tool outside that list is never offered.

It generates a fresh Hermes profile holding only the launcher's local gateway bearer: the model relay's token appears there only as an environment-variable reference, and the kernel session bearer not at all. It checks that the gateway configuration carrying the session credential, the gateway's journal directory, and any Codex auth file sit outside every path the profile may read. Finally it writes the sandbox-exec profile that confines the host and its children.

A refused session call returns its exact HTTP status and string

Session credential refusals are plain HTTP status codes carrying the string the caller sees; no typed error variant crosses this edge.

For a pending or uncertain call, keep the stable chioRequestId and the original request, and inspect the retained session and operation before retrying; reinitializing a session leaves its prior effect unreconciled. For an expired or revoked credential, use the host's legitimate credential lifecycle and keep the same least-privilege method and tool limits.

Next: govern a coding agent end to end