> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superworker.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Local quickstart

> Start the Superworker applications with a local PostgreSQL database.

## 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

```bash theme={null}
pnpm install
docker compose up -d
```

## Configure the local environment

```bash theme={null}
export DATABASE_URL='postgres://superworker:superworker@127.0.0.1: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

```bash theme={null}
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

```bash theme={null}
pnpm docs:dev
```

Open `http://localhost:3002`. The documentation preview runs independently and
needs neither PostgreSQL nor application secrets. See
[documentation development](/apps/docs/development) for editing and publishing.

## Troubleshooting

### PostgreSQL port is already in use

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

```bash theme={null}
POSTGRES_PORT=55432 docker compose up -d
export DATABASE_URL='postgres://superworker:superworker@127.0.0.1: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](https://github.com/superworker-ai/mcp/blob/main/docs/LOCAL-DATABASE-RENAME.md)
before starting the new Compose volume.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.