helio

KO | EN

gitlite — search

#kubernetes #android #api #self-hosted #php #web #llm #postgresql #tailwindcss #list

(★ 9)

The open-source growth platform — AI-native marketing automation: CDP, segmentation, cross-channel journeys, email, analytics. Self-hostable, data-sovereign.

파일 탐색기

ZIP 다운로드

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - visual-recap.sh
- - ci.yml
  - release.yml
  - visual-recap.yml
- CODEOWNERS
- FUNDING.yml
- PULL_REQUEST_TEMPLATE.md
- - eslint.config.mjs
  - openapi.json
  - package.json
  - tsconfig.json
  - vitest.config.ts
- - eslint.config.mjs
  - package.json
  - tsconfig.json
  - vitest.config.ts
- - eslint.config.mjs
  - next-env.d.ts
  - next.config.mjs
  - package.json
  - postcss.config.mjs
  - source.config.ts
  - tsconfig.json
- - eslint.config.mjs
  - package.json
  - tsconfig.json
  - vitest.config.ts
- - pyproject.toml
  - README.md
  - uv.lock
- - eslint.config.mjs
  - package.json
  - tsconfig.json
  - vitest.config.ts
- - eslint.config.mjs
  - instrumentation.ts
  - next-env.d.ts
  - next.config.ts
  - package.json
  - playwright.config.ts
  - postcss.config.mjs
  - tsconfig.json
- - eslint.config.mjs
  - package.json
  - tsconfig.json
  - vitest.config.ts
- - 0001-monorepo-turborepo-pnpm-uv.md
  - 0002-polyglot-ts-python.md
  - 0003-postgres-rls-tenancy.md
  - 0004-better-auth-kernel.md
  - 0005-temporal-orchestration.md
  - 0006-agpl-license.md
  - 0007-event-plane.md
  - 0008-hono-openapi-gateway.md
  - 0009-commit-and-release-flow.md
  - 0010-ingestion-pipeline.md
  - 0011-campaign-delivery.md
  - 0012-journey-execution.md
  - 0013-sso-oidc.md
  - 0014-scim-provisioning.md
  - 0015-gateway-api-keys.md
  - 0016-docs-site-fumadocs.md
  - 0017-webhook-tenant-resolution.md
  - 0018-install-distribution-and-cli.md
  - 0019-org-credential-vault.md
  - 0020-local-backup-architecture.md
  - 0021-byo-churn-model.md
  - 0022-pgbouncer-transaction-pooling.md
  - 0023-write-key-shared-cache.md
- - campaigns.png
  - contacts.png
  - dashboard.png
  - demo.gif
  - email-builder.png
  - journey-canvas.png
  - login.png
  - segment-builder.png
- - ai-copilot-flow.mmd
  - analytics-query.mmd
  - cdp-identity-resolution.mmd
  - churn-model.mmd
  - credential-vault.mmd
  - delivery-adapters.mmd
  - deployment-profiles.mmd
  - ingestion-pipeline.mmd
  - journey-execution.mmd
  - landing-forms.mmd
  - mcp-server.mmd
  - mermaid-config.json
  - puppeteer-config.json
  - render.sh
  - rls-tenant-isolation.mmd
  - scheduler-meeting.mmd
  - segmentation-compute.mmd
  - sso-scim.mmd
  - webhook-delivery.mmd
  - widget-embed.mmd
- - linkedin-post.md
  - medium-article.md
  - README.md
- - v2.2.3.md
- - local-dev.md
  - production-ops.md
  - wsl-memory.md
- - audit-2.0.9.md
  - audit-2.1.0.md
  - zap-baseline.html
  - zap-baseline.json
  - zap-baseline.md
- api.md
- architecture.md
- diagrams.md
- helio-product-guide.pdf
- helio-setup-guide.pdf
- sso.md
- threat-model.md
- - helio-cloud-init.yaml
  - helio-demo-cloud-init.yaml
