HelixDB/helix-foundry

选用指南

AI 根据 README 整理 · 2026/10/16 21:21:35

使用方式

通过 Docker Compose 启动，访问 http://localhost:3001 使用。支持本地 AI（默认 qwen3:4b）或选择 Claude、OpenAI 等外部模型。

查看 README 依据

- 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. ## Manual quick start You need Docker with Compose v2 (see [requirements](#requirements)). ```sh

部署要求

需要 Docker（含 Compose v2 插件）、git、bash 和 openssl。首次运行需下载数 GB 数据（应用镜像约 0.9 GB，模型约 2.5 GB）。本地 AI 在 16 GB 内存机器上开发验证，建议给 Docker 足够内存。

查看 README 依据

This relies on Docker Desktop, which provides `host.docker.internal`. With another Docker runtime, use the default command above. ## Requirements - **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](docs/OPERATIONS.md#deployment-limits).

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: ```sh curl -fsS http://localhost:3001/api/health # {"ok":true,"service":"helix-foundry"} ```

已知限制

Windows 未测试，脚本需要 bash。应用仅发布在 127.0.0.1，不应通过反向代理或隧道暴露。备份不包含加密密钥，需单独保存 .env 文件。

查看 README 依据

- **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](#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. ## What you get - **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.

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

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