Agent Substrate

How it works

Where DefenseClaw runs in an Agent Substrate cluster, how a tool call, a model call and a web request are checked, and how agent identity, network policy, state and suspend and resume fit together.

The whole picture

  Laptop or CI
  defenseclaw substrate  login | run | connect | pull | approvals
        |   HTTPS, signed in with OIDC (Keycloak, Active Directory, ...)
        |   or your Kubernetes identity
        v
 +- defenseclaw-system namespace ---------------------------------------------+
 |  GATEWAY  admin listener   create agents, attach the terminal, approvals   |
 |  GATEWAY  actor listener   tool-call hooks, model proxy (/llm), asks       |
 |  CALLOUT                   checks every other web request                  |
 |  CONTROLLER                allow lists, template admission, idle, drift    |
 |  LEADER                    tool chains, intent, asks, registrations        |
 +------^---------------^---------------^------------------------+-----------+
        | terminal      | hooks and     | "may this request      | network allow list
        | (via router)  | model calls   |  go out?"              | (EgressPolicy), templates
 +- Agent Substrate (ate-system) ----------------------------------v-----------+
 |  router  -------->  ACTOR  sandbox (gVisor or microVM)                     |
 |                     coding agent + DefenseClaw kit (hook, terminal relay)  |
 |                     no keys, no secrets, no network of its own             |
 |                          |  every request                                  |
 |                          v                                                 |
 |  egress gateway   default deny; adds the actor's signed identity;          |
 |                   swaps secret placeholders, on bound hosts only           |
 +--------------------------+-------------------------------------------------+
                            v
   allowed hosts: git, packages, APIs       model providers: only through the gateway
   events to OTLP, Splunk, Grafana, each tagged with the agent, actor UID and person

Read it from the top: you start an agent from your laptop, the gateway creates it in Substrate, and from then on everything the agent does leaves its sandbox through Substrate's egress gateway. Hooks and model calls go to the DefenseClaw gateway, and every other request is checked by the callout first. The controller decides, before the agent first runs, which hosts it may reach at all. The sections below follow each path.

Where DefenseClaw runs

DefenseClaw doesn't run inside the agent's sandbox. It runs next to Substrate in the cluster, in its own namespace. The agent reaches it the only way an actor can reach anything: through Substrate's egress gateway. This mirrors OpenShell, where DefenseClaw stays on the host and the sandbox calls out to it.

runs hooks
all traffic
hooks, model calls
asks about the rest
stateful steps
checked model calls
if allowed
UntrustedActor sandbox (gVisor or microVM)
PrivilegedAgent Substrate (ate-system)
RestrictedDefenseClaw (defenseclaw-system)
Coding agentClaude Code, Codex, ...
DefenseClaw kithook binary and terminal relay
Egress gatewaydefault deny, adds identity and secrets
Gateway, actor listenerhooks and guardrail proxy
Egress calloutchecks each request
Gateway leaderchains, intent, asks
Model providers and the web

List view for small screens. Use the expand button to open the drawing.

UntrustedActor sandbox (gVisor or microVM)

  1. Coding agentClaude Code, Codex, ...
    • runs hooksDefenseClaw kit
  2. DefenseClaw kithook binary and terminal relay
    • all trafficEgress gatewayAgent Substrate (ate-system)

PrivilegedAgent Substrate (ate-system)

  1. Egress gatewaydefault deny, adds identity and secrets
    • hooks, model callsGateway, actor listenerDefenseClaw (defenseclaw-system)
    • asks about the restEgress calloutDefenseClaw (defenseclaw-system)
    • if allowedModel providers and the web

RestrictedDefenseClaw (defenseclaw-system)

  1. Egress calloutchecks each request
  2. Gateway, actor listenerhooks and guardrail proxy
    • stateful stepsGateway leader
    • checked model callsModel providers and the web
  3. Gateway leaderchains, intent, asks
  1. Model providers and the web
