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 — Technical & Architecture Guide

Helix is a multi-agent AI workspace organized around a Bench-themed Next.js web application, background run workers, isolated Daytona sandboxes, a PostgreSQL/Supabase data and authentication layer, and a self-hosted Posta transactional mail stack.


1. Repository & Code Architecture

LayerDirectoryResponsibility
App Router & APIsrc/app/Next.js App Router pages for marketing (src/app/(marketing)/), authenticated Helix workspace (src/app/(v2)/helix/), legacy dashboard compatibility (src/app/dashboard/), status views (src/app/status/), embeds (src/app/embed/), and HTTP handlers (src/app/api/).
Request Proxysrc/proxy.tsSession cookie relay, route protection, and host-scoped request forwarding.
Client Workspace UIfrontend/helix/Bench UI kit (ui2/kit.tsx, ui2/bench-kit.tsx, ui2/bench-board.tsx), interactive AgentFace avatar system (ui2/agent-face.tsx), colleague collaboration regions (ui2/colleague-features.tsx), staff platform controls (ui2/staff-platform-panel.tsx), and streaming hooks.
Marketing & Docs UImarketing/Public landing components (marketing/components/marketing/), marketing AgentFace (marketing/components/marketing/agent-face.tsx), MDX documentation loader, and changelog data.
Backend Domain Layerbackend/Auth & Supabase SSR helpers (backend/lib/supabase/), transactional mailer (backend/lib/mailer.ts), Paystack billing, status probes (backend/lib/status/), channel adapters (backend/helix/channels.ts), and webhook verification.
Agent Engine & Runtimeagent/Mission execution loop (agent/core/run-loop.ts), crew catalog (agent/core/crew-shared.ts), colleague collaboration persistence & runtime (agent/core/colleague-runtime.ts), presence & mood logic (agent/core/agent-presence.ts), Daytona integration (agent/daytona/), standalone agent server (agent/engine/agent/server.ts), and background worker (agent/worker-main.ts).
Shared Utilitiesshared/Cross-boundary primitives: branding (shared/brand.ts), structured logging (shared/log.ts), API errors (shared/errors.ts), secret scrubbing (shared/secret-scrub.ts), pricing, and rate limits.
Database Migrationssupabase/migrations/PostgreSQL schemas, RLS policies, signup triggers, and colleague collaboration tables (public.helix_* and helix_v2.*).
Archivearchive/Retired legacy implementation files (archive/legacy/) and archived deployment artifacts (archive/cloud-deployment/). The live application does not import from archive/.

2. Runtime Processes

  1. Web Application (next start / standalone server.js)

    • Serves the marketing site, /helix/* workspace routes, authentication callbacks, OpenGraph generators (src/app/opengraph-image.tsx), and /api/* endpoints.
    • Connects to Supabase Auth/PostgREST/Storage and self-hosted Posta.
  2. Background Worker (npm run worker / npm run v2-worker)

    • Runs agent/worker-main.ts to claim queued tasks with PostgreSQL leases and execute runs against HELIX_V2_BASE_URL.
  3. Standalone Agent Server (npm run agent-server)

    • Runs agent/engine/agent/server.ts for dedicated HTTP/WebSocket agent orchestration when enabled.
  4. Status Server (npm run status-server)

    • Runs backend/lib/status/status-server.ts as an independent process so platform status remains available even if the primary web process restarts.

3. Data & Authentication Model

Authentication & Cookie Isolation

  • Browser and SSR clients (src/utils/supabase/client.ts, src/utils/supabase/server.ts) use @supabase/ssr with shared auth cookie logic in backend/lib/supabase/cookies.ts.
  • getSharedCookieDomain() scopes cookies dynamically to .launchverse.app in production domains while staying host-scoped (localhost / 127.0.0.1) during local testing so next start or next dev cookie jars never fail cross-domain checks.
  • Signup triggers (handle_new_user_signup()) are conflict-safe (ON CONFLICT DO NOTHING / membership-guarded) so re-created or migrated users keep their existing team workspace rather than receiving a shadow empty team.

Core Schemas (public and helix_v2)

  • Workspace & Runs: teams, team_members, public.helix_threads, public.helix_runs, public.helix_missions, public.helix_approvals, public.helix_artifacts, and helix_v2.* equivalents.
  • Colleague Collaboration Tables (supabase/migrations/20261117190000_helix_colleague_features.sql):
    • public.helix_out_of_office_windows — Out-of-Office delegation windows, covered/parked items, and compiled Return Briefings.
    • public.helix_colleague_desks — Open Door live supervision state (colleague | shoulder_tap_paused | human_takeover), cursor location labels, and paused checkpoints.
    • public.helix_concern_cards — Principled Disagreement (Stop & Push Back) concern records, alternatives, reversibility risks, shadow predictions, and human resolutions (proceed_as_asked | use_suggestion).
    • public.helix_teach_playbooks — Teach-by-Showing captured UI/browser step traces with parameter extraction and automatic secret scrubbing (masked_fields_count).
    • public.helix_source_consents — Per-user explicit consent flags (inbox, calendar, chat, files), WhatsApp compliance state (whatsapp_enabled, meta_ai_terms_verified), and dismissed hire suggestions.
    • public.helix_mobile_approvals_queue — Idempotent mobile biometric approval queue decisions synced across channels.
  • Security: All six helix_* collaboration tables have Row Level Security (RLS) enabled with access revoked from anon and authenticated, restricting read/write access to server-side service_role calls guarded by authedOrg().

4. Transactional Mail & Notifications

Outbound transactional mail and alerts are handled by backend/lib/mailer.ts with reply-to threading and opt-out enforcement. Internal self-hosted Posta SMTP/Postfix MTA topology and DNS setup are documented in the internal operations runbook: docs/operations/self-hosting-and-mail.md.


5. UI Design System, AgentFace & Link Previews

Expressive AgentFace Avatar System

Implemented in frontend/helix/ui2/agent-face.tsx, marketing/components/marketing/agent-face.tsx, and src/app/(v2)/helix/design.css:

  • Supports 12 distinct states across both doing and emotional axes: idle, working, waiting, done, error, observing, happy, angry, excited, sad, bored, sleeping.
  • Two-axis Eye Hierarchy: .hx-face-lid owns involuntary blinking (scaleY), while .hx-face-pupil wraps both the dark pupil circle and .hx-face-glint catchlight to drive state-specific eye tracking (hx-face-glance, hx-face-track, hx-face-peek, hx-face-scan, hx-face-happy, hx-face-glare, hx-face-drift, hx-face-dream) or pointer tracking (data-gaze).
  • Performance & Accessibility Guarantees:
    • Every @keyframes hx-face-* animates only GPU compositor properties (transform and opacity).
    • @media (prefers-reduced-motion: reduce) stops all animations explicitly (animation: none !important).
    • Tested against source-level invariants in tests/v2/agent-face-states.test.ts, tests/v2/agent-faces-and-workspace-image.test.ts, and tests/v2/class-coverage.test.ts.

Social / OpenGraph Preview Pipeline

  • shared/brand.ts defines canonical BRAND.tagline, BRAND.description, BRAND.ogImage, and BRAND.ogImageAlt.
  • scripts/marketing/build-og.mjs renders public/og.png (1200x630) and public/og@2x.png (2400x1260) via Playwright using real Bench display/text fonts, crew avatar states, and framed workspace screenshot.
  • src/app/opengraph-image.tsx and src/app/twitter-image.tsx mirror the Bench theme dynamically for Next.js metadata image endpoints.
Edit this page on GitHub↗