Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt

Use this file to discover all available pages before exploring further.

For the complete documentation index optimized for AI agents, see llms.txt.
Run 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.

​
Usage

helix run [INSTANCE] [OPTIONS]

​
Arguments

ArgumentDescription
INSTANCELocal instance name from helix.toml. If omitted, defaults to dev when present, otherwise prompts in a TTY or fails if non-interactive.

​
Available flags

FlagTypeDescriptionDefault
--foregroundBooleanRun attached and stop the container on Ctrl-C. Useful for streaming startup logs.false
--portNumberOverride the host port for this run. The container always listens on 8080 internally.Value from [local.<instance>] port (default 8080)
--diskBooleanUse on-disk storage backed by a CLI-managed MinIO container for this run.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 run

# Start a named instance in the background
helix run staging

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

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

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