Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
With
CLI Command Reference
helix start
Start a local instance in the background or foreground
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.12. Flags override the image tag and pull policy set in[local.<instance>]. alwaysrequires a successful pull,missinguses a cached image when available, andneverfails 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.tomlunchanged. Helix and disk-mode dependencies start by their resolved immutable image IDs. - The disk-mode SeaweedFS image defaults to
missingunless a pull policy is explicitly configured. - Names the container
helix-<project>-<instance>and publishes the configured port to container port8080. - Uses Docker or Podman based on
[project] container_runtimeinhelix.toml. - Default storage is in-memory. Passing
--diskstarts a SeaweedFS S3 sidecar (ghcr.io/chrislusf/seaweedfs:4.47, pinned by digest) that creates thehelix-dbbucket, waits up to 60 seconds for the bucket to accept signed requests, and runshelixdbwith S3-compatible storage environment variables. - With
--diskor S3 storage, the server caches data on disk in a per-instancehelix-<project>-<instance>-cachevolume 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-httprequire--storage-uri, unless the instance already uses S3 storage; then they override its saved S3 settings for this run.- The CLI loads
.envfrom the project root before starting. For S3 storage, it passes anyAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN,AWS_PROFILE,AWS_REGION, andAWS_DEFAULT_REGIONvalues from the environment into the container. - Background mode (
-d,--restart unless-stopped) waits up to ~30 seconds forGET /healthzreadiness 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.--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.12 --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
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.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.