HelixDB Docs

For the complete documentation index optimized for AI agents, see llms.txt.

Start a local v2 instance. By default the container starts in the background and the CLI waits until the local gateway accepts POST /v1/query requests before returning.

helix run is a backwards-compatible alias for helix start.

Usage

helix start [INSTANCE] [OPTIONS]

Arguments

Argument	Description
`INSTANCE`	Local instance name from `helix.toml`. If omitted, defaults to `dev` when present, otherwise prompts in a TTY or fails if non-interactive.

Available flags

Flag	Type	Description	Default
`--foreground`	Boolean	Run attached and stop the container on Ctrl-C. Useful for streaming startup logs.	`false`
`--port`	Number	Override the host port for this run. The container always listens on `8080` internally.	Value from `[local.<instance>] port` (default `6969`)
`--disk`	Boolean	Use on-disk storage backed by a CLI-managed MinIO container for this run.	`false`
`--persist`	Boolean	Write the resolved port and storage settings for this run back to `[local.<instance>]` in `helix.toml`, so future runs reuse them.	`false`

Behavior

Pulls ghcr.io/helixdb/enterprise-dev:latest (or the image/tag set in [local.<instance>]).
Names the container helix-<project>-<instance> and publishes the configured port to container port 8080.
Uses Docker or Podman based on [project] container_runtime in helix.toml.
Default storage is in-memory. Passing --disk starts a MinIO sidecar, creates the helix-db bucket, and runs enterprise-dev with S3-compatible storage environment variables.
Background mode (-d, --restart unless-stopped) waits up to ~30 seconds for POST /v1/query readiness and prints the URL and container name when ready.
Foreground mode (--rm) streams the container’s stdout/stderr until Ctrl-C, then removes the container.

The default enterprise-dev storage mode is in-memory. Stopping or restarting an in-memory instance wipes all local data.

With --disk, helix stop removes the Helix and MinIO containers but keeps the persistent local volume. helix prune removes that volume and deletes the persisted local data.

Examples

# Start the default 'dev' instance in the background
helix start

# Start a named instance in the background
helix start staging

# Stream logs in the foreground; Ctrl-C stops the container
helix start dev --foreground

# Override the host port for this run only
helix start dev --port 9090

# Start with persistent local storage for this run
helix start dev --disk

# Start on a new port and save it to helix.toml for future runs
helix start dev --port 9090 --persist

helix stop — stop a background instance
helix restart — restart a background instance
helix query — send a dynamic query to a running instance
helix logs — view container logs

Using the helix CLI

CLI Command Reference

helix start

Usage

Arguments

Available flags

Behavior

Examples

​Usage

​Arguments

​Available flags

​Behavior

​Examples

​Related

Usage

Arguments

Available flags

Behavior

Examples

Related