Skip to content

Run agents with Aegis

Aegis wraps a coding agent in a protected runtime on your machine. Two agents are supported today: OpenAI Codex and Anthropic Claude Code, each launched through its protected Aegis launcher. The runtime boundary, credential broker, and network policy are separate from the Forge deployment surface.

Protection is on by default

In the default tier the agent runs under a macOS Seatbelt sandbox, reaches the network only through an allowlisting egress proxy, and holds no standing provider credentials. Protected model requests are routed through the account-bound Aegis LLM proxy established by account setup. You do not configure a provider token, API key, or endpoint for the protected session.

Protected Claude is the only supported Claude path. Setting AEGIS_CLAUDE_PROTECTED=0 returns provider_runtime_not_available; the variable does not select an unprotected session, because no unprotected launch path is available.

Your agent configuration comes with you

A protected session is not a blank agent. Aegis composes your agent configuration with its own contribution inside a session home. Composition is provider-specific and selective; it is not a copy of your whole configuration.

  • Codex imports only defined areas of your configuration: MCP servers, marketplaces, and plugins, when the tier allows them. Your hooks are preserved, and Aegis re-adds its managed hooks beside them. Codex sessions also receive Aegis skills.
  • Claude copies an allowlist of paths: your instructions file, settings, agents, skills, plugins, output styles, and MCP configuration. Where Aegis supplies a file at the same path, it replaces yours; Aegis does not merge file contents. Claude sessions currently receive no Aegis skills.

Session history, transcripts, project records, and caches are never copied into a session. Provider credentials are never copied into a session either.

Some Aegis commands write outside provider configuration by design. Setup may install a repository pre-push guard and reports that action.

Hard isolation

The hard-isolation tiers start from a clean guest profile and do not carry your host configuration or extensions in. What stays on the host stays on the host.

Authority separation

The operator's GitHub authority controls ordinary source-control operations. Forge App authorization begins only when deployment requires repository access. Forge derives environment, tenant, account, installation, and app identity from authorization and repository context. See Account setup and authorization.

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.

Method enforcement

Aegis can supply its engineering method to the agent as advice, or enforce it as a gate. In enforced mode 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. The gate controls process integrity, not task success.

Secret handling

Keep repository credentials, private keys, and runtime secrets out of instructions, logs, and committed files.

Scope

This page describes the protected runtime at a high level. It does not add an unsupported Aegis invocation, a Forge selector, a repository workflow, or a hosted deployment claim. Read Deploy for the frozen Forge customer path and Security and trust for authority boundaries.