Account setup¶
Aegis account sign-in uses the browser. No token is copied into a command, configuration file or environment variable.
Sign in¶
Aegis prints aegis: sign-in URL: <url> and tries to open that URL in your
browser. Finish the account and consent prompts there. The command waits up
to two minutes for the browser callback.
On a host without a usable browser, prevent the launch and open the printed URL yourself:
The callback listens on 127.0.0.1, so the URL must be opened on the same
machine that runs the command. A browser on another machine cannot complete
the flow.
Version 0.9.4 prints nothing after a successful sign-in. A later release adds
a short, non-secret confirmation. Check the session with aegis auth status.
Inspect and clear the session¶
Status is read-only and human-readable. It prints the active profile, for
example profile mithran (namespace mithran, digest 8f78a8177015e447),
followed by the signed-in account, session identifier and remaining session
lifetime. It has no JSON form. When the profile has no stored authority it
reports the profile as signed out and exits 0 without creating state.
Logout clears local authority and prints two non-secret lines:
local_authority: removed|none and remote_revocation: revoked,
not_applicable, unavailable, failed or refused. It exits 0 when
local authority is cleared, including when the remote result is
unavailable; 75 when the remote result is failed; and 77 when it is
refused. Running it while signed out prints local_authority: none and
remote_revocation: not_applicable, and exits 0.
Profiles, home and state¶
The defaults are enough for ordinary use; the selectors exist for separate accounts or isolated stores.
- Home. Aegis uses your account home as the operating system reports it
rather than
HOME,AEGIS_HOMEorAEGIS_STATE_DIR. Changing those environment variables does not isolate configuration or state. - Connection profile.
--connection <name>selects a named profile. Without it, Aegis usesactive_profilefrom the config file, defaulting tomithran. - Config file.
--config <path>selects a different user-owned config file. The default is<home>/.aegis/product/config.toml; when that file is absent, Aegis uses its built-inmithranprofile. - Alternate home.
--agent-home <DIR>selects a private alternate home for defaults and native agent targets. The directory must be absolute, already exist, be owned by the effective user, have mode0700, and be disjoint from your account home. Ordinary users do not need it. - State root. The default is
<home>/.aegis/product/state/<namespace>-<digest>.namespaceis the selected profile's own label, anddigestis a 16-character hex digest of that profile's descriptor, so two different profile descriptors never share a store.--state-dir <DIR>selects an existing, absolute,0700, effective-user-owned directory with trusted ancestry. It selects the state root; it never selects a profile.
Legacy endpoint variables do not override the selected connection profile.
A nonempty conflicting AEGIS_MITHRAN_AUTH_URL,
AEGIS_FORGE_CONTROL_PLANE_ENDPOINT or AEGIS_LLM_PROXY_ENDPOINT causes
exit 64. A value matching the selected endpoint is allowed; comparison
includes scheme, host, port, path and query, with a trailing slash treated
as equivalent. Unset or empty values are ignored.
auth login and gateway enable may create the default private state
chain. auth status and auth logout do not create it. Configuration
refusals exit 64; a missing required input exits 66.
Separate authorities¶
| Authority | Established where | Purpose |
|---|---|---|
| Aegis account | aegis auth login |
Identifies the signed-in account and authorizes gateway and Forge requests. |
| Agent gateway settings | aegis gateway enable --agent codex |
Lets Codex or Claude Code use your Aegis account for model access. |
| Your GitHub authority | Your own Git authentication | Publishes application commits. |
| Forge GitHub App | Installation on the owning GitHub account or organization, plus repository access and association with your profile, agent and repository | Lets Forge read one repository for deployment. |
One authority does not establish another. Signing in does not supply Git credentials or authorize a repository.
Next¶
Follow Quickstart to configure an agent and deploy an application.