Skip to main content
For the complete documentation index optimized for AI agents, see llms.txt.
Local development runs the prebuilt ghcr.io/helixdb/enterprise-dev:latest container and exposes the gateway at POST /v1/query. By default, storage is in-memory. Use --disk when you want persistent local data backed by a CLI-managed MinIO volume.

​
Prerequisites

  • Docker or Podman on PATH.
  • The Helix CLI: curl -sSL "https://install.helix-db.com" | bash.

​
Initial setup

For an agent-assisted first app, helix chef can run this setup end-to-end: it installs Helix skills and the docs MCP, initializes ~/my-first-helix-project, starts dev, seeds starter data, and launches your coding agent to build the app. 
helix chef
Use the manual flow below when you want to scaffold and run each step yourself.
1

Scaffold a project

mkdir my-helix-app
cd my-helix-app
helix init
helix init creates helix.toml, .helix/, and examples/request.json.
2

Start the local runtime

helix start dev
Starts a background container named helix-my-helix-app-dev on port 6969. The CLI waits until the gateway accepts POST /v1/query before returning.For attached log streaming use helix start dev --foreground and stop with Ctrl-C.For persistent local storage use helix start dev --disk, or initialize the project with helix init local --disk to make disk mode the default for that instance.
3

Send the example query

helix query dev --file examples/request.json
The example counts User nodes. Try --compact to print on one line, or --warm to populate caches without printing a response.
Default local storage is in-memory. helix stop or helix restart wipes in-memory data — keep your seed data in JSON request files so you can replay it, or use --disk for persistent local storage.

​
Persistent local storage

# One-off disk mode for this run
helix start dev --disk

# Persist disk mode in helix.toml for a new local instance
helix add local --name persistent --disk
helix start persistent
Disk mode starts a MinIO sidecar, creates the helix-db bucket, and stores data in a Helix-managed Docker/Podman volume. helix stop removes the containers but keeps the volume. helix prune <instance> removes the volume and deletes the persisted local data.

​
Iteration loop

# Edit a request file (or write a new one)
$EDITOR examples/request.json

# Send the request
helix query dev --file examples/request.json

# Tail container logs in another shell
helix logs dev --follow

# Stop and restart from a clean state
helix restart dev
helix restart falls back to a fresh helix start if the container has been removed.

​
Multiple local instances

# Add a second local instance on a different port
helix add local --name staging --port 9090

# Run them independently
helix start dev
helix start staging

# See what's running
helix status
Each instance is isolated by container name and host port. Disk-mode instances also get their own MinIO container, network, and volume.

​
Inspecting logs

helix logs dev               # one-shot dump from docker/podman logs
helix logs dev --follow      # stream
--range, --start, and --end are Helix Cloud-only and rejected for local instances.

​
Cleaning up

GoalCommand
Stop one instancehelix stop <instance>
Restart one instancehelix restart <instance>
Remove containers, workspace state, and disk-mode volume for one instancehelix prune <instance>
Remove everything Helix-owned, for every local instancehelix prune --all (--yes in non-TTY)
Permanently delete an instance from helix.tomlhelix delete <instance> (--yes in non-TTY)
helix prune only touches Helix-managed containers (helix-<project>-<instance> and disk-mode MinIO sidecars), networks, volumes, and the per-instance .helix/<instance> directory. It never runs a broad docker/podman system prune.

​
Authoring dynamic queries

A request JSON file must contain:
  • request_type: lowercase "read" or "write".
  • query_name (optional): top-level operational name for logs and query diagnostics. Missing or null falls back to __dynamic__.
  • query: the query object — queries[] entries such as {"Query": {"name": "...", "steps": [...], "condition": null}}, plus a returns[] list.
  • parameters (optional): named parameter values.
The first step must be a source step (for example NWhere) before any terminal step like Count. See helix query for the validation rules.

​
What next?

Helix Cloud workflow

Authenticate, link a project, and query a remote cluster

CLI Command Reference

Every command, subcommand, and flag