HelixDB Docs

Reference

Start a local instance. By default the container starts in the background and the CLI waits for GET /healthz to report ready before returning. Local only.

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`. Defaults to `dev`, then the only local instance, then a picker in a terminal; otherwise the command fails and lists the local instances.

Options

Flag	Description	Default
`--foreground`	Run attached and stop the container on Ctrl-C. Useful for streaming startup logs.	Off (background)
`--port <PORT>`	Override the host port for this run. The container always listens on `8080` internally.	Value from `[local.<instance>] port` (default `6969`)
`--disk`	Use on-disk storage backed by a CLI-managed SeaweedFS container for this run. Cannot be combined with `--storage-uri`.	Off
`--storage-uri <URI>`	Use an S3 or S3-compatible bucket and prefix for this run, for example `s3://bucket/prefix/`.	—
`--s3-region <REGION>`	Region for S3 storage.	—
`--s3-endpoint-url <URL>`	Custom S3-compatible endpoint URL.	—
`--s3-allow-http`	Allow plain HTTP for the S3 endpoint.	Off
`--image-version <VERSION>`	Override the image tag, or `sha256:<64 lowercase hex digits>`, for this run.	Configured tag
`--pull <POLICY>`	`always`, `missing`, or `never`. Explicit policies also apply to the disk-mode SeaweedFS image.	Configured policy, otherwise `always` for `latest` and `missing` for other versions
`--persist`	Write the resolved port, storage, image, and pull settings for this run back to `[local.<instance>]` in `helix.toml`, so future runs reuse them.	Off
`--json`	Print `instance`, `url`, and `container` as JSON on stdout once ready, and never prompt. Not allowed with `--foreground`.	Off

Behavior

Defaults to ghcr.io/helixdb/helixdb:v0.0.9. Flags override the image tag and pull policy set in [local.<instance>].
always requires a successful pull, missing uses a cached image when available, and never fails if the image is not cached. A failed pull never silently falls back to an older cached image.
All required images are resolved before overrides are saved or containers are replaced, so a failed resolution leaves helix.toml unchanged. Helix and disk-mode dependencies start by their resolved immutable image IDs.
The disk-mode SeaweedFS image defaults to missing unless a pull policy is explicitly configured.
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 SeaweedFS S3 sidecar (ghcr.io/chrislusf/seaweedfs:4.47, pinned by digest) that creates the helix-db bucket, waits up to 60 seconds for the bucket to accept signed requests, and runs helixdb with S3-compatible storage environment variables.
With --disk or S3 storage, the server caches data on disk in a per-instance helix-<project>-<instance>-cache volume mounted at /var/cache/helix. The CLI sets its budget (HELIX_DISK_CACHE_BYTES) to 64 MiB in disk mode, where SeaweedFS already keeps the data on your machine, and to 1 GiB for an S3 bucket.
--s3-region, --s3-endpoint-url, and --s3-allow-http require --storage-uri, unless the instance already uses S3 storage; then they override its saved S3 settings for this run.
The CLI loads .env from the project root before starting. For S3 storage, it passes any AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_PROFILE, AWS_REGION, and AWS_DEFAULT_REGION values from the environment into the container.
Background mode (-d, --restart unless-stopped) waits up to ~30 seconds for GET /healthz readiness and prints the URL and container name when ready. Progress goes to stderr.
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. The CLI shows this warning the first time you start each in-memory instance.

With --disk, helix stop removes the Helix and SeaweedFS containers but keeps the persistent local volume. helix prune removes that volume and deletes the persisted local data. helix stop also keeps the disk-cache volume, so the next start reads recently used data locally, and helix prune removes it. With S3 storage, helix stop, helix restart, and helix prune never delete remote data. Older CLI releases stored disk-mode data with MinIO, which SeaweedFS cannot read. helix start removes an old MinIO sidecar, starts on a new SeaweedFS volume, and warns while the MinIO volume remains. See Migrate MinIO disk 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

# Track the latest image explicitly
helix start dev --image-version latest

# Save a specific image version
helix start dev --image-version v0.0.9 --persist

# Start using cached images only
helix start dev --pull never

# Store data in an S3 bucket and save that setting to helix.toml
helix start dev --storage-uri s3://bucket/prefix/ --s3-region us-east-1 --persist

# 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

Options

Behavior

Examples

​Usage

​Arguments

​Options

​Behavior

​Examples

​Related

Usage

Arguments

Options

Behavior

Examples

Related