An Agent Substrate cluster with DefenseClaw. The agent's sandbox has no network of its own: everything leaves through Substrate's egress gateway, which adds a signed agent identity to calls to DefenseClaw and asks the DefenseClaw callout about every other request.

Separately, the controller decides what each agent may reach at all:

writes
applies
DefenseClaw profilepack, team, template
Controllerrenders the allow list
Substrate control planeEgressPolicy per agent
Egress gatewayenforces it

List view for small screens. Use the expand button to open the drawing.

  1. 1.DefenseClaw profilepack, team, template
    • Controller
  2. 2.Controllerrenders the allow list
    • writesSubstrate control plane
  3. 3.Substrate control planeEgressPolicy per agent
    • appliesEgress gateway
  4. 4.Egress gatewayenforces it
The controller turns each agent's DefenseClaw profile into Substrate's own network allow list. Substrate enforces it; an agent without one has no network.
PartWhat it does
Gateway, actor listenerThe same checks as on a laptop: tool-call hooks, model request and reply guardrails, MCP and skill checks, asks. A Deployment with an autoscaler (at least two replicas). Its Service defenseclaw-actor is the only DefenseClaw host in an actor's allow list
Gateway, admin listenerThe launcher and the fleet view. A separate Service defenseclaw-admin that is never in an allow list, so an actor cannot reach it
Gateway leaderOne replica holds a lease and the store volume. It keeps the state that has to survive across stateless calls
ControllerWatches agents through Substrate's API. For each agent it writes Substrate's network allow list (EgressPolicy) from the agent's DefenseClaw profile, before the agent first runs. It also checks templates and handles suspend, resume, fork, idle suspend and drift
Egress calloutPlugged into Substrate's egress gateway. It sees each web request the agent makes (method, address, headers, and for MCP calls the body) and can refuse it: block lists, data in URLs and headers, sites that need an ask
Kit in the imageA small hook binary and a terminal relay, plus the agent's hook settings. It holds no keys and no policy

A tool call

Agent and hook
Egress gateway
DefenseClaw
hook call, placeholder identity
same call, signed agent identity
verify identity and live actor, find profile, check
allow, block or ask
verdict
  1. 1Agent and hook to Egress gateway

    hook call, placeholder identity

  2. 2Egress gateway to DefenseClaw

    same call, signed agent identity

  3. 3Note · DefenseClaw

    verify identity and live actor, find profile, check

  4. 4DefenseClaw to Egress gatewayreply

    allow, block or ask

  5. 5Egress gateway to Agent and hookreply

    verdict

Claude Code asks DefenseClaw before running a command. The hook sends a placeholder header; Substrate's egress gateway replaces it with a short-lived token that names the agent, so the agent can't pretend to be another one and holds nothing worth stealing.

The hop from Substrate's egress gateway to the actor Service is plain HTTP on port 80 inside the cluster, because Substrate 1.0.0 verifies an https upstream only against public certificate authorities. The Service's NetworkPolicy admits only the egress gateway; see the threat model.

The gateway believes only the token Substrate adds. Everything else in the request, including the body, session IDs, timestamps and file paths, is a claim from the agent. The token must be unexpired, have the right audience, come from a key the cluster published, and name an actor that is running or resuming with that UID. A worker token, a stale UID or no token gets a 401 with a closed reason and nothing else. The gateway never echoes request headers.

The verdict uses the same code path as a hook on a laptop, so messages, rules and audit records match. If DefenseClaw can't be reached, the hook retries once and then follows the fail mode: closed on managed deployments and for unattended runs, open with a warning for interactive agents on default open-source settings.

A model call

The agent's model address (ANTHROPIC_BASE_URL, OPENAI_BASE_URL and the like) points at the DefenseClaw guardrail proxy through the same Service, on a path per provider. The provider's own address is never in the agent's allow list, so there's no way around the proxy. The proxy works out who is calling from the signed token, applies routing and the guardrails, adds the real key, which lives only in the cluster, forwards the request, and checks the reply. It records usage and cost against the verified actor and person.

