{"id":51829303,"url":"https://github.com/helipod-sh/helipod","last_synced_at":"2026-07-22T13:01:04.527Z","repository":{"id":372516767,"uuid":"1307680978","full_name":"helipod-sh/helipod","owner":"helipod-sh","description":"Open-source, self-hostable reactive Backend-as-a-Service — TypeScript functions, transactional data, live queries, deploy anywhere","archived":false,"fork":false,"pushed_at":"2026-07-22T11:59:00.000Z","size":14866,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-22T13:00:25.675Z","etag":null,"topics":["baas","backend","offline-first","postgres","reactive","realtime","self-hosted","sqlite","typescript","websocket"],"latest_commit_sha":null,"homepage":"https://helipod-sh.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/helipod-sh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-21T12:32:09.000Z","updated_at":"2026-07-22T11:59:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/helipod-sh/helipod","commit_stats":null,"previous_names":["helipod-sh/helipod"],"tags_count":89,"template":false,"template_full_name":null,"purl":"pkg:github/helipod-sh/helipod","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helipod-sh%2Fhelipod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helipod-sh%2Fhelipod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helipod-sh%2Fhelipod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helipod-sh%2Fhelipod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/helipod-sh","download_url":"https://codeload.github.com/helipod-sh/helipod/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helipod-sh%2Fhelipod/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35762225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-22T02:00:06.236Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["baas","backend","offline-first","postgres","reactive","realtime","self-hosted","sqlite","typescript","websocket"],"created_at":"2026-07-22T13:00:35.077Z","updated_at":"2026-07-22T13:01:04.490Z","avatar_url":"https://github.com/helipod-sh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helipod\n\nA Convex-compatible, self-hostable reactive backend. Write TypeScript query/mutation functions, run them server-side and transactionally, and get **reactive** results — when the underlying data changes, subscribed clients are pushed updates over a WebSocket. **Lightweight by default, scalable on demand** — the same app code runs as a single binary on a $5 VPS or (eventually) as a distributed fleet (see [docs/dev/architecture/scalability-spectrum.md](docs/dev/architecture/scalability-spectrum.md)).\n\n\u003e Status: **pre-1.0, but working end-to-end.** The reactive engine and Tier 0 production tooling are built and tested on both Node and Bun. Distributed Tier 2 and search/vector remain deferred. Architecture lives in [docs/dev/architecture/](docs/dev/architecture/); this is a clean-room implementation (see [CLAUDE.md](CLAUDE.md)).\n\n## What works today\n\n- **Reactive core** — MVCC document-log storage, a single-writer OCC transactor, a query engine with cursor pagination, and range-precise subscription invalidation: a write only re-runs the subscriptions whose read-set it intersects. No polling.\n- **Pluggable storage** — everything rides a narrow `DocStore` seam. Ships **embedded SQLite** (zero-config, single-file, the default) and **Postgres** (single-node, opt-in via a connection string, no app-schema migrations). The engine never learns which database it's on.\n- **The `helipod` CLI** — `dev` (watch + hot-reload + serve sync/HTTP), `serve` (production entrypoint), `deploy` (live hot-swap onto a running server), `build` (compile the app to a single self-contained binary), and typed `codegen`.\n- **Client SDK** — framework-agnostic client + `useQuery`/`useMutation`/`useAction` React hooks over the WebSocket sync protocol, plus a fully typed `api` from codegen.\n- **Dashboard** ([apps/dashboard](apps/dashboard)) — a live data browser (reactive via admin subscriptions, cursor pagination, structured filters), a logs viewer, and a function runner.\n- **Functions beyond queries/mutations** — `action`s (side-effect escape hatch that runs outside the transaction: `fetch`, clock, `ctx.runQuery`/`runMutation`/`runAction`), `httpAction` + an `httpRouter()` for webhooks/custom HTTP endpoints.\n- **Pluggable components** ([components/](components/)) — opt-in per project via `helipod.config.ts`: **auth**, **authz**, **scheduler** (`ctx.scheduler.runAfter`/`runAt`, crons, retries/backoff), and **workflow** (durable multi-step workflows with deterministic replay, `waitForEvent`, and saga/compensation).\n- **File storage** — always-on (not opt-in): a `_storage` system table + `Id\u003c\"_storage\"\u003e` + `ctx.storage`, on a pluggable `BlobStore` seam (**embedded filesystem**, zero-config default, or **S3-compatible object storage** for scale). Two-phase uploads (proxied through the engine on FS, presigned direct-to-bucket on S3), private-by-default bearer-token serving, and a background reaper that reclaims abandoned/deleted blobs. See [docs/enduser/files.md](docs/enduser/files.md).\n- **Self-host** — `docker compose up` brings up the engine + dashboard on a persistent volume; a single-binary build embeds everything but the database file.\n\n## Measured performance\n\nA single **1-vCPU / 512MB container of the shipped image serves 2,000 live reactive subscribers at ~12% CPU** (~102ms hot-push p50, ~21KB RSS per connection, disconnect-storm recovery in the reconnect window), and fleet nodes add horizontally with proven cgroup isolation (hammering one node moves its neighbors by −0.7%) and 15–16ms cross-node propagation. Measured, not estimated — the numbers come from a committed benchmark suite that boots the repo's own `Dockerfile` image under enforced cpu/memory budgets, and each finding documents its own limits (the capacity run hit Docker Desktop's port-forward ceiling before the node's; all containers shared one host — no multi-machine claim is made).\n\n- [benchmarks/docs/docker-fleet-findings.md](benchmarks/docs/docker-fleet-findings.md) — the budget capacity table, isolation proof, and WAN-latency multipliers\n- [benchmarks/docs/connections-findings.md](benchmarks/docs/connections-findings.md) — single-node connection scale (10,000 subscribers/node measured clean)\n- [benchmarks/docs/fleet-connections-findings.md](benchmarks/docs/fleet-connections-findings.md) — multi-node fleet behavior: cross-node latency, failover, parallelization\n\nReproduce with `bun run bench:dockerfleet` (requires Docker); baselines are committed under [benchmarks/baselines/](benchmarks/baselines/).\n\n## Repository layout\n\n```\npackages/            # the engine, in dependency order (see design §3)\n  values/            # Convex-compatible value system, validators, schema\n  errors/            # structured engine error hierarchy\n  id-codec/          # document/index id + storage-id encoding\n  index-key-codec/   # order-preserving index-key encoding\n  docstore/          # the storage seam (async DocStore contract)\n  docstore-sqlite/   # SQLite adapter — embedded, zero-config default\n  docstore-postgres/ # Postgres adapter — single-node, opt-in via --database-url\n  transactor/        # single-writer OCC transaction manager\n  query-engine/      # query execution + cursor pagination\n  executor/          # isolate-safe syscall executor\n  sync/              # reactive subscription tier (subscribe → write → push)\n  runtime-embedded/  # embedded runtime + loopback/WebSocket transports\n  component/         # component composition (namespaced tables, driver seam)\n  blobstore/         # the byte-storage seam (async BlobStore contract)\n  blobstore-fs/      # filesystem blob adapter — embedded, zero-config default\n  blobstore-s3/      # S3-compatible blob adapter — any bucket, opt-in via --storage-bucket\n  storage/           # _storage system table + ctx.storage facade + upload/serve HTTP routes + orphan reaper\n  codegen/           # typed Doc/Id/api generation\n  admin/             # admin API (data browser, deploy)\n  client/            # framework-agnostic client + React hooks\n  cli/               # the helipod CLI (dev / serve / deploy / build / codegen)\ncomponents/          # pluggable, opt-in via helipod.config.ts\n  auth/  authz/  scheduler/  workflow/\napps/\n  dashboard/         # live data browser, logs, function runner\nexamples/\n  chat/  auth-demo/  # runnable sample apps that double as integration tests\ndocs/\n  enduser/           # public product docs (the eventual docs site)\n  dev/               # engineering: architecture, research, clean-room internals\n  superpowers/       # design specs + implementation plans\n```\n\n## Develop\n\nRequires **[Bun](https://bun.com) ≥ 1.2** (the package manager + runtime). Node ≥ 22 is a fully-supported *target*, but the dev workflow runs on Bun.\n\n```bash\nbun install         # bootstrap the workspace\nbun run build       # build every package (Turborepo, topological)\nbun run test        # run all tests (vitest, under Node)\nbun run typecheck   # tsc --noEmit across packages\nbun run dev         # watch mode\n```\n\nSingle package, e.g. just the value system:\n\n```bash\nbun run --filter @helipod/values test\nbun run --filter @helipod/values test compare   # one test name/file filter\n```\n\n## The `helipod` CLI\n\n```bash\nhelipod dev        # local: watch functions, hot-reload, serve sync + HTTP + dashboard\nhelipod serve      # production: requires HELIPOD_ADMIN_KEY, binds 0.0.0.0, graceful shutdown\nhelipod deploy     # hot-swap functions + additive schema onto a running `serve` (opt-in)\nhelipod build      # compile the app to a single self-contained binary\nhelipod codegen    # regenerate the typed api / Doc / Id types\n```\n\n## Run (Tier 0)\n\n```bash\ndocker compose up        # one container, one volume — embedded SQLite (zero config)\n```\n\n`helipod serve` is the production entrypoint (requires `HELIPOD_ADMIN_KEY`); `docker compose up` runs it against a bind-mounted `convex/` with a persistent SQLite volume.\n\n### Storage: SQLite (default) or Postgres\n\nSQLite is the zero-config default and needs nothing. To use **Postgres** instead — same app code, no schema migrations — point the server at a connection string:\n\n```bash\nhelipod serve --database-url postgres://user:pass@host:5432/db\n# or\nHELIPOD_DATABASE_URL=postgres://user:pass@host:5432/db helipod serve\n```\n\nPostgres is a **single-node** backend (one engine per database — a second fails fast on a single-writer advisory lock); it is durable networked storage, not clustering. See [docs/enduser/self-hosting.md](docs/enduser/self-hosting.md) for a `docker compose` Postgres service, the persistence model, and known limitations.\n\n### File storage: filesystem (default) or S3/R2\n\nFile storage is always on — no opt-in needed. The filesystem backend is the zero-config default (`\u003cdata-dir\u003e/storage`); point at an S3-compatible bucket instead — same `ctx.storage` app code either way — via flag or env var:\n\n```bash\nhelipod serve --storage-bucket my-app-uploads --storage-endpoint https://s3.us-east-1.amazonaws.com\n# or\nHELIPOD_STORAGE_BUCKET=my-app-uploads helipod serve\n```\n\n`HELIPOD_STORAGE_ENDPOINT`/`HELIPOD_STORAGE_REGION`/`HELIPOD_STORAGE_PUBLIC_URL` plus the standard `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` round out the S3 config (flags win over env, same convention as `--database-url`). See [docs/enduser/files.md](docs/enduser/files.md) for the full guide, including the upload flow and the private-by-default access model.\n\n## License\n\n[**FSL-1.1-Apache-2.0**](LICENSE) (the Functional Source License, the same license Convex uses): free to use, modify, and self-host — including commercially — but you may not offer Helipod itself as a competing hosted service. Each release automatically converts to **Apache 2.0 two years** after it ships. Single-node self-hosting and deploy-anywhere are free forever.\n\nThe one exception is the [`ee/`](ee/) directory (scale/enterprise modules), which is source-available under a separate [commercial license](ee/LICENSE) and does not convert. See [docs/dev/business-model-and-licensing.md](docs/dev/business-model-and-licensing.md) for the full model.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelipod-sh%2Fhelipod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhelipod-sh%2Fhelipod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelipod-sh%2Fhelipod/lists"}