helix-foundry README

The project's README from github.com/HelixDB/helix-foundry. As one markdown file: README.md.

Helix Foundry

Your company's data, connected into one ontology, on your own computer.

Helix Foundry is a local-first data workspace built on HelixDB and DuckDB. Connect the tools your company already runs on, such as your database, Stripe, WorkOS, PostHog, files and APIs, and it suggests one connected ontology across them that you can explore and ask questions of. There are no accounts and nothing to host: it runs on your computer, and AI runs locally by default.

The Helix Foundry Explorer showing accounts, users, invoices, subscriptions, campaigns, SSO connections and support tickets as one connected graph

Get started with your coding agent

You need Docker installed and running. The first run downloads several GB, so give it a few minutes.

Paste this prompt into Claude Code, Codex, Cursor or any coding agent that can run terminal commands:

Set up Helix Foundry on this computer.

Clone https://github.com/helixdb/helix-foundry.git (or use the copy I already
have), cd into it, then read AGENTS.md and follow it to install, start and
verify the app. Ask me before doing anything that deletes data or stops
something that is already running. When it is ready, give me the URL and
tell me what to do next.

Your agent will ask you to approve git, docker and network commands as it goes. Approve them one at a time rather than allowing every docker command up front; the runbook asks before anything that deletes data.

What your agent will do