A web request

  • No allow list, no network. Substrate refuses DNS and connections for an agent without an EgressPolicy. An agent DefenseClaw hasn't approved, from an unattested template for example, can't reach anything. Nothing is ever left open while DefenseClaw catches up.

  • DefenseClaw writes the list. It is built from the policy pack and the profile. It always includes DefenseClaw itself, and never the model providers. Allowed sites use Substrate's inspected HTTPS rule, so the callout sees each request. Sites an admin explicitly marks as pass-through are not inspected, never carry a secret, and their events say so.

  • The callout checks each request. Block-list feeds, secrets in URLs or headers, and hosts that need an ask. For POSTs to MCP servers and other listed hosts it can read the body, up to 1 MiB, to apply tool rules; a larger body is not read and the event says so. Credential headers are redacted in its logs.

  • Chains. Each request adds an observed_egress step to the actor's tool chain window. A request that leaves the cluster after a secret read is refused by default in every mode (open source, strict and managed), because actors are unattended. alert is an opt-in the operator chooses; see the secret-read chain for which reads start the chain and the one setting.

    An unattended defenseclaw substrate run claude --task that reads ~/.aws/credentials and then repeats a request: the hook records a MEDIUM finding for rule PATH-AWS-CREDS on the read and allows it, the request that follows answers 403, and the cluster's callout log shows log.egress.blocked for GET github.com with category chain_egress, rule chain.secret_read_then_egress and the reason that earlier in this actor's work it read a secret, so DefenseClaw blocks sending data off the cluster after that

  • Asks. A refused site raises an ask in your session. An approval updates the agent's list, and Substrate applies it within seconds; the held request is retried for about ten seconds.

  • What Substrate blocks anyway. WebSockets from the actor, proxy tunnels, raw TCP, and UDP other than DNS. A raw TCP connect still completes, to any address and port, because Substrate's egress answers it and then closes it when the first bytes match no rule: nothing reaches the target, but a port scan sees every port open (see Known limits).

  • If the callout is down. Closed in managed mode. Open source can choose; verify is red either way.

The secret-read chain

A tool call starts chain.secret_read_then_egress when it reads the contents of a credentials file, wherever the file is: in the home, in a project or work directory, or as a copy. A read counts whatever its exit code: a call that printed a credentials file and then failed (cat .env ., cat .env && false) starts the chain the same as a call that succeeded. A failed call is left out only when its result proves it read nothing: one plain reader (cat, head, tail, ...) whose whole output is its error for every file, such as cat: .env: No such file or directory. The proof trusts that the reader is the system's: a cat the agent replaced with its own program could print a false error. That proof needs the call's result tied to the call. Devin and GitHub Copilot name no tool call in their hooks, but their result carries the call's command and output, so DefenseClaw ties the result to the call by the session and the exact command; until that result comes, the read counts as proposed. Antigravity and Kiro have no such result, so for them a credentials read starts the chain when the call is proposed, a failed read of a missing file too, and the refusal says The credentials read could not be cleared: no result correlation for <connector>. A tool call DefenseClaw can't record in the actor's chain window is reported (SUBSTRATE-CHAIN-UNRECORDED), never skipped: for the chain's window the callout refuses that actor's egress where it refuses unchecked egress, and alerts elsewhere. A file is a credentials file by its name alone: .env or .env.<name>; an SSH private key (id_rsa, id_ed25519, id_ecdsa, id_dsa, id_ecdsa_sk, id_ed25519_sk anywhere, any other id_* directly in an .ssh folder); .aws/credentials or a copy beside it (.aws/credentials.<name>); .kube/config; .docker/config.json; .npmrc; .pypirc; .git-credentials; .netrc or _netrc; .pgpass; a Hugging Face, Poetry or Kaggle token file; a gcloud, GitHub CLI (hosts.yml), Anthropic or Azure CLI token file; a *.key, *.p12 or *.pfx file; a *.pem file whose name says key (privkey.pem, server-key.pem). A read is the agent's Read or Grep tool on the file, or a shell command that reads, searches or copies it (for example cat, head, grep, base64, cp, PowerShell Get-Content), on its own, inside a pipeline, or inside a command list (;, &&, ||), as long as every word of that command is known before it runs. Known limit: a read that only the program's own logic can place doesn't start the chain yet: a script (sed or awk programs, python3 -c, node -e, perl), a search of a whole folder, a glob, a path kept in a variable, a link to the file or a while read loop. The home-path rules (PATH-*), /proc/self/environ, the cloud and workload-identity credential reads and the browser session stores start it too. These never start it: a template or sample, meaning a name whose last suffix is example, examples, sample, samples, template, templates, tpl, tmpl, dist, default, defaults, schema, skel, j2, jinja, jinja2, md or txt (.env.example, .aws/credentials.template, .ssh/id_rsa.sample); a public key (*.pub); a certificate, chain, bundle or public-key .pem; any file under a testdata, test-data, fixture, fixtures, example, examples, docs, __tests__, __fixtures__ or __mocks__ folder or inside node_modules, site-packages or dist-packages; an SSH client that only presents a key (ssh -i, scp -i). An upload to an external host within the next 8 tool calls and 30 minutes of the same session completes the chain; the upload call must parse completely. Not covered yet: a file read only by jq or yq, by xargs -a, by a while ... done < file loop, or through a path built when the command runs ($(pwd)/.env); the action parser records no file read for these today.

