HelixDB/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.

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

• Check that Docker is running and that the app's port (3001 by default) is free, and pick another port if it is not.
• Generate local encryption keys in .env with scripts/setup.sh.
• Build and start the stack with Docker Compose, including a local AI model. On a Mac where Ollama is already running, it uses that instead.
• Wait for the health check to pass, then give you the URL.

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, OpenAI, Azure OpenAI, Amazon Bedrock, or a custom OpenAI-compatible endpoint. 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.

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.

• Docker with the Compose v2 plugin (docker compose, not docker-compose). Checked with Compose 2.29.
• git, bash and openssl for the setup scripts.
• Disk: several GB for the first run: the app image (about 0.9 GB), HelixDB, Ollama and the qwen3:4b model. Then room for your data: importing a large file can take several times its size while it runs. See deployment limits.
• Memory: local AI was developed and benchmarked on a 16 GB machine. Give Docker enough memory for the model, or choose Claude or OpenAI during setup.
• Node.js 24 and pnpm 10.7, only for local development.

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

• Connectors for Neon, Supabase, PlanetScale, PostgreSQL, MySQL, Neo4j, Stripe, WorkOS, PostHog, REST APIs, S3-compatible storage, file uploads (CSV, JSON, JSONL, Parquet) and an ingestion API.
• Automatic sync through native PostgreSQL and MySQL change capture where the database allows it, and scheduled snapshot refreshes otherwise.
• A suggested ontology that matches the same customers and records across sources, stored as real objects and relationships in HelixDB.
• Versioned data: immutable Parquet snapshots with profiles, schema-drift review and history, queried by isolated DuckDB processes.
• Home and Analyst: key metrics, and answers to your questions backed by executed SQL with snapshot citations.
• Your choice of AI: local qwen3:4b through Ollama by default, or Claude or OpenAI. AI-proposed changes are tested and wait for your review.
• Developer access: OpenAPI at /api/docs, a TypeScript SDK, scoped API tokens, and backup, restore and upgrade scripts.

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

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.

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.12@sha256:f22b50fdab8fadbf8b5a881e656f293fdf5c688bad018f503b8dbc2f0f29543d
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.

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.

• The app is published on 127.0.0.1 only. Never expose it with a reverse proxy, tunnel or port forward, and never publish the internal HelixDB, executor or Ollama ports.
• The API rejects requests whose Host is not this computer, and browser changes from any other origin, with 403.
• Connector and AI credentials are encrypted with ENCRYPTION_KEY from .env. Keep .env, .env.pre-restore-* files and backups private and out of git, and keep a copy of .env apart from your backups, which do not include the key. Backups made by an older backup.sh do: their config.env holds both keys in plain text, often in the repository's backups/ folder. Once you have a new backup and a separate copy of .env, delete those backups, or at least their config.env; backup.sh and upgrade.sh warn while any remain in backups/ or ~/helix-foundry-backups/. If you lose the key, stored credentials cannot be recovered. Do not try to rotate it by replacing the value.
• Generated SQL runs in a separate DuckDB executor on an internal network with no internet access, no connector credentials, no Linux capabilities, and memory and process limits.
• Scripts and the SDK use workspace-scoped API tokens from Settings → Developer tools. Tokens are read-only unless you grant write access.

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