MAIster

Self-hosted execution and governance for reproducible AI-powered software
delivery over private code.

Website ·
Public documentation ·
Getting started ·
Architecture ·
Releasing

Status: beta until v1.0 — the beta ends with full multi-host support.
Versioning and release mechanics are described in RELEASING.md.

Coding agents can write code. MAIster makes the process around them repeatable:
versioned delivery flows, isolated workspaces, scoped capabilities, human
decisions, evidence gates, cost controls, and promotion to a pull request or
local target branch.

The 60-second model

Task → version-pinned Flow → isolated worktree → ACP coding agent
     → human input + evidence gates → review → PR or local merge

• One control plane: see projects, active workspaces, tasks, and requests
  for human input without babysitting a wall of terminals.
• Reproducible process: install and pin Flow packages that compose agents,
  CLI steps, gates, bounded rework, consensus, and orchestration.
• Governed execution: materialize only the capabilities a session needs,
  enforce guardrails at the Agent Client Protocol (ACP) boundary, and retain an
  auditable run ledger.
• Evidence before delivery: validate typed artifacts, readiness, diffs, and
  budgets before work reaches the target branch.

MAIster is designed for a technical owner or small engineering team operating
multiple private repositories and coding agents on its own infrastructure.

What is here

The web tier and supervisor run as separate Node processes on the same host and
communicate over HTTP and server-sent events. PostgreSQL is the durable control
plane store; run workspaces use Git worktrees. External ACP adapters remain the
agent runtimes.

Quick start

Prerequisites: Node 24, pnpm, Git, Docker with Compose, and a coding agent
signed in on this host (Claude Code, Codex, Gemini CLI, OpenCode, or MiMo).
Only Postgres runs in Docker; the web tier and the supervisor run on the host
because they spawn agent CLIs and work on local git repositories. Linux and
macOS are supported; on Windows run everything inside WSL2 with Docker
Desktop's WSL integration.

One command clones the repository, installs dependencies, writes the env files
with a generated AUTH_SECRET, starts Postgres, applies the migrations, and
builds the MCP facade:

curl -fsSL https://imaister.dev/quickstart.sh | bash

The script is scripts/quickstart.sh. Read it first if
you prefer, then run ./scripts/quickstart.sh from a checkout; it never
overwrites an existing env file and is safe to repeat. Then start both host
processes:

cd maister
pnpm dev        # supervisor on :7777, web on :3000

Open http://localhost:3000/login and sign in as [email protected] with
the password maister-admin; the first login asks for a new one. Before the
first Run, open Settings → ACP runners: on a fresh install the first visit
registers a native runner for each adapter found on the host (for example
claude-code); wait for Ready. Then
add a repository under Projects → Add project (a manifest that names a
default_runner needs that runner Ready first).

git clone https://github.com/maister-dev/maister.git
cd maister
pnpm install --frozen-lockfile

cp .env.example .env
cp web/.env.sample web/.env.local
cp supervisor/.env.sample supervisor/.env

# Put the output in AUTH_SECRET in web/.env.local before starting the web tier.
openssl rand -base64 33

docker compose up -d --wait postgres
pnpm --filter maister-web db:migrate
pnpm --filter maister-web db:migrate:brain
pnpm --filter @maister/mcp build

Then run the two processes in separate terminals:

pnpm --filter @maister/supervisor dev    # http://localhost:7777
pnpm --filter maister-web dev            # http://localhost:3000

The complete setup, adapter requirements, database workflow, and first-run
checks are in Getting Started.

Project status

MAIster is under active development and is already dogfooded for governed agent
delivery. It is suitable for evaluation and self-hosted experimentation, not a
turnkey production platform. Current productization gaps include stronger
process/container isolation, OIDC/SSO/MFA and organization administration,
automated backup/restore drills, notification routing, and broader end-to-end
qualification. See the Product View for current scope.

Coding agents

MAIster drives coding agents through the
Agent Client Protocol (ACP) and its
vendor-neutral SDK.
The supervisor spawns one adapter process per session and enforces
capabilities at that boundary.

Agents run with the authentication configured on the execution host, including
subscription-backed sessions. API providers such as Anthropic, OpenAI, and
Anthropic-compatible gateways are runner configuration, with secrets referenced
by environment variable name only.

Packages and the methods behind them

Ready-made Flow packages live in
maister-plugins. Each package
is pinned by its own git tag and installs from Settings → Package sources.

Documentation

MAIster is built with AI Factory, and
the repository deliberately keeps that engineering record in
.ai-factory/: implementation plans, reviews, and the reasoning
that shaped the current architecture. The same method ships as the aif
package above.

Contributing and security

Contributions are welcome. Start with CONTRIBUTING.md, follow
the Code of Conduct, and use the private route described
in SECURITY.md for vulnerabilities. Please do not open public
security issues.

License

MAIster is available under the MIT License.