- - docker-compose.selfhost.yml
  - docker-compose.yml
  - selfhost.env.template
- - api.Dockerfile
  - backup.Dockerfile
  - ingest.Dockerfile
  - intelligence.Dockerfile
  - migrate.Dockerfile
  - tracking.Dockerfile
  - updater.Dockerfile
  - web.Dockerfile
  - workers.Dockerfile
- - ingest.js
  - README.md
- - otel-collector.yaml
  - prometheus.yaml
- - campaigns.png
  - contacts.png
  - dashboard.png
  - email-builder.png
  - journey-canvas.png
  - login.png
  - segment-builder.png
- helio-demo.mp4
- helio-product-guide.pdf
- helio-setup-guide.pdf
- v2.0.0-release-notes.md
- - eslint.config.mjs
  - package.json
  - tsconfig.json
  - vitest.config.ts
- - eslint.config.mjs
  - package.json
  - README.md
  - vitest.config.mjs
- - eslint.config.mjs
  - package.json
  - README.md
  - tsconfig.json
  - vitest.config.ts
- - eslint.config.mjs
  - package.json
  - prisma.config.ts
  - README.md
  - tsconfig.json
  - vitest.config.ts
- - eslint.config.mjs
  - package.json
  - tsconfig.json
  - vitest.config.ts
- - eslint.config.mjs
  - package.json
  - README.md
  - tsconfig.json
  - vitest.config.ts
- - pyproject.toml
  - README.md
  - uv.lock
- - components.json
  - eslint.config.mjs
  - package.json
  - README.md
  - tsconfig.json
  - vitest.config.ts
- - build-bundle.ts
- install.ps1
- install.sh
.dockerignore
.editorconfig
.env.example
.gitattributes
.gitignore
.gitleaks.toml
.nvmrc
.prettierignore
.release-please-manifest.json
.trivyignore
CHANGELOG.md
CITATION.cff
CODE_OF_CONDUCT.md
commitlint.config.mjs
CONTRIBUTING.md
lefthook.yml
LICENSE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
prettier.config.mjs
README.md
release-please-config.json
renovate.json
SECURITY.md
SUPPORT.md
Taskfile.yml
turbo.json

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**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.

