Skip to content

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.

ProcessWherePort
API (ikazebot-server)localhost5000
Worker (ikazebot-server)localhostnone
Web (ikazebot-web)localhost3000
Postgres 18 + pgvector, Redis, MinIODokploy on the VPS5432, 6379, 9000

Prerequisites

  • Node.js 24 (.nvmrc pins it) and pnpm 10 (packageManager pins it; corepack enable provides it).
  • Access to the development database, Redis and storage. Ask the maintainer for credentials.
  • An OpenRouter API key. Development can use :free models.
  • A Resend key. Local runs send real email; see Mail.

1. The server

bash
cd ikazebot-server
pnpm install
cp .env.example .env        # then fill it in — every variable is commented

The important variables:

VariableValue in development
DATABASE_URLThe ikazebot_app role, never the superuser. The API refuses to boot as a role that bypasses row-level security.
AUTH_SECRETopenssl rand -base64 48
AUTH_BASE_URL / WEB_BASE_URLhttp://localhost:5000 / http://localhost:3000
CORS_ORIGINShttp://localhost:3000
REDIS_URLThe VPS Redis
STORAGE_*The MinIO bucket (README → "Development: MinIO on the VPS")
OPENROUTER_API_KEY, EMBEDDING_MODELYour key; a :free embedding model is fine for test data
WIDGET_RELAY_SECRETopenssl rand -hex 32, the same value in web
SECRETS_ENCRYPTION_KEYopenssl 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:

bash
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

bash
cd ikazebot-web
pnpm install
cp .env.example .env.local
VariableValue
API_BASE_URLhttp://localhost:5000 (server-side only)
NEXT_PUBLIC_API_URLhttp://localhost:5000 (browser auth client only)
WIDGET_RELAY_SECRETThe same value as the server's
bash
pnpm dev                  # http://localhost:3000

3. First run

  1. 1Sign up at localhost:3000
  2. 2Verify your email
  3. 3Create a workspace
  4. 4Become platform adminpnpm admin:grant
  5. 5Enable models/admin/models
  6. 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

bash
pnpm typecheck && pnpm lint && pnpm test

All three must pass, in every repository you touched. See Working conventions.

Get started free — 50 credits a month