Agent Substrate

Feature coverage

How each DefenseClaw feature works when agents run as Agent Substrate actors - guardrails, routing, tool chains, policies, skill and MCP scanning, AI discovery, segmentation, secrets, asks, identity and observability.

Every DefenseClaw feature runs in the cluster gateway, the same code as on a laptop. What changes is how each one gets its inputs. On a laptop, DefenseClaw reads the machine. In a cluster, it hears only what reaches it through Substrate: hook calls, model calls, web requests, and the control plane's list of templates and agents.

Key: Same means it behaves as on a laptop. Changed means it works, with a different input or delivery. Not available means the cluster can't provide it, with the reason given.

Guardrails

FeatureCoverageHow it works in the cluster
Model request and reply checksSame, strongerEvery model call goes through the guardrail proxy. The provider is not in the agent's allow list, so nothing bypasses it. The Bedrock event stream passes through unchanged. The security notice a refusal adds to the next model requests goes only to that agent's own requests, and only to those the same gateway replica serves (best effort: the refusal reply itself stays in the agent's history)
Tool-call checksSameHooks call the cluster gateway; Substrate's egress gateway adds a signed agent identity
Tool chains and intentChangedFindings that span several calls (a secret read, then a send) need state across stateless gateway replicas. A single leader holds the state, per verified session and per actor, so rotating session IDs can't empty it. Time spent suspended doesn't count against the 30 minute window. Egress after a secret read is refused by default in every mode, because actors are unattended; alert is an opt-in the operator sets with the chain egress action. Host-side hooks keep the balanced default
Several agents per personSameEach agent is its own session and its own record
User and group policiesChangedGroups come from the company sign-in (OIDC) instead of the OS. See Identity
LLM judge, unified LLM keyChangedThe judge runs in the cluster gateway. The key is a Kubernetes Secret, or comes from Substrate's credential provider, and never reaches an agent. A managed cluster names it with enterprise.inspection.llm.credential: a key of the defenseclaw-llm Secret the /llm route reads (bedrock for the cluster's Bedrock key). An open-source cluster can also set guardrail.judge.llm.api_key_env to a variable from gateway.extraEnv; a managed one reads no key from the environment
Cisco AI DefenseChangedThe AI Defense key is a Secret. Inspection calls leave from the gateway, not from agents
Fail modesSameInteractive agents follow the profile: closed on managed installs, open with a warning on default open-source settings. Unattended runs always fail closed

Routing, budgets and cost

Because every model call passes the guardrail proxy, the model request and reply checks apply to every agent that routes through the gateway, and the caller is the verified actor and person from the signed token, never a header the agent sends.

What is not in this release yet: semantic and admin routing rules, budgets (warn, downgrade or deny) and per-call usage and cost records for actors. The gateway's tokenomics store keeps usage per gateway replica and has no batch or actor key, so the cluster does not serve it for actors yet. Until it does:

  • defenseclaw substrate usage answers "this cluster does not offer that yet; ask your administrator to upgrade DefenseClaw on it". usage --batch does too.
  • No budget applies to an actor or a batch.
  • The fleet view has no spend.
  • Metrics carry no person or actor labels.

Policies

FeatureCoverageHow it works in the cluster
Rule packs, thresholds, CEL, deterministic detectionSameSame engine, same files
Admission (allow and block lists for skills, MCP servers, plugins)SameSame engine. Its data comes in the chart values, not from files on a machine
Sandbox policy packs (balanced, strict)ChangedDefenseClaw turns them into each agent's Substrate allow list, and the egress callout enforces the per-request parts
Policy creator, recipes, cookbooksSameThey write the same files
Test a policy before rolloutChangeddefenseclaw substrate policy test NAME --host H asks the cluster whether a host, method or tool would be allowed for an agent, without changing anything
DeliveryChangedHelm values and profiles, applied by Helm or GitOps instead of MDM. See Delivery and fleet management

Skill and MCP scanning

FeatureCoverageHow it works in the cluster
Scan before useChanged, strongertemplate build scans the agent's skills, plugins, MCP servers and agent config inside the image, then signs the result. Agents from unscanned images get no network
Scan at run timeChanged, weakerskill-scanner does not run in the cluster. A skill that ships in an attested template is trusted by its digest, because the signed attestation lists it. A skill added mid-session is not scanned, so it follows the fail mode: managed installs and the strict tier refuse it and raise an alert; open source allows it and raises an alert
Remote MCP serversSame, plus networkAllowed MCP servers are named in the allow list. The egress callout reads the body of a call to a listed MCP host (up to 1 MiB) to apply tool rules, and admission decides as usual
MCP servers started inside the actor from the repoConfig checked, tools not scannedAn MCP server the agent adds mid-session (a repository .mcp.json, a written MCP config, mcp add) is checked by its config: one that downloads and runs code is refused in every tier. Its tools are not scanned in the cluster, so a server that may run code of the folder follows the fail mode: managed installs and the strict tier refuse it, open source allows it and raises an alert. Only an installed program, a registry package the folder cannot redirect (npx or uvx of a registry name with no project bin, node_modules program, .npmrc, pip.conf or uv.toml, and no local --package, --from or --spec), or a container image run with no mount is left to the config check alone. Servers in the image are scanned at build. Tool-call hooks and the egress policy still apply to what the server does
Local MCP servers on your laptopNot availableAn agent in the cluster can't reach your machine
Registries (skill and MCP catalogs)SameClean catalog entries are promoted into admission and, for MCP, into the allow list

