helix start

Reference

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

Start a local instance. By default the container starts in the background and the CLI waits for GET /healthz to report ready 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/helixdb:v0.0.4 (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 helixdb with S3-compatible storage environment variables.
• Background mode (-d, --restart unless-stopped) waits up to ~30 seconds for GET /healthz 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 helixdb 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

Related

• 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