On Agent Substrate a completed chain refuses the egress by default, in every mode (open source, strict and managed), because actors are unattended: the actor's tool call that uploads is refused by its hook, and its request that leaves the cluster is refused by the egress callout (category chain_egress). That includes a chain whose every completing read names no one file (a read of several files, a read in a call that also makes a write with its own commands or redirects, a relative path in a call that is not proven to keep its directory): the agent chooses how it reads, so that form refuses the same way. The callout sees no file: after a credentials read it refuses every request of that actor that leaves the cluster, benign or not, until the chain's window ends (8 steps and 30 minutes of the actor's running time: wall time while the actor runs, whether or not it makes requests; a suspend, however long, doesn't count, nor does a time the leader can't see it running, such as a controller outage) or the opt-in is set; an upload of a different, known file is allowed only at the hook. The one setting is the config key substrate.chain_egress_action: block (the default) or alert (an opt-in under which every chain only alerts), set with the chart value config.substrate.chain_egress_action, which the gateway and the leader both read. A request counts as a Substrate actor's only with a verified actor token (the actor listener or the callout route). Hooks on a person's own computer or in an OpenShell sandbox keep the rule pack's disposition: an alert in the default pack, also for a chain whose read names no one file.

State across stateless calls

Gateway replicas hold no state, so a finding that spans several calls needs one place to live. The leader keeps tool-chain windows, user intent, asks and registrations, and the other replicas forward to it over mutually authenticated calls that are safe to repeat.

  • A chain window is the current call plus up to eight earlier ones, for 30 minutes, counted in running time: the time the actor works, measured from its own calls through DefenseClaw. A pause of more than 5 minutes between two calls counts as 5 minutes. So the clock stops whenever the actor stops (suspended by hand, after idle time or after its task ends, or moved off its node), whether or not DefenseClaw saw it stop. A window that still holds a secret read is kept while the actor exists; it is the last to go when an atespace reaches its actor cap (see the known limits). When an actor is deleted, its chain state goes with it. If DefenseClaw missed the delete (the controller was down or restarting), the state goes at the first sweep 7 days after the actor was suspended or made its last call, once its registration shows it deleted; if the registration can't be read, the state is kept.
  • Every call lands in two windows, one per session and one per actor, so rotating session IDs can't empty the window.
  • A fork inherits its parent's windows but not its asks. A revert marks a barrier in the window and keeps earlier findings. It doesn't end the egress refusal after a secret read: the snapshot the actor goes back to may still hold what it read.
  • When the leader moves, the volume reattaches in about 30 seconds. Stateless checks continue meanwhile; stateful steps follow the fail mode, and unattended runs wait and retry. While the actor's chain can't be checked, and for 15 seconds after a new leader answers its first check, a request that leaves the cluster with a body, or with any method other than GET and HEAD, is refused in every mode (retryable, chain_unchecked); an interactive actor's GET and HEAD requests go through with an alert on default open-source settings.
  • Findings from different actors are correlated in telemetry and detections only, never used as a blocking proof.

Identity

  • The agent. Substrate issues each agent its own certificate and, on request, signed tokens. DefenseClaw trusts only the token Substrate's egress gateway adds. Events carry Substrate's actor UID (ate.actor.uid), so DefenseClaw and Substrate records line up. The agent identity (agt-...) is derived from the person the launcher verified (the CI workload for a pipeline run, or the atespace for an actor made outside the launcher) and the connector, so one person's agents of one connector, and a fork, share it with a new sandbox each. The session instance (ais-...) is derived from it and the session, so it is the same on every gateway replica.
  • The person. When the DefenseClaw launcher starts the agent, the cluster gateway verifies the person's OIDC token and registers the actor with that person before it answers. In enterprise, team atespaces only let DefenseClaw create actors, so the registration can't be forged. Actors started some other way are attributed to their atespace and template only.
  • The relay. To attach to an actor, the launcher opens a WebSocket (or a long-poll fallback) to the gateway's admin listener. The gateway authenticates the person with OIDC or the Kubernetes identity, checks they own the actor (administrators included: they see the inventory, never another person's session), and proxies to the actor's relay through Substrate's router with its own in-cluster identity. The relay accepts only a short-lived session token for that actor that names the actor's own person; the gateway's check refuses one minted for anyone else. The launcher never dials the router and holds no router certificate.

