Helix — Developer & Operations Guide
This guide covers installing dependencies, configuring environment variables, running Helix against real or local backing services, applying database migrations, running test suites, and preparing a release.
1. Prerequisites
- Node.js: 22.x LTS (
node -v) - npm: 10+
- Playwright Chromium (for OpenGraph image generation and browser E2E checks):
npx playwright install chromium - PostgreSQL / Supabase instance (local Supabase CLI, staging server, or SSH tunnel to staging Postgres/Kong/Posta)
Install dependencies:
npm install --legacy-peer-deps
2. Environment Configuration
Copy .env.example to .env.local (never commit .env* files containing credentials). Key groups required at runtime:
Supabase & Auth
| Variable | Scope | Purpose |
|---|---|---|
NEXT_PUBLIC_SUPABASE_URL | Client & Server | Public Supabase / Kong base URL |
NEXT_PUBLIC_SUPABASE_ANON_KEY | Client & Server | Public anon key for browser session client |
SUPABASE_SERVICE_ROLE_KEY | Server only | Admin PostgREST/Auth client (BYPASSRLS, validated after authedOrg()) |
SUPABASE_JWT_SECRET | Server only | Fast local JWT verification inside SSR server helpers |
NEXT_PUBLIC_SITE_URL | Client & Server | Canonical origin (e.g. https://launchverse.app or http://localhost:3200) |
NEXT_PUBLIC_AUTH_COOKIE_DOMAIN | Client & Server | Optional override (localhost for local testing) |
HELIX_INTERNAL_SECRET | Server only | HMAC-SHA256 signing secret for internal worker calls |
Transactional Mail Configuration (Summary)
Outbound transactional mail uses MAIL_PROVIDER, MAIL_FROM, MAIL_REPLY_TO, POSTA_API_URL, POSTA_API_KEY, POSTA_WEBHOOK_SECRET, and SMTP relay fallback (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS). See docs/operations/self-hosting-and-mail.md for server setup and Posta verification steps.
Agent Engine & Sandboxes
| Variable | Scope | Purpose |
|---|---|---|
HELIX_V2_BASE_URL | Server/Worker | Loopback URL used by v2-worker to invoke Next APIs |
HELIX_SANDBOX_BACKEND | Server/Agent | Sandbox runtime provider (daytona) |
DAYTONA_API_URL, DAYTONA_API_KEY, DAYTONA_TARGET | Server/Agent | Daytona workspace provisioning credentials |
GROQ_API_KEY, BAI_API_KEY, NIM_API_KEY, EXA_API_KEY | Server/Agent | LLM inference & web search provider keys |
Important build note: Do not set
HELIX_API_URLduringnext buildwhen serving API routes from the same Next.js server (next.config.tscompiles/api/*rewrites whenHELIX_API_URLorNEXT_PUBLIC_API_URLis non-empty at build time).
3. Running Locally
Development Mode
npm run dev
Standalone Production Mode (Matches Container Runtime)
npm run build
cp -a public .next/standalone/public
cp -a .next/static .next/standalone/.next/static
PORT=3200 HOSTNAME=127.0.0.1 node .next/standalone/server.js
Optional Supporting Processes
# Background task worker
npm run worker
# Standalone HTTP/WebSocket agent server
npm run agent-server
# Independent status page server
npm run status-server
4. Database Migrations
Migrations live in supabase/migrations/ and are idempotent (IF NOT EXISTS, ON CONFLICT DO NOTHING):
- Recent colleague features migration:
supabase/migrations/20261117190000_helix_colleague_features.sqlCreates:public.helix_out_of_office_windowspublic.helix_colleague_deskspublic.helix_concern_cardspublic.helix_teach_playbookspublic.helix_source_consentspublic.helix_mobile_approvals_queue
Apply against Postgres using psql:
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f supabase/migrations/20261117190000_helix_colleague_features.sql
5. Verification, Testing & Asset Pipelines
| Task | Command | Notes |
|---|---|---|
| Typecheck | npm run typecheck | Verifies full TypeScript strict check across all packages. |
| Lint | npm run lint | Runs ESLint across src, frontend, marketing, backend, agent, shared. Must exit with 0 errors. |
| Cookie domain safety | npm run check:cookie-domain | Ensures auth cookies never hardcode mismatched domains. |
| Unit tests | npx vitest run tests/unit --maxWorkers=4 | Keep --maxWorkers=4 on high-core hosts (e.g. 48 vCPUs) to bound memory usage. |
| Reliability tests | npx vitest run tests/helix-reliability --maxWorkers=4 | Execution loop, run ledger, failure recovery, and streaming tests. |
| UI/v2 contract tests | npx vitest run tests/v2 --maxWorkers=4 | Enforces Bench CSS rules, AgentFace motion invariants, SEO metadata, and class coverage. |
| Regenerate OG cards | node scripts/marketing/build-og.mjs && node scripts/marketing/build-status-og.mjs | Rebuilds public/og.png, public/og@2x.png, public/og-status.png, and public/og-status@2x.png. |
| Production build | npm run build | Compiles Turbopack server, client, and standalone bundles. |