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
| Area | Purpose |
|---|
web/ | Next.js control plane, Postgres state, boards, review, and promotion |
supervisor/ | Fastify daemon that owns ACP sessions and agent processes |
mcp/ | MCP facade for governed agent access to MAIster operations |
site/ | EN/RU product website published at imaister.dev |
site-docs/ | EN/RU public product documentation |
docs/ | Engineering contracts, architecture, APIs, and operating details |
.ai-factory/ | Plans, adversarial reviews, ADR context, and the design record |
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.
| Package | Built on |
|---|
aif | AI Factory: spec-driven delivery Flows (dev, bugfix, evolve, roadmap, init, loop, qa) with the vendored skills and agents |
pstack | pstack: evidence-first engineering Flows with typed result profiles and an Evaluation Method |
superpowers | Superpowers: governed Flows with structured design, verification, and review handoffs |
openspec | OpenSpec: spec-driven change Flows with typed change and review handoffs |
spec-kit | Spec Kit: Spec-Driven Development Flows |
bmad-bmm | BMAD Method: planning and build Flows, upstream skills, and platform agents |
bmad-tea | BMAD Test Architect: quality Flows and the Murat agent |
bmad-cis | BMAD Creative Intelligence Suite: a governed discovery Flow and creative agents |
core, core-java, core-react, core-pg, core-skill-authoring, env-e2e | First-party MAIster packages: triage, Project Brain, and evaluation agents; stack skills for Java, React, and PostgreSQL; skill authoring; an ephemeral docker-compose end-to-end environment as readiness evidence |
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.
