Skip to main content
Guide
For the complete documentation index optimized for AI agents, see llms.txt.
Local development runs the prebuilt ghcr.io/helixdb/helixdb:v0.0.4 container and exposes the standalone server at POST /v2/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.
Use the manual flow below when you want to scaffold and run each step yourself.
1

Scaffold a project

helix init creates helix.toml, .helix/, and examples/request.json.
2

Start the local runtime

Starts a background container named helix-my-helix-app-dev on port 6969. The CLI waits for GET /healthz to report ready 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

The example counts User nodes. Try --compact to print on one line, or --warm to populate the standalone process caches while returning the normal 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

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

helix restart falls back to a fresh helix start if the container has been removed.

​
Multiple local instances

Each instance is isolated by container name and host port. Disk-mode instances also get their own MinIO container, network, and volume.

​
Inspecting logs

--range, --start, and --end are Helix Cloud-only and rejected for local instances.

​
Cleaning up

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: exactly one read or write batch with entries[] and returns[].
  • parameters and parameter_types (optional): named values and their declared types.
Each entry contains one nested operation-tree root; source operations appear at the innermost input. See helix query for the request shape.

​
What next?

Helix Cloud workflow

Authenticate, link a project, and query a remote cluster

CLI Command Reference

Every command, subcommand, and flag