Suspend, resume, undo, fork

What happensWhat DefenseClaw does
The agent suspends, then resumes on another machineNothing changes. Its approvals, sessions and audit trail carry on. Before it resumes, the controller checks its profile hasn't changed, and the first hook after resume uses a connection the relay opened in advance. Budget: that first hook answers within 250 ms at p99 on gVisor and microVM (about 60 ms and 86 ms), with no timeout, retry or fail-mode answer
The agent suspendsDefenseClaw's idle and task-end suspends use Substrate's default, asynchronous mode: the suspend returns once the snapshot is on the node, and atelet uploads it to the bucket about 5 minutes later (atelet's --snapshot-upload-delay). Until then the snapshot reads SNAPSHOT_STORAGE_STATE_PENDING and exists only on that node: a resume or a delete in those minutes skips the upload, and a lost node takes the agent back to its last uploaded snapshot. To store a running agent's snapshot at once, suspend it with kubectl ate suspend actor NAME -a ATESPACE --mode sync
You undo to a checkpoint (defenseclaw substrate undo)Same agent, same approvals. The undo puts the project folder back with git inside the agent, and DefenseClaw is not told, so it keeps its view of the files: running a file downloaded before the undo can still be reported as chain.download_then_execute_same_artifact, an alert, never a block. Egress after a secret read stays refused
An administrator reverts the actor (kubectl ate revert)Same agent, same approvals. The controller sees the revert and the leader puts a barrier in its chain windows, so files from before the revert no longer join a download-then-run chain. Egress after a secret read stays refused
Someone starts a new agent from a saved snapshotA new agent with a new UID and fresh approvals. An approval given to one agent can't be copied by cloning it. Actors made from one golden snapshot share the memory the snapshot captured, including the state of any random number generator in a program that started before it. Kernel randomness and IDs differ per actor. The kit starts nothing before the first resume, and partitions its state on the actor UID
The agent is deletedIts allow list and registration are removed and a tombstone stays in the audit. The snapshots are removed from the bucket

What we rely on Substrate for, and what we don't

We rely on Substrate's sandbox, its egress gateway and its identity certificates. We don't defend against a cluster administrator, a node root user or a sandbox escape. See the threat model. The integration follows one pinned Substrate version at a time, inside the supported range.