Skip to content

Quickstart

This is the whole customer journey: install the Aegis CLI, sign in, optionally route a coding agent through your account, then deploy committed application source from GitHub with Forge.

Install and sign in

Install the npm launcher and check the version as described in Install Aegis:

npm install --global @mithran-hq/aegis@0.9.4
aegis version

Sign in to your Aegis account:

aegis auth login

Aegis prints aegis: sign-in URL: <url> and opens that URL in your browser. Complete the account and consent prompts there. Version 0.9.4 prints nothing further after a successful sign-in; confirm the session with aegis auth status. See Account setup for the no-browser flow, profiles and sign-out.

Route an agent through Aegis (optional)

The gateway lets Codex or Claude Code use your Aegis account for model requests. Sign-in must succeed first. Enable it for the agent you use:

aegis gateway enable --agent codex

Aegis writes the managed settings into that agent's own configuration and prints aegis: gateway codex <outcome>. Enable claude instead when you use Claude Code, and check the result with:

aegis gateway status --agent codex

Do not add provider keys or edit the managed settings by hand. To remove the gateway's changes later, run the disable action for the same agent, for example aegis gateway disable --agent codex; see Run agents for the exact behaviour and conflict recovery.

Initialize your repository

Forge reads mithran.yaml from the repository root. Commit it with the application source.

Use an existing application

Run initialization from the repository root:

cd /path/to/your-app
aegis forge init

If a valid mithran.yaml already exists, initialization validates it and leaves it unchanged. In a directory that has a root index.html and no competing build manifest, it adds mithran.yaml and keeps your source. Other layouts are refused with guidance instead of a guessed framework; correct the manifest as described in Configure your app and rerun.

Create a new application

Create an empty directory and initialize the static starter:

mkdir my-app
cd my-app
aegis forge init
git init

Initialization writes mithran.yaml and index.html, then prints next: review mithran.yaml, then commit and push your application. A directory containing only .git also receives the starter. Edit index.html before deploying.

Publish your source

Create an empty GitHub repository, then connect it and push the commit you want Forge to deploy:

git remote add origin git@github.com:OWNER/REPOSITORY.git
git add mithran.yaml index.html
git commit -m "Prepare app for Forge"
git push -u origin HEAD

Ordinary Git operations use your own GitHub credentials. Forge reads the committed source; uncommitted or unpushed changes are not included.

Deploy

Request a deployment from the repository root:

aegis forge deploy

The default request uses the GitHub origin and committed HEAD. On success the command prints aegis: forge deploy accepted <deployment_ref>. Keep that reference with the commit: it is the record of the request. Forge may need its GitHub App installed and associated with the repository before it accepts a request, and 0.9.4 does not print a setup URL or open a consent page; Connect GitHub explains each state.

What 0.9.4 can and cannot show you

The reduced CLI has no deployment URL command, no hosted status command, and no rollback command. aegis forge deploy prints the deployment reference, and --json adds a redacted evidence envelope. Treat that as the request result. aegis doctor and aegis status currently report the product as a scaffold even when auth, gateway and Forge work — a known 0.9.4 limitation, described in CLI reference.

Update your application

Edit and test the application, commit and push the changed files, then run aegis forge deploy again. Each deployment describes one commit; keep each reference with its commit. A ready deployment does not by itself prove long-term availability. Review App reachability and Security and trust before sharing an app, and Troubleshooting if a step fails.