The open-source growth platform — unify customer data, segment anyone, orchestrate journeys across every channel, and let AI do the heavy lifting. Self-host it, own your data, pay nothing per contact.
☀️ v2.0.0 — Helio for humans. v1 proved the engine; v2 makes it yours without a terminal career. Install on any machine with one command — the
helioCLI drives Docker for you, the app installs to your desktop or phone (PWA), and a setup wizard takes you from blank box to working organization in minutes. Every channel sends for real, per organization: bring your own SMTP/Postmark/Resend/Mailgun, Twilio SMS, WhatsApp — and your own AI key (OpenAI, Anthropic, Groq, NVIDIA NIM, or a local model server), every secret sealed in an encrypted vault and shown only masked. Admins get a control room: a filterable audit trail, reports, live system health, a validated Database Studio over your own tables, and scheduled backups with one-command restore. The CRM closes the loop — contact & deal pages, companies, notes, a draggable board, sales reports — and the migration wizard pulls contacts straight from the HubSpot, Mailchimp, or Klaviyo APIs. If your data team trains its own churn model, upload it (ONNX or XGBoost; pickle refused by design) or point Helio at your model server, with automatic fallback if it ever fails. Security got the deep pass: TOTP 2FA with any authenticator app, org-enforced 2FA and password-rotation policies, scoped API keys, strict headers and rate limits everywhere. And billing is gone for good — Helio is free forever: no plans, no contact caps, no metering. The roadmap tells the story.
▶ Watch the demo film (MP4) · 📘 Read the product guide (PDF)
The journey canvas and the AI copilot, captured from a live instance. The film and the guide regenerate from the real product via task demo:video and task product:guide.
Marketing automation today forces a bad choice:
- HubSpot, Customer.io, Klaviyo — polished, but closed, expensive, and per-contact priced. Real automation sits behind ~$890+/mo tiers, and your customer data lives in someone else's cloud.
- Mautic — powerful but heavy (PHP/Symfony, 4–8 GB RAM) with slowing community velocity.
- Listmonk — delightfully fast, but newsletters only. No journeys, no automation.
Helio takes the best of each: Listmonk's performance, Mautic's automation depth, HubSpot's polish — open-source, self-hostable, data-sovereign, and AI-native from the first commit, not as a bolt-on.
Legend: ✅ shipped · 🚧 in progress · 🗺️ roadmap
- ✅ Multi-tenant platform core — organizations & workspaces with Postgres row-level security (cross-tenant access is impossible at the database, not just filtered), role-based access (owner/admin/editor/viewer), email-verified auth with 2FA support, invitations, audit log, REST gateway with per-organization API keys, OpenAPI 3.1 + problem+json + idempotency + rate limiting
- ✅ Contacts & lists — profiles with free-form attributes, tolerant CSV import with validation summary, static lists, cursor-paginated search
- ✅ Event pipeline — zero-dependency browser SDK (
@helio/sdk-js) → write-key-authenticated ingestion → Redpanda → ClickHouse; at-least-once with engine-level dedup. Segment/RudderStack-compatible HTTP Tracking API (/v1/batch+/v1/track|identify|page, write key via Basic auth), so existing instrumentation points straight at Helio - ✅ Segmentation — visual nested AND/OR builder over fields, JSON attributes, status, and recency; always-live membership (segments are predicates, not sync jobs); NULL semantics verified against real Postgres
- ✅ Email — block-based template builder with a visual block palette, server-rendered live preview, image uploads from your device (stored in Helio, served from your instance) with width/alignment/rounding controls,
{{token|fallback}}personalization, open-pixel + HMAC-signed click tracking, one-click unsubscribe (RFC 8058) + hosted preference page - ✅ Real sending, per organization — connect your own SMTP relay or a native Postmark/Resend/Mailgun adapter (SES/Gmail/Brevo via their SMTP endpoints) with your own From identity; one-click verify and a live test send; Twilio SMS and WhatsApp Cloud credentials work the same way, with delivery-failure alerts in-app
- ✅ Campaigns — template + segment/list audiences delivered durably on Temporal: per-recipient send rows make retries double-send-proof; suppression honored at enumeration and per send
- ✅ Journeys — React Flow canvas → validated DAG → one Temporal workflow per enrolled contact: event triggers from the live stream, durable waits (survives
kill -9with the timer expired), live-data branches; every send node (email, SMS, WhatsApp, web push, in-app) claims a deterministic delivery row, so a worker retry never double-sends - ✅ Customizable dashboard — every member arranges their own overview: show/hide and reorder widgets drawn from across the product (KPIs, activity timeline, sales pipeline, recent campaigns, audience, channels, tasks, quick links); the layout persists per member
- ✅ Analytics — overview dashboard with engagement timeline and per-campaign opens/clicks from ClickHouse, degrading gracefully when the analytics stack is offline
- ✅ Insights — an event-stream funnel (ordered steps, conversion + drop-off via ClickHouse
windowFunnel), a weekly cohort-retention grid, multi-touch attribution (first/last/linear credit to the campaigns that touched each converter), and a fenced read-only SQL explorer (single SELECT, events-table-only, auto-scoped to the workspace, row/time-capped) — with the shaping and SQL-guard logic unit-tested in@helio/core - ✅ Hosted forms — public signup pages that upsert contacts, idempotently and suppression-safely
- ✅ Multi-channel — web push, SMS (Twilio), WhatsApp (Cloud API), and in-app messages as journey send nodes alongside email, personalized with the same
{{token}}tokens - ✅ Deliverability — a wizard that generates a DKIM key pair per sending domain, shows the SPF/DKIM/DMARC records to publish, and verifies them by live DNS lookup; the DKIM private key is tenant-isolated
- ✅ Landing pages — a block-based builder with a sticky live preview (heading, text, image, button, email-capture form; keyboard-reorderable) that publishes a white-labeled hosted page at
/p/<id>and captures signups into the CDP - ✅ On-site widgets — banners and popups composed against a live preview and shown on your own site via a one-line, zero-dependency embed (
/widget.js) that pulls live widgets from a write-key-scoped, CORS-enabled endpoint - ✅ In-app messages — per-contact messages queued by a journey's Send in-app step and drained by the tracking SDK (
helio.inApp()), resolved by the visitor's identity and scoped to the write key's workspace - ✅ AI copilot — describe a segment, journey, or on-brand email in a sentence and get a working draft; predictive lead scoring & churn (with per-workspace conversion events); send-time optimization; autonomous A/B winner selection — all grounded in your own org's data
- ✅ Bring your own AI — each organization picks its provider (OpenAI, Anthropic, Groq, NVIDIA NIM, Ollama, or any OpenAI-compatible local server) and pastes its own key in Settings; keys are sealed with AES-256-GCM, shown only masked, and never logged
- ✅ Bring your own churn model — upload an ONNX or XGBoost model (pickle refused by design) or connect your own model server; the feature mapping is automatic (train on the one-click CSV and it plugs straight in); validated in a locked-down sandbox, one click to activate, automatic fallback to the built-in model if yours ever fails — plus a one-click training-data CSV
- ✅ Agent-ready — an MCP server exposes Helio's capabilities as tools, so external AI agents can drive campaigns programmatically
- ✅ CRM-lite — pipelines with configurable stages and a deal board, a task list (calls, emails, meetings, to-dos) grouped by due date, and a meeting scheduler with public booking pages (timezone-correct slots, server-validated, double-book-proof) that file meetings into the CRM; all tenant-isolated
- ✅ Migration & ingestion — one-click importers that detect HubSpot/Mailchimp/Klaviyo exports (mapping who's unsubscribed), and a Segment/RudderStack-compatible HTTP Tracking API so existing instrumentation points straight at Helio
- ✅ One-minute first run — a fresh install opens on a setup screen (admin, organization, workspace — done); instances are invite-only after that, and Helio installs as its own desktop/mobile app (PWA) with a getting-started checklist on the dashboard
- ✅ Free forever — no plans, no contact caps, no metering, no payment integrations; every Helio deployment is unlimited
- ✅ Credential vault — every third-party secret (email/SMS/WhatsApp/AI keys, signing secrets, DKIM keys) is encrypted at rest with a deployment key, bound to its row so ciphertext can't be replayed elsewhere, with zero-downtime key rotation
- ✅ Enterprise SSO & SCIM — per-organization OIDC single sign-on (domain-routed, server-authoritative org binding) and SCIM 2.0 user provisioning; IdP client secrets and SCIM tokens are walled off from the tenant database role
- ✅ SDKs & docs — typed REST SDKs for JavaScript/TypeScript and Python, generated from the OpenAPI spec, plus a full documentation site (Fumadocs)
- ✅ Outbound webhooks — subscribe endpoints to lifecycle events (contacts, deals, tasks); each delivery is HMAC-signed with the endpoint's own secret over a timestamped scheme and sent on a durable, retrying workflow, with a one-click test ping
- ✅ White-labeling — per-organization display name, accent color, and logo applied across the dashboard shell and hosted pages; the accent drives the primary token with an auto-picked legible foreground, validated hex-only so it can't inject markup
- ✅ Per-element color palettes — every published surface (hosted forms, landing pages, in-app messages, on-site widgets) sets its own background, text, button, and accent colors; new surfaces are seeded from your brand color and each value is re-validated hex-only on the server before it reaches a hosted page, the SDK, or the zero-dependency widget embed
- ✅ Bug reports → GitHub — a report-a-bug / feedback widget in every page header (captures the current route, reporter, and version) files straight to a GitHub repo: with an admin-configured PAT it creates the issue server-side; otherwise it opens a prefilled new-issue page. The target repo (and sealed token) are an admin setting under Settings → Maintenance
- ✅ Onboarding tour — a dependency-free product tour that greets new operators and points them at contacts, journeys, the AI copilot, and the CRM; shown once, dismissible
- ✅ Shopify — connect a store and stream
customers/create|updateandorders/createinto the CDP; every webhook is HMAC-verified, the shop domain resolves the org, and buyers gainshopify_*traits you can segment on - ✅ Salesforce — connect an org and new Helio contacts push to Salesforce as Leads via the REST API; best-effort so a Salesforce hiccup never blocks the contact write
- 🗺️ Platform integrations — ad-audience sync
 |
 |
 |
 |
flowchart TB
subgraph Client
SDK[Tracking SDK - JS/TS]
DASH[Next.js Dashboard]
end
subgraph EdgeAPI[Edge / API]
BFF[tRPC BFF]
GW[REST/OpenAPI Gateway + Webhooks]
ING[Event Ingestion]
end
subgraph Orchestration
TMP[(Temporal)]
JW[Journey Workers]
end
subgraph Intelligence[Intelligence - Python/FastAPI]
AI[Copilot + Content Gen]
SCORE[Predictive Scoring]
SEG[Segment Compute]
MCP[MCP Server]
end
subgraph Delivery
EMAIL[Email Adapters]
SMS[SMS / Push / WhatsApp]
TRACK[Open/Click Tracking]
end
subgraph Data
PG[(PostgreSQL 16 + pgvector)]
CH[(ClickHouse)]
REDIS[(Redis)]
OBJ[(S3 / MinIO)]
BUS[(Redpanda)]
end
DASH --> BFF --> GW
SDK --> ING --> BUS
BUS --> CH
BUS --> JW
GW --> PG
JW <--> TMP
JW --> EMAIL & SMS
JW --> AI & SCORE & SEG
EMAIL --> TRACK --> BUS
AI & SCORE & SEG --> PG & CH
MCP --> GW
GW --> REDIS
TypeScript owns the product surface (dashboard, APIs, journey workers on Temporal for durable execution); Python owns the intelligence plane (scoring, content generation, segment compute, MCP). PostgreSQL holds transactional state with row-level security per tenant; ClickHouse holds the event firehose for analytics; Redpanda is the backbone between them.
One-time prerequisite: Docker — a normal, free app install (Desktop on Windows/macOS, Engine on servers). On Windows the installer below even offers to set it up for you. Helio handles absolutely everything else.
Linux / macOS / servers & VMs
curl -fsSL https://github.com/achref-soua/helio/releases/latest/download/install.sh | shWindows (PowerShell)
irm https://github.com/achref-soua/helio/releases/latest/download/install.ps1 | iexThe installer is a plain script — nothing for antivirus or SmartScreen to flag — that checks Docker (and offers to set it up on Windows/Linux), generates this installation's secrets, verifies the release bundle's checksum, pulls release-pinned images, runs migrations, starts the stack, and opens the dashboard; create the first account there and it becomes the administrator. It also saves itself as ~/.helio/helio, so day 2 is just as boring: run it with no argument for an interactive menu, or pass a command — helio status, helio logs, helio update (which takes a safety backup first), helio stop. Leaving is one command too: helio uninstall stops and removes the stack but keeps your data; helio uninstall --purge-data erases everything (both ask you to type uninstall first).
Everything lives under ~/.helio (compose file, .env with your secrets, backups). The install runs the full stack by default (~8 GB RAM) — dashboard, REST API, AI copilot, campaign sending, event ingestion, tracking, analytics, and journeys all work out of the box. On a small host, pass --core (-Core on Windows) for the minimal ~2.5 GB profile (dashboard, REST API, and AI service only). Mail goes to the bundled Mailpit test inbox until an organization connects its real provider under Settings → Provider credentials — so you can explore without sending anyone anything.
Docker is where most install problems happen, so the installer (and helio doctor) diagnoses the common ones and fixes the safe cases automatically — Linux socket permissions and a stopped daemon, and on Windows a missing WSL2 backend (it offers to run wsl --install) or CPU virtualization disabled in the BIOS. If an install stalls, run helio doctor: it names exactly what's wrong and the command to fix it. See self-hosting.mdx for the full list.
git clone https://github.com/achref-soua/helio.git
cd helio
cp .env.example .env # set BETTER_AUTH_SECRET (openssl rand -hex 32) + HELIO_ENCRYPTION_KEY (openssl rand -base64 32)
task setup # install dependencies + git hooks
task up # full stack: Postgres (+pgvector), Redis, Mailpit, ClickHouse, Redpanda, Temporal, MinIO
task db:migrate && task db:seed
pnpm --filter @helio/web devOpen http://localhost:3000, sign up, and verify your email at Mailpit (http://localhost:8025) — onboarding creates your organization, and the seed provisions a ready-to-explore demo workspace: contacts (with lead scores and AI predictions), lists, segments, email templates, a campaign, an active welcome journey, lead-scoring rules, a CRM pipeline with deals and tasks, and a demo write key. Dev email never leaves your machine.
task up already runs the campaign/journey/analytics infrastructure. For hot-reload on those services, run them from source too:
pnpm --filter @helio/ingest dev # event ingestion :4100
pnpm --filter @helio/tracking dev # open/click tracking :4200
pnpm --filter @helio/workers dev # Temporal worker (sends + journeys)Create a template under Emails, a campaign under Campaigns, hit Send — mail lands in Mailpit with live tracking links, and opens/clicks stream into the dashboard. Fire curl -X POST localhost:4100/v1/batch -H 'x-write-key: wk_demo_0000000000000000000000000' -H 'content-type: application/json' -d '{"batch":[{"type":"track","event":"Signed Up","userId":"ada@example.com"}]}' to enroll a contact into an active journey.
| Command | What it does |
|---|---|
task up / task up:core / task up:observability |
full stack (everything) / minimal infra only / + Prometheus, Grafana, OTel collector |
task db:migrate · db:seed · db:studio · db:reset |
schema & data lifecycle |
task lint · typecheck · test · format · build |
the quality pipeline (same as CI) |
pnpm --filter @helio/web dev / @helio/api dev |
dashboard :3000 / gateway :4000 |
pnpm --filter @helio/ingest dev / @helio/tracking dev / @helio/workers dev |
ingestion :4100 / tracking :4200 / Temporal worker |
task ch:migrate |
apply ClickHouse migrations standalone (the ingest service also applies them at boot) |
cd apps/intelligence && uv run uvicorn helio_intelligence.app:app --reload |
intelligence :8000 |
cd apps/web && pnpm test:e2e |
Playwright suite incl. the full signup→invite→accept journey |
task screenshots |
regenerate docs/assets from a running app |
Details: local-dev runbook.
Every environment variable any service reads is documented in .env.example, added in the same PR as the feature that reads it. Required variables fail fast at startup.
Multi-stage, non-root, healthchecked images for every service live in infra/docker/ and publish to GHCR on every main push (Trivy-gated, SBOM attached):
for service in web api ingest tracking workers intelligence; do
docker build -f "infra/docker/$service.Dockerfile" -t "helio-$service" .
doneCompose profiles cover local/self-host topologies. For the fastest hosted start, paste infra/cloud/helio-cloud-init.yaml into a new Linux VM's user-data on any provider (DigitalOcean, Hetzner, EC2, …) — it installs Docker and Helio on first boot and serves the dashboard at http://<server-ip>:3000, no SSH needed. For Kubernetes, a Helm chart lives in infra/helm/helio — helm install helio ./infra/helm/helio brings up all six services with health probes, optional Ingress and autoscaling, and (for evaluation) bundled Postgres + Redis; point it at managed datastores for production. The managed-cloud walkthrough lives in apps/docs/content/docs/production.mdx.
Measured on the development reference (WSL2, core profile, production build, v2.0 tree): warm server-rendered responses for the dashboard's key routes land at 24–44 ms (/contacts 24 ms, /deals 28 ms, /admin/audit 30 ms, /settings 36 ms; first-hit ≤ 530 ms including route compilation warm-up). The journey canvas (React Flow) is code-split and loads only when an editor opens. Journey sends run on Temporal with explicit retry policies (5 attempts on sends, 3 on short activities) and raise in-app system alerts on exhaustion.
Hot-path ingestion is load-tested with the committed k6 harness in infra/k6/ (task loadtest). Measured 2026-06-28 against the full stack on the development reference (WSL2, 20 vCPU, 15 GiB, all services co-located on one host — production separates them and runs multiple ingest replicas, so these understate it):
| Offered rate | Sustained events/s | Accept | p95 latency | Errors |
|---|---|---|---|---|
| 6 000/s | 6 063 | 100 % | 5.4 ms | 0 % |
| 15 000/s | 15 435 | 100 % | 23 ms | 0 % |
| 20 000/s | 20 259 | 100 % | 81 ms | 0 % |
Sustains ~20 000 events/s at p95 81 ms — 4× the ≥ 5 000 events/s budget, within the < 150 ms target; a single ingest process saturates at ~23.5k events/s. End to end, 3.0 M events drained through Redpanda into ClickHouse with the consumer group at zero lag. The per-workspace rate limit (INGEST_RATE_LIMIT_MAX, default 600/60 s) correctly sheds excess with 429 + Retry-After; raise it to measure raw capacity. Full method and the API-read budget (not yet load-tested) are in docs/production-readiness/v2.2.3.md and infra/k6/README.md.
For horizontal scale, the RLS app connection can be fronted by an opt-in transaction-mode PgBouncer — safe by design, since Helio sets the tenant id transaction-locally (ADR-0022) — and ingestion resolves write keys through a shared Redis cache (ADR-0023).
Multi-tenant isolation is enforced at the database: PostgreSQL row-level security under a non-superuser role, with the tenant id set transaction-locally so it never leaks across requests or a connection pool. On top of that — SSRF guards on every server-side fetch of an operator-supplied URL, a shared-token boundary in front of the AI plane, hashed scoped API keys, an AES-256-GCM credential vault, TOTP 2FA and SSO/SCIM, and an opt-in Kubernetes NetworkPolicy.
The v2.0.9 security audit documents the latest hardening pass — findings, fixes, and verification. See SECURITY.md for the policy and the full surface table, and the threat model.
| Milestone | Focus |
|---|---|
| v0.1 | Foundation: monorepo, CI/CD, multi-tenant auth & RBAC, design system, observability baseline |
| v0.2 | Usable MVP: contacts & lists, event ingestion, segmentation, email sending & tracking, first journeys |
| v0.3 | Growth: full journey canvas, SMS & push, landing pages, lead scoring, A/B testing, attribution |
| v0.4 | AI: copilot, NL→segment, NL→journey, brand-voice generation, MCP server |
| v0.5 | AI, cont'd: predictive scoring & churn, send-time optimization, autonomous A/B winner selection |
| v0.6 | Platform: HubSpot/Mailchimp/Klaviyo importers, Segment-compatible ingestion, CRM-lite deal board |
| v0.7 | Platform: opt-in Stripe billing with plan-gated usage limits and a signature-verified webhook |
| v0.8 | Platform: enterprise SSO & SCIM, generated REST SDKs (JS + Python), documentation site, richer demo seed |
| v0.9 | Platform: Kubernetes Helm chart, and production & managed-cloud deployment guides |
| v0.10 | Platform: CRM tasks & meeting scheduler, outbound webhooks, white-labeling, Shopify & Salesforce |
| v1.0 | Launch: published load-test numbers (run the shipped k6 harness on reference hardware) and a hosted public demo (stand it up with the shipped Helm/Compose), then tag v1.0.0 |
| v2.0 | Helio for humans: one-command install (helio CLI + PWA) with a setup wizard, per-org real sending (SMTP/Postmark/Resend/Mailgun, Twilio, WhatsApp) and BYO AI key behind an encrypted credential vault, admin control room (audit, reports, system health, Database Studio, backups & restore), complete CRM (contact/deal pages, companies, board, sales reports), API-driven migration wizard, BYO churn model (ONNX/XGBoost/HTTPS), the security deep pass (org 2FA & password-rotation policies, scoped API keys), mobile/responsive overhaul — and billing removed: free forever |
- 📘 Product guide (PDF) — the whole story in 25 pages: why Helio, a screenshot tour, installation and org setup, connecting every channel (SMTP, AI, SMS, WhatsApp, webhooks, widgets), migrating from HubSpot/Mailchimp/Klaviyo, the CRM, the admin control room, the usage guide, and how to contribute. Written for technical and non-technical readers alike.
- 🧭 Setup guide (PDF) — a plain-language walkthrough for operators: install Helio, complete first-run setup, and understand every settings panel. No technical background needed.
- 📖 Documentation site (Fumadocs) — concepts, self-hosting, configuration, every feature guide, the REST API, SDKs, the MCP server, and migration guides. Run it locally with
task docs(→localhost:3002). - Architecture (C4) & trust boundaries · Decision log (ADRs) · Threat model
- Local-dev runbook · SSO & SCIM setup · REST API guide · API spec (OpenAPI 3.1)
- CONTRIBUTING.md — dev setup, branching model, commit conventions, PR rules
- SECURITY.md — how to report vulnerabilities (privately, please)
- SUPPORT.md — where to ask questions and get help · Discussions · Wiki
- CODE_OF_CONDUCT.md — the community standard we hold each other to
- CHANGELOG.md — notable changes, release by release
- Privacy Policy — the project collects nothing; here is exactly what that means
- Terms of Use — AGPL-3.0 is the contract; plain-words expectations around it
- Data & Compliance — where deployment data lives, the GDPR/email tooling, and the operator checklist
- Marketing kit — launch article, social post, and a discoverability checklist
AGPL-3.0 — free to self-host, modify, and redistribute; network-service modifications must stay open.