[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](https://raw.githubusercontent.com/achref-soua/helio/main/LICENSE)
[![Release](https://img.shields.io/github/v/release/achref-soua/helio?include_prereleases)](https://github.com/achref-soua/helio/releases)
[![Stars](https://img.shields.io/github/stars/achref-soua/helio?style=social)](https://github.com/achref-soua/helio/stargazers)

</div>

> ☀️ **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](#install-in-one-command) — the `helio` CLI 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](#roadmap) tells the story.

<a href="https://github.com/achref-soua/helio/releases/latest/download/helio-demo.mp4">▶&nbsp;Watch the demo film (MP4)</a>
 &nbsp;·&nbsp;
 <a href="docs/helio-product-guide.pdf">📘&nbsp;Read the product guide (PDF)</a>

The journey canvas and the AI copilot, captured from a live instance. The film and the guide regenerate from the real product via <code>task demo:video</code> and <code>task product:guide</code>.

## Why Helio

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.

## Features

> 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 -9` with 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|update` and `orders/create` into the CDP; every webhook is HMAC-verified, the shop domain resolves the org, and buyers gain `shopify_*` 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

### The product in action

|                                                                           |                                                                              |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| ![Overview dashboard with engagement timeline](https://raw.githubusercontent.com/achref-soua/helio/main/docs/assets/dashboard.png) | ![Contacts with scores, lists, and CSV import](https://raw.githubusercontent.com/achref-soua/helio/main/docs/assets/contacts.png)     |
| ![Segment builder with live preview](https://raw.githubusercontent.com/achref-soua/helio/main/docs/assets/segment-builder.png)     | ![Email builder with server-rendered preview](https://raw.githubusercontent.com/achref-soua/helio/main/docs/assets/email-builder.png) |

## Architecture

```mermaid
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.

## Install in one command

One-time prerequisite: Docker — a normal, free app install ([Desktop](https://docs.docker.com/desktop/) on Windows/macOS, [Engine](https://docs.docker.com/engine/install/) on servers). On Windows the installer below even offers to set it up for you. Helio handles absolutely everything else.

**Linux / macOS / servers & VMs**

```bash
curl -fsSL https://github.com/achref-soua/helio/releases/latest/download/install.sh | sh
```

**Windows (PowerShell)**

```powershell
irm https://github.com/achref-soua/helio/releases/latest/download/install.ps1 | iex
```

The 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](https://mailpit.axllent.org/) 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`](apps/docs/content/docs/self-hosting.mdx) for the full list.

## Develop from source

```bash
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 dev
```

Open `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:

```bash
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.

### Everything you can run

| 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](docs/runbooks/local-dev.md).

## Configuration

Every environment variable any service reads is documented in [`.env.example`](.env.example), added in the same PR as the feature that reads it. Required variables fail fast at startup.

## Deployment

Multi-stage, non-root, healthchecked images for every service live in [`infra/docker/`](infra/docker) and publish to GHCR on every `main` push (Trivy-gated, SBOM attached):

```bash
for service in web api ingest tracking workers intelligence; do
  docker build -f "infra/docker/$service.Dockerfile" -t "helio-$service" .
done
```

Compose profiles cover local/self-host topologies. For the fastest hosted start, paste [`infra/cloud/helio-cloud-init.yaml`](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`](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`](apps/docs/content/docs/production.mdx).

## Performance

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/`](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`](docs/production-readiness/v2.2.3.md) and [`infra/k6/README.md`](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](docs/adr/0022-pgbouncer-transaction-pooling.md)) — and ingestion resolves write keys through a shared Redis cache ([ADR-0023](docs/adr/0023-write-key-shared-cache.md)).

## Security

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](docs/security/audit-2.0.9.md)** documents the latest hardening pass — findings, fixes, and verification. See [SECURITY.md](SECURITY.md) for the policy and the full surface table, and the [threat model](docs/threat-model.md).

## Roadmap

| 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 |

## Documentation

- 📘 **[Product guide (PDF)](docs/helio-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)](docs/helio-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](apps/docs)** (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](docs/architecture.md) · [Decision log (ADRs)](docs/adr) · [Threat model](docs/threat-model.md)
- [Local-dev runbook](docs/runbooks/local-dev.md) · [SSO & SCIM setup](docs/sso.md) · [REST API guide](docs/api.md) · [API spec (OpenAPI 3.1)](apps/api/openapi.json)

## Contributing & policies

- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, branching model, commit conventions, PR rules
- [SECURITY.md](SECURITY.md) — how to report vulnerabilities (privately, please)
- [SUPPORT.md](SUPPORT.md) — where to ask questions and get help · [Discussions](https://github.com/achref-soua/helio/discussions) · [Wiki](https://github.com/achref-soua/helio/wiki)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — the community standard we hold each other to
- [CHANGELOG.md](CHANGELOG.md) — notable changes, release by release
- [Privacy Policy](apps/docs/content/docs/legal/privacy.mdx) — the project collects nothing; here is exactly what that means
- [Terms of Use](apps/docs/content/docs/legal/terms.mdx) — AGPL-3.0 is the contract; plain-words expectations around it
- [Data & Compliance](apps/docs/content/docs/legal/data-and-compliance.mdx) — where deployment data lives, the GDPR/email tooling, and the operator checklist
- [Marketing kit](docs/marketing/) — launch article, social post, and a discoverability checklist

## License

[AGPL-3.0](LICENSE) — free to self-host, modify, and redistribute; network-service modifications must stay open.

helio

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README