Route an agent through Aegis¶
The Aegis gateway lets a coding agent use your Aegis account for model requests. It writes the agent's ordinary provider configuration for you, so you do not add an API key, a token or a custom endpoint yourself.
Codex and Claude Code are supported. Each agent is configured separately.
Before you enable¶
- Complete account setup. The gateway needs a signed-in
account and exits
66without one. - Use a supported installed Aegis distribution.
enablechecks the running Aegis executable and credential-helper layout, and exits64if that identity is missing or unsupported. Repair the Aegis global installation withnpm install --global @mithran-hq/aegis@0.9.4; this refusal does not establish whether Codex or Claude Code is installed.
Enable, inspect and disable¶
aegis gateway enable --agent codex
aegis gateway status --agent codex
aegis gateway disable --agent codex
--agent is required and accepts codex or claude. Substitute claude
for Claude Code.
enable writes the managed settings into the agent's own configuration
(~/.codex/config.toml for Codex, ~/.claude/settings.json for Claude
Code), records what it changed, and prints
aegis: gateway <agent> <outcome>. The first enable may also create the
private state chain for the profile.
status prints any detected overrides, then an aegis: engine <operation>
(<outcome>) line and an aegis: helper <code> line. The helper line names
whether the Aegis credential helper was found at the expected installed layout.
disable restores the values the gateway recorded before it enabled them
and clears the agent's gateway cache. It prints its own
aegis: gateway <agent> <outcome> line.
When the gateway refuses¶
The managed-settings transaction refuses rather than overwriting a value you changed. A later status-record or cache-cleanup failure can occur after settings have already changed:
- Exit
64with refused keys. A managed key no longer holds the value the gateway recorded as its own. Restore each named key to the value in the gateway transaction backup, leaving unrelated keys untouched, then run the disable for that agent and enable it again. Running the disable first repeats the same refusal. - Exit
75. Read the exact stage and outcome. Enable can succeed before publishing its status record fails, leaving the agent configured; the diagnostic saysthe gateway is enabled but its helper record was not published. Disable can restore settings before cache cleanup fails, leaving settings restored and cleanup incomplete, withthe configuration was restored but cache cleanup failed. A bounded deadline may also expire. Inspectaegis gateway status --agent codex(or use--agent claude) and follow the printed recovery; do not assume a nonzero exit rolled back the action. - Exit
77. A file the gateway must own has the wrong owner. Fix the reported ownership and retry.
Do not edit the managed provider settings by hand and do not add your own provider credentials beside them. Keys the gateway does not own are left alone.
The deployed application is separate¶
The gateway routes local model requests. It establishes nothing about Forge deployments. Your GitHub credentials publish source, and the Forge GitHub App's grant covers repository access during deployment; see Connect GitHub and Security and trust.
Full-product protected runtime¶
The separate full Aegis product, distributed as a signed macOS .pkg,
adds a protected agent runtime around the same agents. None of the
following is required for, or part of, the npm launcher journey above:
- a macOS Seatbelt sandbox and an allowlisting egress proxy;
- hard-isolation tiers that start from a clean guest profile;
- protected Claude as the only supported Claude path, where
AEGIS_CLAUDE_PROTECTED=0returnsprovider_runtime_not_available; - session configuration composition and managed hooks;
- method enforcement that gates the agent's first file change and session closure.
Those features belong to the full product's documentation. They are not prerequisites for installing, signing in, routing an agent or deploying with the reduced CLI. Do not follow full-product setup steps to satisfy a reduced-CLI requirement.
Secret handling¶
Keep repository credentials, private keys and runtime secrets out of instructions, logs and committed files. Support reports should name the profile and agent, and the printed outcome, without copying configuration values.