> ## Documentation Index
> Fetch the complete documentation index at: https://helix-isolate-failing-index-entities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# helix start

> Start a local instance in the background or foreground

<div className="flex flex-wrap gap-2"><Badge color="gray" size="sm">Reference</Badge></div>

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.

<Note>
  `helix run` is a backwards-compatible alias for `helix start`.
</Note>

## Usage

```bash theme={null}
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.

<Warning>
  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.
</Warning>

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](/cli/workflows/local#migrate-minio-disk-data).

## Examples

```bash theme={null}
# 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
```

## Related

* [`helix stop`](/cli/command-reference/stop) — stop a background instance.
* [`helix restart`](/cli/command-reference/restart) — restart a background instance.
* [`helix query`](/cli/command-reference/query) — send a dynamic query to a running instance.
* [`helix logs`](/cli/command-reference/logs) — view container logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.