Self-Hosted

Run PocketBase, the MCP gateway, and the workflow editor locally. No cloud dependency, no external API keys. BYO Ollama.

Prerequisites

• Docker and Docker Compose
• Git
• Pi, Claude Code, or Codex installed

Quick Start

git clone https://github.com/statewright/statewright.git
cd statewright/self-hosted
docker compose up --build

First build takes a few minutes (Rust compilation). Subsequent starts are fast.

The first-start docker compose logs print a locally issued gateway API key. Treat those logs as sensitive. In the terminal where you will launch an agent, enter that key without adding it to shell history:

read -r -s STATEWRIGHT_API_KEY
export STATEWRIGHT_API_KEY

The examples below use this local key. A production key or an old ~/.statewright/api_key file must not be used against the self-hosted gateway. Run unset STATEWRIGHT_API_KEY when you are done with this terminal.

Connect Your Agent

Pi

pi install /path/to/statewright/plugins/pi
cd /path/to/statewright/plugins/pi && npm install
export STATEWRIGHT_GATEWAY_URL=http://localhost:3001
pi

Claude Code

From the cloned repository, load the local plugin with its bundled MCP proxy. Do not also add a second Statewright server in .mcp.json; that would create another client session.

STATEWRIGHT_GATEWAY_URL=http://localhost:3001 \
STATEWRIGHT_PB_URL=http://localhost:8090 \
claude --plugin-dir /path/to/statewright/plugins/claude-code

Codex

codex plugin marketplace add statewright/statewright
codex plugin add statewright@statewright

The default self-hosted stack issues a local bootstrap key. Set STATEWRIGHT_GATEWAY_URL to http://localhost:3001/mcp and pass that key as a process-scoped STATEWRIGHT_API_KEY when starting Codex. Keep it out of shell history and project files. The hosted browser-approval flow needs an authorization service; it does not automatically apply to this local stack.

If you launch Codex through a configured gateway profile instead, provide both the gateway URL and its authorization-service URL as described in the OAuth login guide.

Load a Workflow

From any connected agent:

> load the agentic-engineering workflow, then fix the failing tests

The gateway ships with the agentic-engineering workflow template. Create custom workflows through the UI at http://localhost:8080 or via MCP tools.

Add Ollama

The self-hosted stack doesn't include Ollama — bring your own. If you're using Pi with local models:

ollama serve &
pi --model ollama/gemma4:12b

Data

All state is persisted in a Docker volume (pb_data). To reset:

docker compose down -v
docker compose up --build

Private Discord Operations Feed

Production deployments can run the optional statewright-discord-ops sidecar. It receives authenticated local notifications from PocketBase and posts them to a private Discord ops channel. The application emits new-account, workflow, API-key, first-plugin-install, and first-workflow-run events. A user with no activation signal after the configured window produces one durable stalled-activation alert, with an optional email copy for the operator.

Set these deployment-only values in a secret named statewright-ops-secrets; do not commit them:

DISCORD_BOT_TOKEN=...
DISCORD_BOT_SECRET=...
DISCORD_OPS_CHANNEL_ID=...
OPS_ALERT_EMAIL=ops@example.com
SMTP_HOST=...
SMTP_PORT=587
SMTP_USERNAME=...
SMTP_PASSWORD=...
SMTP_SENDER_ADDRESS=noreply@example.com

Enable the feed with DISCORD_OPS_NOTIFICATIONS=true. Set OPS_FUNNEL_WATCH_ENABLED=true to enable stalled-activation alerts; OPS_FUNNEL_ALERT_MINUTES defaults to 30. Leave the values unset outside production to keep development and staging quiet.