Reading a body needs a Substrate version that lets the callout ask for it. Without it the callout still checks headers, hosts and URLs, verify says "headers only", and MCP tool rules fall back to the hook path.

AI discovery

FeatureCoverageHow it works in the cluster
Inventory of agents, skills, MCP servers and modelsChangedThe controller lists every template and actor through Substrate's API. Each template's scan record gives its agent, version, skills, MCP servers and model providers
Shadow AIChangedTemplates without a valid attestation and actors DefenseClaw didn't start are reported. Their actors have no network
Which ones actually ranSameFrom hook and model events, per agent
Local model serversNot availableNothing in a cluster corresponds to models served on a laptop. Model use shows up as calls through the guardrail proxy

Segmentation and the agent's surroundings

IntentCoverageHow it works in the cluster
Protected pathsSameHook rules, as in an OpenShell sandbox. Secret files from your project are held back at upload. Rules that resolve links use path facts the kit reports, which the gateway treats as claims
CredentialsStrongerAgents hold no keys. Substrate adds them on the way out, only for the sites that need them. See Secrets
EgressStrongerSubstrate denies by default, and DefenseClaw writes the allow list and checks each request
Blocked toolsSameHook rules
PersistenceChangedSubstrate keeps an agent's files and memory across suspends. Changes to startup files and hooks are flagged when they happen, and pull flags them before they reach your machine
Foreign hooks (a repo or the agent adding its own hooks)SameDefenseClaw's hook config sits in root-owned managed settings in the image, and the agent runs as an ordinary user
Process lineage, kernel feedNot availablegVisor and microVM hide the agent's processes from the node, so there is nothing to watch. Substrate reports CPU and memory per agent

Asks and approvals

FeatureCoverageHow it works in the cluster
Asks in the agentSameFor agents that can pause (Claude Code, Codex and others)
Asks for sitesChangedAsked in your terminal session, or answered later with defenseclaw substrate approvals while detached. The request is refused at once with the ask's id (the egress gateway holds a request under 2 seconds); the agent doesn't stop, and retries once the ask is approved
Unattended asksNewDenied by default. A profile can allow a wait of up to ask_timeout for a person to answer. See Unattended runs
Admin-bounded approvalsSameThe same rules decide whether you can approve, and the same request-access text appears when you can't
Webhooks for approvalsSameSent from the gateway

Identity

WhoCoverageHow it works in the cluster
The agentNew, strongerSubstrate signs each agent's identity, and DefenseClaw trusts nothing the agent says about itself. The gateway also checks that the actor is alive with that UID
The personChangedCompany sign-in (Okta, Entra ID or any OIDC provider), or on an open-source cluster without one your Kubernetes identity, through defenseclaw substrate login. Active Directory works through the provider's AD connection
CINewA workload identity (GitHub Actions OIDC or a Kubernetes service-account token) is the "person" for a batch
Profile choiceSameThe same profile assignments, matched on sign-in groups and, for agents started outside the launcher, on atespace and template
Unverified peopleSameGet default_profile, as on managed laptops
PrivacyNewYou see only your own effective policy, usage and secret names. The fleet view is admin-only and served on a listener actors can't reach

Observability

FeatureCoverageHow it works in the cluster
OpenTelemetry events, metrics, tracesSameSame names and fields, plus the Substrate attributes (defenseclaw.sandbox.substrate.*, ate.actor.uid) so Substrate's own records line up. An agent's hook events carry no turn step number (step_idx): each gateway replica sees only some of a session's hooks, so the replicas can't number its turns alike. For an agent that sends no turn id of its own (Claude Code), the turn id (turn_id) DefenseClaw gives its hook events is chosen by the replica that sees the turn start and can differ between replicas within one session; session_id, tool_use_id and the actor attributes are the same on every replica
Local observability stack, Grafana dashboardsChangedThe chart can install a local collector. A Substrate agents board sits next to the existing ones
Agent 360SameDrill-down per agent, with suspend and resume shown in the lifecycle
Sandbox telemetryChangedruntime=substrate, driver=gvisor or microvm. See Sandbox telemetry
AlertsNewThe chart can install a PrometheusRule for availability, policy lag, conflicts and unattested templates
Splunk, Galileo, webhooksSameExported from the gateway
RedactionStricter defaultSame rules and profiles, applied in the gateway before it stores or exports a record. A laptop keeps its own user's history whole (profile none); the cluster gateway holds every person's prompts, answers and tool results, so the chart defaults to sensitive: credentials, secrets and PII are replaced in its audit store and in every destination. Set observability.redactionProfile (or config.observability.defaults.redaction_profile) to change it
Batch volumeNewRuns started with --task can be sampled; blocks and lifecycle records are never sampled

Not covered

  • Desktop apps and IDE agents. They need a screen. See Agents and features.
  • ACP guard. ACP runs between an editor and an agent over a local pipe. Fronting an actor that way needs the terminal relay to carry ACP too.
  • Edge Connector. It is for embedded and edge devices, not Kubernetes.
  • Secure Client. Not part of this design.