Skip to content

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 66 without one.
  • Use a supported installed Aegis distribution. enable checks the running Aegis executable and credential-helper layout, and exits 64 if that identity is missing or unsupported. Repair the Aegis global installation with npm 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 64 with 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 says the gateway is enabled but its helper record was not published. Disable can restore settings before cache cleanup fails, leaving settings restored and cleanup incomplete, with the configuration was restored but cache cleanup failed. A bounded deadline may also expire. Inspect aegis 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=0 returns provider_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.