Run agents with Aegis

Use this page to run an AI coding agent inside Aegis's protected runtime. Aegis wraps a coding agent in a confinement boundary, brokers its credentials, controls its network egress, and can enforce an engineering method the agent must follow. Two agents are supported today: OpenAI Codex (aegis codex) and Anthropic Claude Code (aegis claude).

For deploying the software an agent produces, see Deploy. For the security model behind the runtime, see Security and trust.

Command shape

Every agent invocation has the same shape:

aegis [aegis options] <agent> [agent arguments]

The agent token (codex or claude) is a hard boundary. Aegis adds no sub-commands beneath it, and every token after the agent token is passed to the agent unchanged, so any argument the underlying agent accepts works there.

--method-gates is Aegis's control for the agent, not an argument to it, so it goes before the agent token:

aegis codex "refactor the payment module"
aegis --method-gates enforce claude "add retry budgets to the scheduler"

Aegis options go before the agent token; the agent's own arguments go after it. --home and --lima also work in either position. --json and --state-dir are read after the agent token, the same as on every other aegis command (aegis doctor --json). If you place --method-gates after the agent token it is passed through to the agent, which will not understand it.

Protection is on by default

aegis claude runs Claude Code through the protected runtime by default. aegis codex does the same for Codex. In the default (native) tier the agent runs under a macOS Seatbelt sandbox, reaches the network only through an allowlisting egress proxy, and holds no standing credentials: Aegis brokers the model API key into the process environment at launch and never writes it to disk.

To run Claude without protection, set AEGIS_CLAUDE_PROTECTED=0. This is not recommended for real work.

Your agent configuration comes with you

On the default native tier, a protected session is not a blank agent. Aegis materializes your own agent configuration into the session and layers its own contribution on top, so the agent behaves the way you configured it.

The hard-isolation tiers behave differently: a Lima or Firecracker session starts from a clean guest profile and does not carry your host configuration in. See Extensions depend on the isolation tier.

Carried in	Left behind
Your instructions file (CLAUDE.md), skills, subagents, settings, output styles, and plugins	Session history, transcripts, project records, and caches

Aegis adds four things and nothing else: its method instructions (appended to your instructions file inside marked delimiters, leaving your text untouched), its own skills alongside yours, the enforcement hooks, and the tools the Aegis package installs. Where the two collide, Aegis's contribution wins and the session verifies that it survived, rather than replacing your configuration to guarantee it.

Credentials are never copied into a session. Aegis brokers the model credential into the process environment at launch.

Aegis does not grant permissions for you

Deciding what an agent is allowed to do is yours, not the runtime's. Aegis confines the session — sandbox, egress allowlist, brokered credentials — but it does not enable tools or approve permissions on your behalf.

This matters for unattended runs. Claude Code asks for approval interactively, so a configuration that relies on prompting grants nothing to a headless run, and such a run cannot edit files. If you want unattended runs to do work, grant it in your own settings, for example:

{ "permissions": { "allow": ["Read", "Write", "Edit", "Bash"] } }

Extensions depend on the isolation tier

MCP servers and plugins are executable, so how much of your setup comes with you depends on how isolated the session is:

• Native (macOS Seatbelt) — your configuration is carried in, including your MCP servers and plugins, and the launch warns you that those extensions are active. This tier exists so real tooling keeps working; the sandbox and egress allowlist bound what it can reach.
• Lima and Firecracker — the guest starts clean. Neither your extensions nor your host configuration are carried in. These are the hard-isolation tiers, and what stays on the host stays on the host.

What you need to run an agent

Protected-worker launch requires signed-in Mithran access, the codex CLI, Lima with limactl, and completed aegis setup. Aegis uses the signed-in account for model access through its LLM proxy. See Sign in.

You do not need a GitHub connection to run an agent. GitHub is required only when you deploy or push, and Aegis requests it at that point. See Connect GitHub, which is a deploy-time step.

Complete aegis setup before launching the protected worker. Setup prepares the managed hooks and local configuration required by the protected runtime.

Check readiness at any time:

aegis doctor --json

Enforcement modes

Aegis can supply an engineering method to the agent as advice, or enforce it as a gate. Select the mode with --method-gates, placed before the agent token:

Mode	Behavior
off	No method is applied.
advise	The method is provided to the agent and findings are surfaced as context. Nothing is blocked. This is guidance.
enforce	A deterministic gate sits in the agent's action path. The agent's first file change is denied until it has authored a valid plan with a falsifiable check, and session closure is blocked until the closure conditions are met.

aegis --method-gates enforce claude "implement the feature described in issue 214"

The method being enforced is the Aegis Method: before changing code, the agent must write down a plan and a falsifier (a check that would prove the change wrong), must not silently rewrite that commitment, and must close the session with an explicit completion argument rather than an unsupported claim of done. The gate speaks the agent's native hook protocol, so the denial takes effect whether or not the model cooperates.

What enforcement does and does not guarantee

Enforcement guarantees process integrity and honesty: a real plan before a mutation, no silent rewrite, and no false claim of completion. It does not make a model capable of a task beyond its ability. On a task the model cannot actually complete, the enforced gate still holds the agent to an honest process and refuses a false "done", but the delivered code can still fall short. Enforcement is a control on how the agent works, not a guarantee that the work succeeds.

Manage a running session

Session control is the same regardless of which agent is running:

aegis session status <id>      # show a protected session
aegis session stream <id>      # stream its events
aegis session steer <id> ...   # send an instruction
aegis session interrupt <id>   # interrupt it
aegis session stop <id>        # stop it and tear down its workspace

Check that a model can meet the method floor

Before relying on enforced mode for a given model, you can probe whether that model can satisfy the delivery floor:

aegis probe-capability --agent codex --model <model> --budget <tokens>
aegis probe-capability --agent claude --model <model> --budget <tokens>

The probe runs the model through the same protected runtime that the verdict gates, so a verdict describes the model as it will actually run. Verdicts are recorded per agent: a Codex verdict does not satisfy Claude, and the reverse.

Enforced Codex requires an above-bar verdict for the model you launch. Without one the launch is refused and the error names the probe command to run.