Agent Substrate

Agents and features

Which agents can run as Agent Substrate actors, how each runs unattended, and how each DefenseClaw feature compares with the host and OpenShell sandboxes.

Short answer

  • Ten command-line agents are built to run in an actor. An actor is a Linux container, and DefenseClaw reuses the harness images it builds for OpenShell. The kit in the image sends hooks to the cluster gateway instead of a local one. How far each agent has been proven differs; the table below says.
  • Desktop and IDE apps can't. An actor has no screen, so the Claude desktop app, Cowork, and the Cursor, Kiro and Antigravity editors keep their host connectors. Their command-line versions can run in an actor.
  • The checks are the same. The same hooks, rules, guardrails, scans and asks apply.
  • The surroundings are not. There's no live folder and nothing on your machine is reachable. In return you get suspend and resume, any laptop OS, model traffic that always passes the guardrail proxy, and unattended runs.

Agents

AgentHeadless (run --task)Model routeIn an actor today
Claude Codeclaude -pDefenseClaw gatewaySupported. Interactive and headless, on a real model, from macOS and Linux laptops. Windows laptops are Preview
Codexcodex execDefenseClaw gateway (/llm/bedrock/openai or /llm/openai)Hooks, headless and interactive work in an actor, on a real model. Model route: GPT-5.6 Luna on Bedrock (us.openai.gpt-5.6-luna) through the gateway's Bedrock OpenAI-compatible route, or OpenAI with a key in defenseclaw-llm. template build --provider bedrock or openai picks one
GitHub Copilot CLIcopilot -pDefenseClaw gateway (/llm/bedrock/openai)Hooks and a real model work in an actor. Model route: Bedrock only, through the gateway's OpenAI-compatible route
Hermeshermes chat -qDefenseClaw gatewaySame as Copilot CLI
OpenCodeopencode runDefenseClaw gatewaySame as Copilot CLI. defenseclaw substrate run opencode starts it: its plugin sends its hook events through the actor kit
Kiro CLIkiro-cli chat --no-interactiveVendor sign-in onlyPreview. Hooks, tamper checks and refusals work. Model access: it needs a vendor sign-in or KIRO_API_KEY
Antigravity CLIagy -pVendor sign-in onlyPreview. Hooks, tamper checks and refusals work. Model access: it needs a vendor sign-in or GEMINI_API_KEY
Cursor Agent CLIcursor-agent -pVendor key (CURSOR_API_KEY)Preview. The hook path works. Model access: a vendor key or sign-in. run starts it, with the sign-in rules below
Ampamp -xVendor key (AMP_API_KEY)Works against its API on a key, but can't run: it speaks WebSocket only, which Substrate's egress refuses (see below). run starts it in open source, with that note and the sign-in warning
Devin CLIdevin -pVendor sign-in onlyPreview. The hook path works. Model access: a vendor key or sign-in. run starts it, with the sign-in rules below
OpenClaw, ZeptoClawNoNoNot in this release
Claude desktop and Cowork, Cursor, Kiro and Antigravity editors, Copilot in VS CodeNoNoDesktop apps need a screen

Supported means a person can drive the agent in a real terminal, or a headless task runs, with DefenseClaw's hooks firing and a real model answering through the gateway. Only Claude Code is started through the launcher; the others run through the kit and a gateway. Preview means the hooks work, but the agent needs a vendor key or sign-in for a model.

defenseclaw substrate run starts all ten agents. For Amp it first prints that Amp's WebSocket connections are not passed through yet, so it may not reach its model. Cursor, Kiro, Antigravity, Devin and Amp follow the sign-in rules below.

Each connector has a headless command; a connector that cannot run one is interactive only, and run --task says so. The full command lines the relay runs are:

AgentCommand
Claude Codeclaude -p {prompt} --output-format stream-json --verbose --dangerously-skip-permissions
Codexcodex exec --skip-git-repo-check -c sandbox_mode="danger-full-access" -c approval_policy="never" {prompt}
OpenCodeopencode run {prompt}
Copilot CLIcopilot -p {prompt} --allow-all-tools
Hermeshermes chat -q {prompt} -Q --yolo --accept-hooks
Kiro CLIkiro-cli-chat chat --v2 --agent defenseclaw --no-interactive --trust-all-tools {prompt}
Antigravity CLIagy -p {prompt} --dangerously-skip-permissions
Cursor Agent CLIcursor-agent -p {prompt} --force --trust
Ampamp -x {prompt}
Devin CLIdevin --permission-mode dangerous --respect-workspace-trust false -p {prompt}

The "skip permissions" flags only silence the agent's own prompts, because a headless run has nobody to answer them. DefenseClaw's hooks still decide every tool call, and a hook deny holds even under --yolo.

Images. template build --connector NAME builds the image for any of the ten agents (claudecode, codex, opencode, copilot, hermes, kiro, antigravity, cursor, amp, devin) and refuses any other name. An agent needs its kit image before it can run.

