Quickstart

Deploy your own application from GitHub with Aegis and Forge. Start with an existing repository or create a new static app, then open its deployed URL in your browser.

Install and sign in

Follow Install Aegis to verify and install the signed macOS package. Install the supported Codex client separately if you want to use Nexus while building your app.

Sign in to your Aegis account:

aegis auth signin
aegis auth status --json

Complete the authentication prompts in your browser. Aegis manages your account credentials, so you do not need to copy tokens into commands or configuration files.

Enable Nexus in Codex

Enable the managed Nexus profile:

aegis codex enable --model nexus
aegis codex status --model nexus --json

The enable command configures Nexus access and its model catalog while preserving unrelated Codex settings. The managed credential helper supplies authentication without a token in your Codex configuration. If you enabled Nexus before upgrading Aegis, rerun the same enable command to install the current model metadata.

Start Codex in your application directory when you are ready to work:

codex

Initialize your repository

Use an existing application

Open your local repository and initialize its Forge configuration:

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

If the repository already contains a valid mithran.yaml, initialization validates it and leaves its bytes and your application files unchanged. Both forge.mithran/v1 and map.mithran/v1 manifests are accepted when valid for their schema.

For an existing static app with a root index.html and no competing build manifest, initialization adds mithran.yaml while preserving your source. Other layouts require an explicit manifest; initialization stops with guidance rather than choosing a framework or replacing your app.

Read Configure your app if initialization reports an invalid manifest or cannot identify your layout. Correct the manifest before running the command again.

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 creates mithran.yaml and index.html. A directory containing only .git also supports this starter. Edit index.html to build your application before deploying it.

Create an empty GitHub repository under your account or organization. Replace OWNER and REPOSITORY with its names, then add its origin:

git remote add origin git@github.com:OWNER/REPOSITORY.git

Keep the existing origin when working in a repository already connected to GitHub. Your GitHub credentials authorize Git operations separately from your Aegis account.

Publish your source and deploy

Review your application and manifest before committing. For the static starter, publish the files with:

git add mithran.yaml index.html
git commit -m "Prepare app for Forge"
git push -u origin HEAD

For an existing app, stage the intended manifest and application changes with your usual Git workflow. Push the commit you want Forge to deploy. Forge reads committed HEAD from your GitHub origin, so uncommitted or unpushed changes are not included.

Request deployment from your repository:

aegis forge deploy

Complete repository authorization in your browser if Forge requests it. This grants the Forge GitHub App access to your repository; Forge adds no deployment workflow to it.

Open your application

Keep the deployment reference returned by the command. When deployment succeeds and its route is ready, the output includes application_url with your application's HTTPS address. Open that address in your browser.

If the output contains only a deployment reference, inspect it again. Replace DEPLOYMENT_REF with the returned reference:

aegis forge status DEPLOYMENT_REF

Status shows the URL when the deployment succeeds and its route is ready. Pending or failed deployments do not advertise a serving URL. If status succeeds without a URL, follow Deploy instead of constructing an address from the repository name.

Update your application

Edit and test your application, then commit and push the changed files. Run the same deploy command to deploy the new commit. Open the returned URL to inspect the result.

Read Deployment records and CLI reference when you need to inspect versions or restore a previous deployment.

Operating limits

Forge derives environment, tenant, account, installation, and app identity from authorization and repository context. You cannot choose these values through deployment flags.

A ready URL identifies a serving route; it does not establish your app's availability, recovery, or scale requirements. Review App reachability and Security and trust before sharing the app. Use Troubleshooting if a step fails.