Sign in¶
Run setup once on each developer machine that will use Forge. Run it again when
aegis doctor --json reports missing or expired local account access.
Protected-worker launch requires signed-in Mithran access, the codex CLI, Lima
with limactl, and completed aegis setup; see
Run agents with Aegis. Connecting GitHub is a separate,
deploy-time step and is not required to run an agent.
Use aegis setup for local Mithran sign-in, local profile state, and any setup
handoff that Aegis prints for the customer account. Do not treat setup itself
as proof that a specific repo is granted. For repo-scoped evidence, run:
What setup proves¶
| Question | Evidence |
|---|---|
| Is the developer signed in locally? | aegis setup --json with ready: true, or aegis doctor --json. |
| Is the local profile blocked on a required action? | aegis setup --json with status: blocked, blockers, and next_action. |
| Is a specific repo granted to the Forge GitHub App? | aegis github status --project-repo <owner/repo> --require --json. |
Keep these separate. A ready setup can still be missing a repo grant, and a GitHub App can be installed without the target repo being selected.
Developer flow¶
In an interactive terminal, aegis setup opens browser sign-in when the local
Mithran account session is missing. When GitHub App access is required, setup
can also open the Forge GitHub setup handoff for the customer account. Use that
handoff; it links the GitHub installation back to your Mithran setup profile.
If a browser cannot be used on that machine, run:
That path uses device authorization for Mithran sign-in instead of the browser loopback flow.
When setup is ready, it writes local profile state and points you at the next command. For Forge deploy work, continue with GitHub connection and repo onboarding.
Use --no-browser only when the machine cannot complete the browser loopback
flow. In that mode, follow the device authorization instructions printed by
the CLI, then re-run aegis setup --json or aegis doctor --json to prove
readiness.
Read setup output¶
Without --json, setup prints a human-readable readiness summary and the next
action when setup is blocked.
For automation or a support bundle, use:
Use these fields:
| Field | Meaning |
|---|---|
schema_version |
Setup report schema, aegis.setup.v0. |
status |
ready when setup has no blockers; blocked when action is required. |
ready |
Boolean readiness value for scripts. |
checks |
Component-level setup checks and messages. |
blockers |
Machine-readable reasons setup cannot finish. |
next_action |
The next operator or developer action, including a URL when setup has one. |
next_command |
Command to run after setup is ready. |
github_operator_auth |
GitHub operator authorization state. |
github_setup |
Forge GitHub App setup handoff and verification state. |
aegis setup exits non-zero when setup is still blocked. Treat ready: true
as the success signal, not the presence of a partially written local profile.
Admin flow¶
To approve or install the GitHub App, admins use GitHub and the customer setup
link. That approval step does not require running the developer's local
aegis setup command.
The admin chooses whether the App can access all repositories or only selected repositories. Choose the smallest repository set that covers the apps your team will deploy.
Use the setup endpoint and GitHub App name shown by the customer account setup link.
Admin approval is not the same as repo readiness. After the App is installed or repository selection changes, the developer or operator should run:
That command proves whether the selected repo is covered by the GitHub App grant for the current account context.
Check readiness¶
doctor reports local setup state, Mithran auth, account access, Aegis
component readiness, and the workspace-scoped GitHub App grant when a repo is
in scope. If no GitHub repository is in scope for the current directory, the
GitHub App grant is not applicable for that doctor run.
For release evidence or admin review, use the explicit repo check:
Use the evidence that matches the question being answered:
| Question | Evidence |
|---|---|
| Is Aegis installed on this machine? | aegis version --json |
| Is this developer machine ready? | aegis doctor --json |
| Can Forge use this repo through the GitHub App? | aegis github status --project-repo <owner/repo> --require --json |
If setup or doctor reports a missing piece, use Troubleshooting.