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 |
Behavior
- Pulls
ghcr.io/helixdb/database-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.
--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
