Self-hosting

Requirements

There are two ways to run it. Docker is the simplest and the one this page leads with. Running from source gives you the same server without containers.

The server listens on PORT, which defaults to 3000. Postgres 17 is the only datastore. There is nothing else to run.

Quick deploy (evaluation)

One command brings up a postgres:17 container and the server, seeds the demo agents and accounts, and prints two API keys you will need.

# postgres:17 + the server, seeded with the demo. Good for evaluation.
docker compose up

# Watch the boot logs. With seeding on, the server prints two API keys ONCE:
#   [makerchecker] DEMO ADMIN API KEY (shown once - copy it now): mk_...
#   [makerchecker] DEMO OFFICER API KEY (for approving gated decisions): mk_...
# Copy both now. They are not shown again. The API listens on :3000.

This is the single-role configuration. The server connects to Postgres as the database owner and runs migrations at boot. It is the fastest way to look at the product, and the seeded demo includes the recon-preparer agent and the txn-match@1 skill, with segregation of duties blocking recon-preparer from also approving its own work (the conflicting role is recon-approver-role).

The owner can disable the append-only audit triggers. That is fine for evaluation and wrong for production. For tamper-resistance against a compromised application credential, use the hardened deployment below.

Hardened deploy (production)

The hardened compose file splits the database work across two roles. A one-shot migrate step applies migrations as the owner. A one-shot harden step runs ops/harden-db.sql as the owner to create a restricted role, mc_app_runtime. The long-lived server then connects as that restricted role.

# Two-role deployment. Set a strong runtime password first.
MC_RUNTIME_PASSWORD=$(openssl rand -hex 24) \
  docker compose -f docker-compose.hardened.yml up --build

# Order is enforced by the compose file:
#   postgres healthy
#     -> migrate  (connects as the owner, applies migrations)
#     -> harden   (owner runs ops/harden-db.sql, creates mc_app_runtime)
#     -> server   (connects as mc_app_runtime, MAKERCHECKER_SKIP_MIGRATE=1)

The runtime role can read and write mutable run-state and can INSERT audit rows, but it cannot UPDATE, DELETE, or TRUNCATE the audit_events table, and it cannot disable the triggers that enforce append-only writes. It does not own the tables, so it cannot grant itself those rights back.

Two settings make this work, and the compose file sets both:

• MC_RUNTIME_PASSWORDis read by the harden step and used in the server's connection string. Set it to a strong value.
• MAKERCHECKER_SKIP_MIGRATE=1 on the server, because the runtime role lacks CREATE on the public schema and cannot run migrations itself. The owner already applied them.

Configuration

Configuration is environment variables. Copy .env.example and adjust. Every variable is optional except DATABASE_URL.

A trimmed production file looks like this:

# Minimal production .env. Every variable is optional except DATABASE_URL.

# Point the long-lived server at the NON-OWNER runtime role (hardened deploy).
DATABASE_URL=postgres://mc_app_runtime:<strong-password>@db:5432/makerchecker
PORT=3000

# Browsers block cross-origin reads unless you list your UI origin here.
ALLOWED_ORIGINS=https://makerchecker.internal.example

# The runtime role cannot run migrations; the owner already applied them.
MAKERCHECKER_SKIP_MIGRATE=1

# No model key set -> the scripted, deterministic executor. Fully offline.
# (Set ANTHROPIC_API_KEY or GEMINI_API_KEY only if you want live model steps.)

# Keep auth ON. Do not set MAKERCHECKER_AUTH_DISABLED in production.

Air-gapped operation

MakerChecker is designed to run with no connection to the internet. With no ANTHROPIC_API_KEY and no GEMINI_API_KEY set, agent steps run on the scripted executor: deterministic, repeatable, and entirely local. The server never phones home.

That means you can run the whole control plane inside a network with no egress. Nothing about authorization, approvals, or the audit depends on a remote service. If you do want live model steps later, setting one provider key is the only change, and you can pin it off again with MAKERCHECKER_EXECUTOR=scripted.

The audit is verifiable offline as well. The records are hash-chained and the export is signed, so an inspector can check the chain and the signature without reaching any server. See The audit trail for the verification procedure.

Authentication and API keys

Every /api route requires a Bearer token. Keys are issued in the form mk_... and are presented as Authorization: Bearer mk_.... The seeded demo prints an admin key and an officer key once at boot; in a real deployment you create keys through the admin API or CLI.

A request that authenticates looks like this:

curl https://makerchecker.internal.example/api/agents \
  -H "Authorization: Bearer mk_0123456789abcdef0123456789abcdef"

With the hardened database, a strong MC_RUNTIME_PASSWORD, a restrictive ALLOWED_ORIGINS, and auth left on, the deployment enforces its guarantees against both a network attacker and a compromised application credential. From here, see The audit trail to verify what the server recorded, or the Quickstart to wrap your first tool against the running server.