Local quickstart

Prerequisites

Node.js 22.22.2 or newer within the Node 22 release line.
pnpm 10.33.2, as pinned in the root package.json.
Docker with Compose for local PostgreSQL.

Run these commands from the repository root.

Install and start PostgreSQL

pnpm install
docker compose up -d

Configure the local environment

export DATABASE_URL='postgres://superworker:[email protected]:5432/superworker'
export BETTER_AUTH_SECRET="$(openssl rand -hex 32)"
export SECRETS_KEY="$(openssl rand -hex 32)"

These commands generate temporary development secrets in your shell. Keep BETTER_AUTH_SECRET stable for the lifetime of the database: Better Auth uses it to encrypt signing keys. Use your secret manager for persistent development credentials, including SECRETS_KEY. The root .env.example lists configuration keys. Copying it to .env does not automatically load the values. Export configured values and leave unused optional variables unset.

Apply migrations and run

pnpm db:migrate
pnpm dev

Surface	Local address
Web	`http://localhost:3000`
API health	`http://localhost:8787/api/health`
MCP endpoint	`http://localhost:3001/mcp`
MCP Inspector	`http://localhost:3001/mcp/inspector`

The default local UI and MCP brand tool use deterministic fixtures. Live provider features need their own configuration and credentials.

Preview only the documentation

pnpm docs:dev

Open http://localhost:3002. The documentation preview runs independently and needs neither PostgreSQL nor application secrets. See documentation development for editing and publishing.

Troubleshooting

PostgreSQL port is already in use

Choose an unused port and match it in the connection string:

POSTGRES_PORT=55432 docker compose up -d
export DATABASE_URL='postgres://superworker:[email protected]:55432/superworker'

Then run migrations and start the applications using the commands above.

Existing local database

If you used the repository before its database rename, follow the database rename guide before starting the new Compose volume.

Get started

Agents and automation

Contribute

Prerequisites

Install and start PostgreSQL

Configure the local environment

Apply migrations and run

Preview only the documentation

Troubleshooting

PostgreSQL port is already in use

Existing local database

​Prerequisites

​Install and start PostgreSQL

​Configure the local environment

​Apply migrations and run

​Preview only the documentation

​Troubleshooting

​PostgreSQL port is already in use

​Existing local database

Prerequisites

Install and start PostgreSQL

Configure the local environment

Apply migrations and run

Preview only the documentation

Troubleshooting

PostgreSQL port is already in use

Existing local database