What you do next

  1. Open the URL (http://localhost:3001 by default). There is no account to create.
  2. Guided setup takes you through AI → Data → Ontology. Choose Local, Claude or OpenAI. Connect your data, or choose Continue with sample data. Then confirm the suggested ontology.
  3. Home opens with your key metrics. Ask anything about your data from the box at the top.

You enter Claude or OpenAI keys and database credentials yourself, in the browser. Your agent never needs them.

Manual quick start

You need Docker with Compose v2 (see requirements).

git clone https://github.com/helixdb/helix-foundry.git
cd helix-foundry
./scripts/setup.sh --compose

setup.sh writes fresh keys to .env if it does not exist yet, then builds and starts the app, a background worker, the DuckDB executor, HelixDB and Ollama. The first run builds the image and downloads HelixDB, Ollama and the qwen3:4b model (roughly 2.5 GB), so give it several minutes.

It is ready when the health check answers:

curl -fsS http://localhost:3001/api/health
# {"ok":true,"service":"helix-foundry"}

Then open http://localhost:3001. The model keeps downloading in the background, and you can start setup before it finishes.

Port 3001 already in use? Create .env first, then set the port and the matching origin together:

./scripts/setup.sh                                   # creates .env with fresh keys
echo 'PUBLIC_PORT=3005' >> .env
echo 'PUBLIC_ORIGIN=http://localhost:3005' >> .env
./scripts/setup.sh --compose

Add the two lines once; if .env already has them, change their values instead. Always change both. If only the port changes, pages load but every save fails with 403 Origin is not allowed.

Apple Silicon. Docker cannot use Metal, so local AI is faster with native Ollama. Start Ollama, then run the stack without the bundled model:

./scripts/setup.sh
grep -q '^MODEL_ENDPOINT=' .env || echo 'MODEL_ENDPOINT=http://host.docker.internal:11434' >> .env
docker compose up -d --build

This relies on Docker Desktop, which provides host.docker.internal. With another Docker runtime, use the default command above.

Requirements

Helix Foundry is developed and validated on macOS with Apple Silicon, and CI runs on Linux. Windows is untested, and the scripts need bash.

What you get

The full feature list, connector details and architecture are in the guide.

Everyday commands

Run these from the repository. If you use native Ollama, leave out --profile local.

docker compose --profile local ps -a                # status
docker compose --profile local logs -f app worker   # follow logs (Ctrl+C to stop)
docker compose --profile local stop                 # stop
docker compose --profile local up -d                # start again

The stack starts again with Docker unless you stopped it.

Upgrade. Run ./scripts/upgrade.sh. It backs up to ~/helix-foundry-backups/ first and stops if the backup fails, then pulls and rebuilds; if the rebuild fails, run it again. If the new release changes HelixDB, it asks first: a newer HelixDB upgrades your data one way, so only that backup can take you back. To go back, run the two commands it prints at the end. A checkout from before scripts/upgrade.sh records the running commit and pulls once first; see operations.

Back up and restore. ./scripts/backup.sh PATH briefly stops the services and archives the HelixDB and data volumes to a folder outside the repository. Backups leave out your encryption key, so keep a separate copy of .env, for example in a password manager. --include-key adds .env, encrypted with a passphrase. ./scripts/restore.sh PATH --replace replaces the current data. It refuses a backup made with another key unless you pass your copy with --env-file, and keeps the .env it replaces as .env.pre-restore-TIME.

Never run docker compose down -v unless you mean to delete everything. It removes all workspaces, imported data and stored credentials. See operations for upgrades, change capture and limits.

Local development

Use Node.js 24 and pnpm 10.7. Run HelixDB in Docker and the app natively:

pnpm install
./scripts/setup.sh
docker run -d --name helix-foundry-dev -p 127.0.0.1:6996:8080 \
  -e HELIX_DATA_DIR=/var/lib/helix -v helix-foundry-dev:/var/lib/helix \
  ghcr.io/helixdb/helixdb:v0.0.6@sha256:94b29942658ebdca0a91bf15edffe921a46da3e26e1223ea333ccce58c6212dd
pnpm dev

Open http://localhost:5173. pnpm dev runs the API on 3001, the executor on 3002 and the web app on 5173. Local AI also needs Ollama on port 11434 (ollama serve). Before opening a pull request, run the same checks as CI: pnpm typecheck, pnpm test and pnpm build. The guide covers tests, ports and the SDK.

Security model

Helix Foundry is built for one person on their own computer. There are no accounts and no sign-in, so anyone who can reach the app controls every workspace.

Documentation

Document What it covers
AGENTS.md Runbook for coding agents: preflight, setup, verification and troubleshooting
docs/GUIDE.md Features, connectors, AI and review, architecture, development and testing
docs/DESIGN.md Existing visual standards, UI tokens, progress feedback and accessibility
docs/onboarding.md Onboarding API routes, SDK methods and import limits
docs/OPERATIONS.md Install profiles, diagnostics, change capture, backup, restore, upgrades, limits
docs/HOSTING.md Neon, Supabase and PlanetScale sign-in, scopes and permissions
docs/API.md REST API reference, authentication and the TypeScript SDK
docs/VALIDATION.md Test results, benchmarks and known limits from the September and October 2026 validation runs; the backup, restore and upgrade scripts have only stub Docker tests so far

License

Helix Foundry is released under the Apache License 2.0. See NOTICE for attribution.

helix-foundry (HelixDB/helix-foundry)

Searching Database…

1.6K ·GitHub
Helix-foundry
Что это?Helix Foundry — рабочее пространство данных с приоритетом локальности (local-first), которое связывает инструменты вашей компании (базы данных, Stripe, WorkOS, PostHog, файлы, API) в единую предлагаемую онтологию, хранящуюся в HelixDB, и позволяет исследовать данные и задавать о них вопросы.
Это хостинговый сервис или всё работает целиком на моей машине?Он работает целиком на вашем компьютере через Docker Compose, без создания аккаунтов и без удалённого хостинга; AI по умолчанию тоже работает локально.
Как это запустить?Вставьте установочный промпт в кодинг-агента вроде Claude Code, Codex или Cursor — он проверит Docker, сгенерирует ключи шифрования и соберёт/запустит стек Docker Compose; как вариант, запустите ручной быстрый старт через scripts/setup.sh самостоятельно.
Что должно быть установлено перед стартом?Нужны Docker с плагином Compose v2, а также git, bash и openssl для установочных скриптов; первый запуск дополнительно скачивает несколько гигабайт, включая HelixDB, Ollama и модель qwen3:4b.
Будет ли это работать на Windows или Mac с Intel?Windows не тестировалась, потому что скриптам нужен bash, а на Apple Silicon Docker не может использовать Metal, поэтому для более быстрого локального AI рекомендуется нативная Ollama вместо модели из Docker.
Покидают ли мою машину мои данные или использование AI?Нет, по умолчанию всё остаётся локальным: приложение слушает только 127.0.0.1, отклоняет запросы с других origin, а AI работает локально через Ollama, если вы сами сознательно не выберете Claude или OpenAI и не введёте свои ключи.
К каким источникам данных он может подключаться?Поддерживаются Neon, Supabase, PlanetScale, PostgreSQL, MySQL, Stripe, WorkOS, PostHog, REST API, S3-совместимые хранилища, загрузка файлов (CSV, JSON, JSONL, Parquet) и универсальный API приёма данных.
Как он поддерживает данные в актуальном состоянии?Он использует нативный захват изменений для PostgreSQL и MySQL там, где это поддерживается, а для прочих источников переключается на запланированное обновление снапшотов, храня версионированные неизменяемые Parquet-снапшоты с историей дрейфа схемы.
Какие варианты AI доступны, чтобы задавать вопросы о моих данных?При настройке вы выбираете Local, Claude или OpenAI; локальный вариант использует модель qwen3:4b через Ollama, а Claude и OpenAI требуют ввести собственные API-ключи в браузере.
Могут ли разработчики встроить Helix Foundry в другие инструменты?Да, он отдаёт OpenAPI-спецификацию на /api/docs, TypeScript SDK и API-токены с ограниченной областью действия, по умолчанию с доступом только на чтение, из Settings → Developer tools.
What are similar projects?m_flow, MemOS, jevbox, semantica, oxynote, airbyte, headroom, tabularis
Which topics is it in?etl, duckdb, graph-database, data-engineering, knowledge-base, ollama, docker-compose, anthropic, sdk, local-first, rest-api, database
Creator
HelixDB
Size
1.3 MB
Stars
1.6K
Updated
CommitOct 13
Age
11d
Commits · 90 Days