> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.

# helix start

> For the complete documentation index optimized for AI agents, see [llms.txt](/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.

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

## Usage

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
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/enterprise-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.

<Warning>
  The default `enterprise-dev` storage mode is in-memory. Stopping or restarting an in-memory instance wipes all local data.
</Warning>

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

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
# 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`](/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