Local setup
Run the API, the worker and the web app on your machine.
On this page
The applications run on your machine. Postgres, Redis and object storage run remotely on the development VPS (Dokploy), decided 2026-09-17.
| Process | Where | Port |
|---|---|---|
API (ikazebot-server) | localhost | 5000 |
Worker (ikazebot-server) | localhost | none |
Web (ikazebot-web) | localhost | 3000 |
| Postgres 18 + pgvector, Redis, MinIO | Dokploy on the VPS | 5432, 6379, 9000 |
Prerequisites
- Node.js 24 (
.nvmrcpins it) and pnpm 10 (packageManagerpins it;corepack enableprovides it). - Access to the development database, Redis and storage. Ask the maintainer for credentials.
- An OpenRouter API key. Development can use
:freemodels. - A Resend key. Local runs send real email; see Mail.
1. The server
cd ikazebot-server
pnpm install
cp .env.example .env # then fill it in — every variable is commented
The important variables:
| Variable | Value in development |
|---|---|
DATABASE_URL | The ikazebot_app role, never the superuser. The API refuses to boot as a role that bypasses row-level security. |
AUTH_SECRET | openssl rand -base64 48 |
AUTH_BASE_URL / WEB_BASE_URL | http://localhost:5000 / http://localhost:3000 |
CORS_ORIGINS | http://localhost:3000 |
REDIS_URL | The VPS Redis |
STORAGE_* | The MinIO bucket (README → "Development: MinIO on the VPS") |
OPENROUTER_API_KEY, EMBEDDING_MODEL | Your key; a :free embedding model is fine for test data |
WIDGET_RELAY_SECRET | openssl rand -hex 32, the same value in web |
SECRETS_ENCRYPTION_KEY | openssl rand -hex 32 (encrypts action and channel secrets) |
Boot validates the whole environment and lists every problem at once, so one restart shows everything that is wrong.
Run the API and the worker, in two terminals:
pnpm start:dev # the API on :5000
pnpm start:worker:dev # the worker — without it, sources stay "Queued" forever
Check: curl http://localhost:5000/health/ready should return ok for the database, storage and queue.
2. The web app
cd ikazebot-web
pnpm install
cp .env.example .env.local
| Variable | Value |
|---|---|
API_BASE_URL | http://localhost:5000 (server-side only) |
NEXT_PUBLIC_API_URL | http://localhost:5000 (browser auth client only) |
WIDGET_RELAY_SECRET | The same value as the server's |
pnpm dev # http://localhost:3000
3. First run
- 1Sign up at localhost:3000
- 2Verify your email
- 3Create a workspace
- 4Become platform adminpnpm admin:grant
- 5Enable models/admin/models
- 6Create an agent
A fresh model catalog enables only a small starter set. To pick others, make yourself a platform admin (see Platform administration) and enable models at /admin/models.
Mail in development
Mail goes through Resend in every environment; there is no fake local transport. Before a sending domain is verified, set MAIL_FROM=onboarding@resend.dev. Resend then delivers only to the address that owns the Resend account, so sign up and invite with that address. Production refuses this sender at boot.
Migrations
Schema changes run from your machine as the database superuser, from a separate .env.migrate. See Migrations. The superuser URL never goes in .env.
Before you commit
pnpm typecheck && pnpm lint && pnpm test
All three must pass, in every repository you touched. See Working conventions.