Skip to content

Account setup

Aegis account sign-in uses the browser. No token is copied into a command, configuration file or environment variable.

Sign in

aegis auth login

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:

aegis auth login --no-browser

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

aegis auth status

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.

aegis auth logout

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_HOME or AEGIS_STATE_DIR. Changing those environment variables does not isolate configuration or state.
  • Connection profile. --connection <name> selects a named profile. Without it, Aegis uses active_profile from the config file, defaulting to mithran.
  • 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-in mithran profile.
  • 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 mode 0700, and be disjoint from your account home. Ordinary users do not need it.
  • State root. The default is <home>/.aegis/product/state/<namespace>-<digest>. namespace is the selected profile's own label, and digest is 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.