Skip to content

Configure your app

Forge reads mithran.yaml from the repository root. Commit it with the application source so each deployment uses the configuration of its commit.

Initialize the repository

Run initialization from the application's repository root:

aegis forge init

Initialization is local: it reads the working tree and writes at most mithran.yaml and index.html. It makes no network request and does not need a signed-in account.

Existing manifest

When mithran.yaml already exists, initialization validates it and leaves it unchanged, printing Forge is already initialized (mithran.yaml is valid). An invalid manifest is refused with the finding and a request to fix it, so correct the reported field and rerun. A retained forge.mithran/v1 manifest is still accepted when valid; new starters use map.mithran/v1.

Existing static application

Without a manifest, initialization writes one when the directory has a root index.html and none of package.json, Cargo.toml, pyproject.toml, requirements.txt, go.mod or Dockerfile. It preserves the existing source and creates only the manifest.

New application

An empty directory, or one containing only .git, receives the static starter and an index.html:

apiVersion: map.mithran/v1
kind: MithranApp
metadata:
  app_id: my-app
  name: my app
identity:
  project_ref: owner/my-app
capabilities:
  - kind: http
    route: /
    runtime: static
    startup:
      command: python3 -m http.server 8000

metadata.app_id is a lowercase slug of the directory name, and identity.project_ref is the GitHub repository from the Git origin, or local/<app-id> when there is no origin. Initialization prints created mithran.yaml and index.html, then next: review mithran.yaml, then commit and push your application.

When initialization refuses

Automatic detection covers only the root static layout. A directory without a root index.html, or one containing a build manifest from the list above, is refused as ambiguous:

cannot unambiguously detect an existing static application: automatic detection requires a root index.html without a package or build manifest; provide mithran.yaml for your application, then rerun aegis forge init

Write mithran.yaml for the app's real runtime using Manifest reference, then rerun initialization to validate it. Initialization never chooses a framework or rewrites source.

aegis forge init --json reports {"ok":true,"workspace":"<dir>","created":[...]} for the same outcome. A refusal exits 64.

Before deploying

Review the manifest and source, test the app locally, and keep credentials and private keys out of both. Read HTTP app contract for runtime behaviour, then commit and push the reviewed files before requesting deployment.