Getting StartedDeveloper & Embed Guide
Helix Agent
Helix AdvisorHelix OperatorArchitecture & Technical GuideHelix ArchitectureHelix PhasesHelix SandboxHelix MCPHelix Security
MCP Providers
Security & Governance
Billing & Quotas
REST, Gateway & MCP API Reference
API Reference (Redoc)

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

VariableScopePurpose
NEXT_PUBLIC_SUPABASE_URLClient & ServerPublic Supabase / Kong base URL
NEXT_PUBLIC_SUPABASE_ANON_KEYClient & ServerPublic anon key for browser session client
SUPABASE_SERVICE_ROLE_KEYServer onlyAdmin PostgREST/Auth client (BYPASSRLS, validated after authedOrg())
SUPABASE_JWT_SECRETServer onlyFast local JWT verification inside SSR server helpers
NEXT_PUBLIC_SITE_URLClient & ServerCanonical origin (e.g. https://launchverse.app or http://localhost:3200)
NEXT_PUBLIC_AUTH_COOKIE_DOMAINClient & ServerOptional override (localhost for local testing)
HELIX_INTERNAL_SECRETServer onlyHMAC-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

VariableScopePurpose
HELIX_V2_BASE_URLServer/WorkerLoopback URL used by v2-worker to invoke Next APIs
HELIX_SANDBOX_BACKENDServer/AgentSandbox runtime provider (daytona)
DAYTONA_API_URL, DAYTONA_API_KEY, DAYTONA_TARGETServer/AgentDaytona workspace provisioning credentials
GROQ_API_KEY, BAI_API_KEY, NIM_API_KEY, EXA_API_KEYServer/AgentLLM inference & web search provider keys

Important build note: Do not set HELIX_API_URL during next build when serving API routes from the same Next.js server (next.config.ts compiles /api/* rewrites when HELIX_API_URL or NEXT_PUBLIC_API_URL is 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.sql Creates:
    • public.helix_out_of_office_windows
    • public.helix_colleague_desks
    • public.helix_concern_cards
    • public.helix_teach_playbooks
    • public.helix_source_consents
    • public.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

TaskCommandNotes
Typechecknpm run typecheckVerifies full TypeScript strict check across all packages.
Lintnpm run lintRuns ESLint across src, frontend, marketing, backend, agent, shared. Must exit with 0 errors.
Cookie domain safetynpm run check:cookie-domainEnsures auth cookies never hardcode mismatched domains.
Unit testsnpx vitest run tests/unit --maxWorkers=4Keep --maxWorkers=4 on high-core hosts (e.g. 48 vCPUs) to bound memory usage.
Reliability testsnpx vitest run tests/helix-reliability --maxWorkers=4Execution loop, run ledger, failure recovery, and streaming tests.
UI/v2 contract testsnpx vitest run tests/v2 --maxWorkers=4Enforces Bench CSS rules, AgentFace motion invariants, SEO metadata, and class coverage.
Regenerate OG cardsnode scripts/marketing/build-og.mjs && node scripts/marketing/build-status-og.mjsRebuilds public/og.png, public/og@2x.png, public/og-status.png, and public/og-status@2x.png.
Production buildnpm run buildCompiles Turbopack server, client, and standalone bundles.
Edit this page on GitHub↗