Getting Started

Prerequisites

Node.js 22 or later.
pnpm 12. Corepack installs it.
Docker, for the local Postgres.
Access to poktalabs/budi, and keys for Tenki, Anthropic, R2 and a Privy app (see Configuration).

Install

Clone the repository and install the dependencies. pnpm install also turns on the pre-push hook.
Terminal window
```
git clone https://github.com/poktalabs/budi.git
cd budi
corepack enable
pnpm install
```
Copy the example environment files and put your values in them. Never commit them.
Terminal window
```
cp apps/api/.env.example apps/api/.env.local
cp apps/web/.env.example apps/web/.env.local
```

Run

Start the local Postgres (port 5440) and apply the migrations.
Terminal window
```
docker compose up -d db
pnpm db:migrate
```
Build the session image once. The script prints the BUDI_SESSION_IMAGE value for apps/api/.env.local.
Terminal window
```
pnpm --filter @budi/api image:build
```
Start the api, then the web app in a second terminal.
Terminal window
```
pnpm --filter @budi/api dev
pnpm --filter @budi/web dev
```
Open http://localhost:5173 and sign in.

The api listens on PORT (3100 by default). Every local server has a fixed port and two fallbacks for when another session holds it; the table is “Local ports” in the repo’s AGENTS.md.

To work on the other surfaces:

pnpm --filter @budi/landing dev   # http://localhost:4321
pnpm --filter @budi/docs dev      # http://localhost:4331

Test

pnpm typecheck
pnpm test
pnpm --filter @budi/web smoke

The api tests need the local Postgres (or TEST_DATABASE_URL). The smoke test signs in with the Privy test account set in apps/web/.env.local.