Helix Foundry operator
When to use this skill
Use this exact-project skill for the checkout and running installation of
HelixDB/helix-foundry.
It is a one-computer, one-owner application: resource documents and relationship
edges live in HelixDB, while isolated DuckDB executors query immutable Parquet
snapshots. Run the offline helper before any operator action:
python3 .agent-skills/helix-foundry/scripts/preflight.py --json
# installed root:
python3 "$SKILLS_ROOT/helix-foundry/scripts/preflight.py" --json
Route generic schema/entity planning to database-schema-design, API contracts
to api-design, auth/session design to authentication-setup, .env policy to
environment-setup, machine/container onboarding to system-environment-setup,
security hardening to security-best-practices, release promotion/rollback to
deployment-automation, and backend test strategy to backend-testing.
Instructions
- Freeze scope before touching the stack. Confirm the repository path and
pinned commit. The helper only inventories host binaries and, when
--repo
is supplied, checks bounded public repository shape, Git show-toplevel, and
rev-parse HEAD;
it never starts Docker/Compose, calls health URLs, reads .env, reads keys,
contacts providers, or claims a running Foundry. Its runtime_verified field
is always false.
- Keep the service loopback-only. Compose publishes to
127.0.0.1; do not
expose the app through LAN, reverse proxy, tunnel, or server-wide network
changes. Keep .env, volumes, backups, provider credentials, and backup key
files private. Never print, copy, or wholesale-read secrets.
- Classify reads honestly. Health, Compose status/log inventory, API docs,
and established-identity reads are read-only evidence. On a brand-new
installation, the first unauthenticated
GET /api/v1/me lazily provisions
the local owner and workspace; treat that request as a mutation and obtain
owner approval before using it. Never call it proof of a read-only fresh run.
- Gate all consequential work. Require explicit approval and the correct
workspace/token before source tests or sync, ingestion/uploads, pipeline
runs, provider or hosting connections, assistant actions, dataset acceptance,
ontology proposal validate/publish/reject/execute, or any external API call or
cost. Review validation output and hashes before publishing; refresh on HTTP
409 instead of blindly retrying.
- Protect data and recovery boundaries. Never use
docker compose down -v
or manual volume deletion; it deletes workspaces, snapshots, and stored
credentials. Backup, restore, and upgrade briefly stop or replace data and
therefore require owner approval, matching checkout/backup, and a rollback
decision. Removing a source does not revoke credentials at its provider.
- Use the pinned operational reference conditionally. For exact Compose,
model, API, identity, backup/restore/upgrade, connector, and SDK commands,
read
references/upstream.md. Do not improvise a
command when the reference gives the pinned form.
Examples
Offline source and host preflight
python3 .agent-skills/helix-foundry/scripts/preflight.py --json \
--repo /path/to/helix-foundry \
--expect-commit 84899851d845d1db98f9e328634f14e0ed4ad7b7
Interpret status: ok as passing offline checks only: a Docker path is not
Docker daemon health, and a Compose candidate is not proof that the Compose v2
plugin works. runtime_verified: false is authoritative.
Existing local installation inspection
Read references/upstream.md, then obtain owner-approved, loopback-only health,
Compose ps/recent logs, and API docs. Do not read .env wholesale. If identity
already exists, read-only GET /api/v1/me is allowed; on a fresh install it is a
provisioning mutation and must be gated as above.
New installation or recovery
Select a model path and inspect the exact pinned commands in the reference before
proposing setup.sh, Compose startup, backup, restore, or upgrade. Keep provider
keys, database passwords, OAuth/API tokens, and model/API spend user-owned.
Best practices
- Pin operational claims to upstream commit
84899851d845d1db98f9e328634f14e0ed4ad7b7.
- Treat source tests, generated SQL, ontology proposals, and assistant builds as reviewable outputs, never authority.
- Preserve the matching
.env/encryption key for existing volumes; replacing it can make stored credentials unrecoverable.
- Prefer the smallest read-only evidence set before any stateful or destructive action.
- Report unknown daemon/plugin/model readiness as unknown, not ready.
References
1---2name: helix-foundry3description: >4 Operate HelixDB/helix-foundry, the local-first company-data workspace that5 connects databases, hosted providers, APIs, files, Stripe, WorkOS and PostHog6 into an ontology backed by HelixDB and DuckDB. Use when the user names7 Helix Foundry, asks to install/start/diagnose its Docker Compose stack, inspect8 its local API or SDK, connect a source, run a sync/query/pipeline, review an9 ontology proposal, or back up/restore/upgrade an installation. Keep setup10 local and loopback-only; distinguish read-only inspection from data,11 credential, network, cloud-cost, and destructive operations.12allowed-tools: Bash Read Write Edit Glob Grep13compatibility: >14 Requires a filesystem-capable agent. Docker Desktop/Engine with Compose v2 is15 required for the container install; macOS Apple Silicon is the validated16 platform. Local development additionally requires Node.js 24 and pnpm 10.7.17metadata:18 version: "1.1.0"19 source: https://skillmd.com/skills/akillness/helix-foundry20 upstream: "https://github.com/HelixDB/helix-foundry"21 upstream_commit: "84899851d845d1db98f9e328634f14e0ed4ad7b7"22---2324# Helix Foundry operator2526## When to use this skill2728Use this exact-project skill for the checkout and running installation of29[HelixDB/helix-foundry](https://github.com/HelixDB/helix-foundry/tree/84899851d845d1db98f9e328634f14e0ed4ad7b7).30It is a one-computer, one-owner application: resource documents and relationship31edges live in HelixDB, while isolated DuckDB executors query immutable Parquet32snapshots. Run the offline helper before any operator action:3334```sh35python3 .agent-skills/helix-foundry/scripts/preflight.py --json36# installed root:37python3 "$SKILLS_ROOT/helix-foundry/scripts/preflight.py" --json38```3940Route generic schema/entity planning to `database-schema-design`, API contracts41to `api-design`, auth/session design to `authentication-setup`, `.env` policy to42`environment-setup`, machine/container onboarding to `system-environment-setup`,43security hardening to `security-best-practices`, release promotion/rollback to44`deployment-automation`, and backend test strategy to `backend-testing`.4546## Instructions47481. **Freeze scope before touching the stack.** Confirm the repository path and49 pinned commit. The helper only inventories host binaries and, when `--repo`50 is supplied, checks bounded public repository shape, Git `show-toplevel`, and51 `rev-parse HEAD`;52 it never starts Docker/Compose, calls health URLs, reads `.env`, reads keys,53 contacts providers, or claims a running Foundry. Its `runtime_verified` field54 is always `false`.552. **Keep the service loopback-only.** Compose publishes to `127.0.0.1`; do not56 expose the app through LAN, reverse proxy, tunnel, or server-wide network57 changes. Keep `.env`, volumes, backups, provider credentials, and backup key58 files private. Never print, copy, or wholesale-read secrets.593. **Classify reads honestly.** Health, Compose status/log inventory, API docs,60 and established-identity reads are read-only evidence. On a brand-new61 installation, the first unauthenticated `GET /api/v1/me` lazily provisions62 the local owner and workspace; treat that request as a mutation and obtain63 owner approval before using it. Never call it proof of a read-only fresh run.644. **Gate all consequential work.** Require explicit approval and the correct65 workspace/token before source tests or sync, ingestion/uploads, pipeline66 runs, provider or hosting connections, assistant actions, dataset acceptance,67 ontology proposal validate/publish/reject/execute, or any external API call or68 cost. Review validation output and hashes before publishing; refresh on HTTP69 409 instead of blindly retrying.705. **Protect data and recovery boundaries.** Never use `docker compose down -v`71 or manual volume deletion; it deletes workspaces, snapshots, and stored72 credentials. Backup, restore, and upgrade briefly stop or replace data and73 therefore require owner approval, matching checkout/backup, and a rollback74 decision. Removing a source does not revoke credentials at its provider.756. **Use the pinned operational reference conditionally.** For exact Compose,76 model, API, identity, backup/restore/upgrade, connector, and SDK commands,77 read [`references/upstream.md`](references/upstream.md). Do not improvise a78 command when the reference gives the pinned form.7980## Examples8182### Offline source and host preflight8384```sh85python3 .agent-skills/helix-foundry/scripts/preflight.py --json \86 --repo /path/to/helix-foundry \87 --expect-commit 84899851d845d1db98f9e328634f14e0ed4ad7b788```8990Interpret `status: ok` as passing offline checks only: a Docker path is not91Docker daemon health, and a Compose candidate is not proof that the Compose v292plugin works. `runtime_verified: false` is authoritative.9394### Existing local installation inspection9596Read `references/upstream.md`, then obtain owner-approved, loopback-only health,97Compose `ps`/recent logs, and API docs. Do not read `.env` wholesale. If identity98already exists, read-only `GET /api/v1/me` is allowed; on a fresh install it is a99provisioning mutation and must be gated as above.100101### New installation or recovery102103Select a model path and inspect the exact pinned commands in the reference before104proposing `setup.sh`, Compose startup, backup, restore, or upgrade. Keep provider105keys, database passwords, OAuth/API tokens, and model/API spend user-owned.106107## Best practices108109- Pin operational claims to upstream commit `84899851d845d1db98f9e328634f14e0ed4ad7b7`.110- Treat source tests, generated SQL, ontology proposals, and assistant builds as reviewable outputs, never authority.111- Preserve the matching `.env`/encryption key for existing volumes; replacing it can make stored credentials unrecoverable.112- Prefer the smallest read-only evidence set before any stateful or destructive action.113- Report unknown daemon/plugin/model readiness as unknown, not ready.114115## References116117- [`references/upstream.md`](references/upstream.md) — pinned source shape plus Compose/model/API/identity/backup/SDK operations and provenance.118- [Pinned upstream tree](https://github.com/HelixDB/helix-foundry/tree/84899851d845d1db98f9e328634f14e0ed4ad7b7)119- [Pinned README and setup](https://github.com/HelixDB/helix-foundry/blob/84899851d845d1db98f9e328634f14e0ed4ad7b7/README.md)120- [Pinned AGENTS runbook](https://github.com/HelixDB/helix-foundry/blob/84899851d845d1db98f9e328634f14e0ed4ad7b7/AGENTS.md)121- [Pinned API contract](https://github.com/HelixDB/helix-foundry/blob/84899851d845d1db98f9e328634f14e0ed4ad7b7/docs/API.md)122- [Pinned operations limits](https://github.com/HelixDB/helix-foundry/blob/84899851d845d1db98f9e328634f14e0ed4ad7b7/docs/OPERATIONS.md)