Model replies. OpenAI-style models on Bedrock (Codex, OpenCode, Copilot CLI, Hermes) get prompt inspection and the model allowlist. The proxy does not yet inspect the tool calls in the model's reply; the hook stops them when they run. See the threat model.

Vendor sign-in

Substrate's egress gateway can add an API key or token to an agent's requests, so the agent never holds it. That covers API keys (Anthropic, OpenAI, Bedrock, AMP_API_KEY, CURSOR_API_KEY, KIRO_API_KEY, GEMINI_API_KEY). Subscription sign-ins that open a browser and refresh their own tokens, such as a Claude or ChatGPT plan login or devin auth login, put tokens in the actor's snapshots.

Open sourceManaged enterprise
Claude Code, Codex, OpenCode, Copilot CLI, HermesModel through the DefenseClaw gateway; no sign-in in the actorSame
Cursor, Kiro, AntigravityStarts with a warning that the sign-in token will sit in the actor and its snapshotsStarts only when its key is bound as a Substrate secret; otherwise refused at create
DevinStarts with the warning. Devin has no API key routeRefused at create
AmpStarts with warningsRefused even with a key: Amp rewrites its config folder at every start, so DefenseClaw's hook registration cannot be made root-owned

Where the warning shows. The launcher prints it when it creates the actor. While you are attached it stays on the bottom line, the launcher's own row, which the agent cannot draw on, so a full-screen agent such as Antigravity can't clear it (asks take that row while one is waiting). The launcher prints it again when you detach or the agent exits. With --no-asks, or when the launcher's output is not a terminal, there is no bottom line: the warning is printed at create and after the attachment, and the relay also writes it at the top of the agent's terminal, where an agent that clears the screen erases it.

A managed refusal comes back before any actor exists, as 403 with the reason subscription_signin_refused (or agent_hook_tamper_refused for Amp), and the launcher shows the message. Binding a key is an admin task: add the secret to substrate.secrets with the key's environment variable as its placeholder (see Secrets).

Amp and WebSockets. Amp's thread and user connections are HTTP/1.1 WebSockets. Substrate 1.0.0's egress answers that upgrade with 403 on an inspected rule. Listing ampcode.com in substrate.allow_passthrough_for lets the upgrade through, but that host is then not inspected and no key is injected there, so Amp's key would sit in the actor. A managed install refuses that. See Troubleshooting.

Features

FeatureOn your machineOpenShell sandboxAgent Substrate
Tool-call checks (hooks)YesYesYes, same rules and messages
Tool chains and intentPer sessionPer sessionPer session and per actor, kept across suspend and resume
Model request and reply guardrailsThrough the guardrail proxy, where the connector routes to itThe model call goes to the provider directlyAlways, for the agents that route through the gateway, because the provider is only reachable through the proxy
Routing, budgets and costWhere the proxy is usedWhere the proxy is usedNot merged yet. See Feature coverage
Network controlNot isolatedEgress proxy, block and allow lists, asksDenied by default; DefenseClaw writes each agent's allow list and checks each request; asks
SecretsIn the user's environmentPlaceholder key in the sandboxNo secret value in the actor; the egress gateway swaps placeholders on bound hosts only
Asks and approvalsIn the agentIn the activity feed and approvalsIn your terminal session and approvals, so you can answer after detaching
Unattended runsn/an/a--task, --batch, from CI
Your projectIn placeLive (Linux, Docker) or copyCopy or git clone only
UndoNoUndo point, or pull from a copyRestore points of the agent's folder (checkpoint, undo), and pull
Your local MCP serversYesImported (Claude Code, Codex)No. Only MCP servers in the image or reachable over the network
Ports on your machineYes--host-port, after approvalNo
Process tree, kernel feedHost feedsLinuxNo. Substrate reports CPU and memory per agent
Interactive terminalYesYes, over SSHYes, through the launcher and the terminal relay in the kit
Leave and come backn/aStop and connect on the same machineSuspends when idle; resume from any machine in under a second
Many agents at onceLimited by the machineLimited by the machineLimited by the cluster
Laptop OSAllLinux, Apple-silicon MacAll, including Windows and Intel Macs
Several people on one hostYesOne account per hostYes, each agent isolated
IdentityOS userOS userCompany sign-in for the person; each agent's identity is signed by Substrate

The interactive terminal

Substrate doesn't attach a terminal to an actor the way ssh or docker exec does. It forwards HTTP to the actor and streams its logs. So the DefenseClaw kit in the image carries a small relay that carries the agent's terminal over that HTTP path (a WebSocket, with a long-poll fallback for proxies that block WebSockets), and run and connect speak to it. Press Ctrl-] to detach.

The relay needs no inbound port on your laptop, and your laptop needs no access to Substrate's router. The launcher connects to the cluster gateway's admin address, which checks that you own the actor and carries the connection to the actor's relay. An administrator sees every person's agents in list --all and can delete them, but can't connect to, run a command in or get a session for another person's agent (403 not_your_agent); every such attempt is audited as the person who made it. The relay still requires a short-lived token for the actor's own person and that actor, and refuses a token that names anyone else, so an unauthenticated connection gets nothing.