This guide starts MAIster from source on one host. Only Postgres runs in Docker; the web and supervisor processes run on the host because they launch agent adapters and operate on local git repositories.

​
Prerequisites

  • Node.js 24
  • pnpm
  • git with worktree support
  • Docker with Compose
  • A local git repository to manage
  • At least one coding agent to run on the supervisor host: Codex, Claude Code, OpenCode, Gemini CLI, or MiMo
  • Linux or macOS. On Windows, run every step inside WSL2 (Ubuntu) with Docker Desktop’s WSL integration enabled; Flows run CLI steps through bash and package installs create symlinks, so a native Windows install is not supported

​
1. Install

One command clones the repository into ./maister, installs dependencies, writes the environment files with a generated AUTH_SECRET, starts Postgres in Docker, applies the migrations, and builds the MCP facade:
The script is scripts/quickstart.sh in the repository. It never overwrites an existing environment file and is safe to run again. To use a Postgres you already run, export DB_URL before the command; that database needs the pgvector extension. If you prefer to do the same by hand:
Set a strong AUTH_SECRET in web/.env.local (openssl rand -base64 33 generates one). Keep provider tokens and agent credentials on the host; never add them to a project manifest.

​
2. Prepare a coding agent

MAIster cannot execute a Flow until the supervisor host has an authenticated coding agent. pnpm install provides the Claude and Codex ACP adapters. For example, authenticate Codex with:
For Claude Code, OpenCode, Gemini CLI, or MiMo, complete the agent’s native sign-in under the same operating-system account that runs the supervisor. The Gemini, OpenCode, and MiMo executables must also be available on that account’s PATH. Provider secrets may instead be exposed to the supervisor through environment references; never store them in a project manifest.

​
3. Start Postgres and prepare the database

The quickstart script has already done this. By hand:
The Brain migration requires the pgvector-enabled Postgres image from the repository’s Compose file. The migrations create the first administrator.

​
4. Start MAIster

One command starts the supervisor on port 7777 and the web application on port 3000, with each process’s output prefixed by its name:
To run them in separate terminals instead:
Open http://localhost:3000/login and sign in as admin@maister.local with the password maister-admin. MAIster asks for a new password on the first login.

​
5. Register the coding agent

Open Settings → ACP runners, create a profile for the authenticated agent, and keep it disabled until diagnostics report Ready. Enable the profile and, if appropriate, make it the installation default. Do not launch the first task until at least one runner is enabled and Ready. See Configure ACP runners and models for provider routes, environment references, and readiness rules.

​
6. Register a repository

Open Projects → Add project, choose an existing repository directory, and submit it. If the repository has no maister.yaml, MAIster creates a minimal manifest. A present but invalid manifest is rejected and never overwritten.

​
7. Launch a task

  1. Open the project board.
  2. Create a task with an outcome and a Flow.
  3. Launch the task.
  4. Follow the Run page until the Flow finishes or requests human input.
  5. Inspect the diff, evidence, and readiness state before promotion.
Success means the Run has an isolated workspace, a recorded Flow revision, and an observable outcome. Promotion remains a separate, explicit action.

​
Next steps