Installation

Ballast is a Python backend and a Node console that share one database. Nothing else is required to run it. This page walks the manual setup of both services, documents every configuration value, and then shows the Docker path that packages the whole thing into a single command.

Repository layout

ballast/
  backend/               # FastAPI app + orchestration engine
    main.py              # app entrypoint (lifespan, middleware, routers)
    server/              # engine, routers, models, schemas, auth, billing
    tests/               # pytest suite
    requirements.txt     # runtime deps (includes the Postgres driver)
    .env.example         # copy to .env; every value has a working default
  frontend/              # Next.js console + marketing site
    app/(console)/       # dashboard, builder, runs, audit, settings
    app/(marketing)/     # public site + these docs
    .env.local.example   # copy to .env.local; sets NEXT_PUBLIC_API_URL
  docker-compose.yml     # production-shaped local deployment

Prerequisites

• Python 3.11+ (the container image uses 3.12)
• Node.js 20+ and npm
• Optional: Docker with Compose v2, if you want the one-command path in the last section

Backend setup

$ cd backend
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -r requirements.txt
$ cp .env.example .env        # optional — every value has a working default
$ uvicorn main:app --reload --port 8000

The server creates its schema on first start and seeds thirteen templates plus a single local workspace. Two behaviours are worth knowing about:

• Auto-migration. Tables are created with Base.metadata.create_all. On SQLite the startup also applies a small set of additive column migrations, so an older database file gains new columns without a manual step
• Interrupted-run recovery. Any run that was running or pending when the previous process died is marked failedwith the message “Interrupted by backend restart — resume from last checkpoint”. Its checkpoint is intact, so POST /api/runs/{id}/resume picks up where it left off

Console setup

$ cd frontend
$ npm install
$ cp .env.local.example .env.local   # sets NEXT_PUBLIC_API_URL=http://localhost:8000
$ npm run dev

The console runs at http://localhost:3000; the operational views live under /dashboard, /runs, /workflows, and /settings. Its only setting is NEXT_PUBLIC_API_URL, which points the browser at the backend.

Environment-variable reference

Every variable is optional in local development. Without LLM keys, agent nodes use a deterministic mock model; without Slack or email keys, those tools run in simulated mode and report "simulated": true in their output. The tables below group the variables by concern. All of them are backend variables read from backend/.env except the last, which is a frontend variable.

Model providers

Ballast is bring-your-own-key: model provider keys are not environment variables. Each workspace adds its own key as a model connection in the console (Settings → Model connections, or the onboarding wizard) — encrypted at rest and injected only at call time. The keyless mock model runs with no setup.

Database

Authentication

Integrations & alerts

Networking & hardening

Frontend

Model providers

Agent nodes choose a model by name. Ballast is bring-your-own-key: real models run through a workspace model connection with your own provider key (Settings → Model connections). The keyless mock model returns stable, structured text with no setup — ideal for templates, evals, and first runs. A real model with no connected key is blocked with a clear error; it never silently falls back to mock.

SQLite → Postgres

SQLite in WAL mode is the default and is genuinely fine for a single-machine deployment — runs survive restarts because checkpoints are rows, not memory. For anything shared or horizontally durable, point DATABASE_URL at Postgres. The schema is portable SQLAlchemy and is created automatically on first boot:

DATABASE_URL=postgresql://agentos:secret@db.internal:5432/agentos

• The driver already ships — psycopg2-binary is in requirements.txt, used automatically when the URL starts with postgresql://
• Tables are created on startup; there is no separate migration command for a fresh database
• The SQLite-only additive column migrations do not run against Postgres. For column changes to an existing production Postgres database, use Alembic
• Checkpoints, runs, and audit logs are ordinary rows — backup and retention are standard database operations

Health check

The backend exposes an unauthenticated liveness probe. It is exempt from auth in every mode, which makes it safe to point a load balancer or container healthcheck at:

$ curl -s http://localhost:8000/api/health
{"status": "ok", "service": "ballast"}

The Docker path

docker-compose.yml builds and runs both services with a production-shaped configuration: AUTH_MODE=required, SIGNUP_MODE=approval, rate limiting at 300/min, the SSRF guard on, and a persisted SQLite volume. Supply a signing key and an owner password on the command line:

$ SECRET_KEY=$(openssl rand -hex 32) OWNER_PASSWORD=pick-one \
    docker compose up --build

The console comes up at http://localhost:3000 and the API at http://localhost:8000. Because this runs in required mode, sign in at http://localhost:3000/loginwith the workspace owner's email and the OWNER_PASSWORDyou set. The frontend's NEXT_PUBLIC_API_URLis passed as a build arg, and the backend's data persists in a named volume across docker compose down and back up.

Running the test suite

$ cd backend
$ pip install -r requirements-dev.txt
$ python -m pytest tests/ -q

The suite runs against a throwaway database and needs no network and no API keys. It exercises the full lifecycle: CRUD and versioning, structural validation, state passing between agents, condition branches, bounded loops, genuinely concurrent parallel branches (timing-asserted), gate approve and reject, checkpoint resume, cancellation, idempotency keys, WebSocket streaming, the expression sandbox's security cases, the auth and signup modes, evaluations, templates, audit, and metrics.

Next

With both services running, read Core concepts to understand the execution model, build Your first workflow from scratch, or go straight to Self-hosting for the production checklist.