Quickstart¶

Goal: take a small HTTP app from a fresh repo to a live URL. Budget about ten minutes, most of it waiting on the first build.

We'll use a trivial Node app as the example. Any language works as long as it builds with a Dockerfile and serves HTTP on $PORT.

1. Install the CLI¶

curl -fsSL https://get.mithran.cloud/aegis | sh
aegis version

Details and verification steps are in Install the CLI.

aegis setup

This signs you into Mithran and walks you through installing the Forge GitHub App on your account. When it asks you to install the App, follow the link it gives you. Don't go straight to GitHub's app page, or the callback won't have the context it needs. See Connect GitHub if you hit a snag.

3. Create a tiny app¶

In an empty repo:

server.js

const http = require("http");
const PORT = process.env.PORT || 8080;
http.createServer((req, res) => {
  if (req.url === "/health") { res.writeHead(200); return res.end("ok"); }
  res.writeHead(200, { "content-type": "text/html" });
  res.end("<h1>Hello from Forge</h1>");
}).listen(PORT);

Dockerfile

FROM node:22-alpine
ENV PORT=8080
WORKDIR /app
COPY server.js ./
EXPOSE 8080
CMD ["node", "server.js"]

Commit and push to main.

4. Onboard the repo¶

map onboard <you>/<your-repo> --repo-dir .

Onboarding does three things: registers the repo with the control plane (so it's allowed to deploy), writes a mithran.yaml describing your app, and adds .github/workflows/map-deploy.yml, the workflow that triggers deploys. Commit the two new files:

git add mithran.yaml .github/workflows/map-deploy.yml
git commit -m "Onboard to Forge"
git push

Onboarding takes effect immediately. There's no control-plane restart and nothing to wait for.

5. Ship it¶

Push a release branch (or tag a release):

git switch -c release/v1
git push -u origin release/v1

The push fires the map-deploy workflow. Watch it in your repo's Actions tab. It mints a GitHub OIDC token, exchanges it for a short-lived Forge token, and posts the deploy to the control plane. The control plane reviews the commit, builds the image, and routes it.

When the workflow goes green:

curl https://<your-repo>.apps.sandbox.mithran.cloud/

You should get your HTML back. That's a live deploy.

What just happened¶

flowchart LR
  A[git push release/**] --> B[GitHub Actions]
  B -->|OIDC token| C[Forge auth]
  C -->|short-lived token| D[Control plane ingress]
  D --> E[Review commit]
  E --> F[Build image]
  F --> G[Deploy + route]
  G --> H[Live at *.apps.sandbox.mithran.cloud]

No secret was stored in your repo. The deploy authenticated with a token that GitHub minted for that one workflow run and that expires minutes later. More on that in How Forge works.

Next¶

Change the app and ship again by pushing another release/** branch or bumping a tag.
Learn what you can put in mithran.yaml.
Read the CLI reference.