> ## 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.

# Local Development

> For the complete documentation index optimized for AI agents, see [llms.txt](/llms.txt).

For local development, Helix ships a combined `enterprise-dev` image that runs a gateway and
database together in a single container. The image supports two storage modes:

* **In-memory** — fastest to spin up, but data is lost on container restart.
* **On-disk** — backed by an S3-compatible object store such as
  [MinIO](https://min.io/), so data survives restarts and mirrors the production storage path.

In both modes:

* If `PATH_TO_QUERIES` is unset, send queries as dynamic `POST /v1/query` requests.
* If `PATH_TO_QUERIES` is set, the container preloads your query bundle from the mounted
  `queries.json` file during startup.

## Quick Start with the CLI

The fastest way to get started is the Helix CLI, which wraps the `enterprise-dev` image and
handles container lifecycle for you:

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
# Install the CLI
curl -sSL "https://install.helix-db.com" | bash

# Scaffold a new project (creates helix.toml and examples/request.json)
mkdir my-helix-app && cd my-helix-app
helix init local --name dev

# Start the local in-memory runtime on port 6969
helix start dev

# Or start with persistent local storage backed by MinIO
helix start dev --disk

# Send a dynamic query
helix query dev --file examples/request.json

# Stop the instance when you're done
helix stop dev
```

For installation details, Helix Cloud authentication, and the full command reference, see the
[CLI Getting Started guide](/cli/getting-started).

### AI-assisted query authoring

If you develop with a coding agent, install the Helix skills bundle for writing, optimizing, and
translating queries. Run it from your project root so the skills can inspect your local schema:

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
npx skills add HelixDB/skills
```

The agent then loads the relevant skill automatically when you ask it to write a query, tune a
slow traversal, or translate a Cypher/Gremlin query.

### Configuring disk mode

To make disk mode the default for a local instance, initialize or add it with `--disk`:

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
helix init local --disk
helix add local --name persistent --disk
```

The CLI-managed disk mode starts a MinIO sidecar, creates the `helix-db` bucket, and keeps the
MinIO volume across `helix stop`. Use `helix prune <instance>` to delete the persisted local data.

If you'd rather manage the containers yourself with Docker Compose, the in-memory and on-disk
setups below show the raw image configuration that the CLI disk mode mirrors.

## Installing the SDKs

To author queries against your local instance, install the SDK for your language.
TypeScript, Rust, and Python can generate bundles; Go v1 posts dynamic requests directly.

<CodeGroup>
  ```bash TypeScript theme={"languages":{"custom":["languages/helixql.json"]}}
  npm install @helix-db/helix-db
  ```

  ```bash Rust theme={"languages":{"custom":["languages/helixql.json"]}}
  cargo add helix-db
  ```

  ```bash Go theme={"languages":{"custom":["languages/helixql.json"]}}
  go get github.com/helixdb/helix-db/sdks/go
  ```

  ```bash Python theme={"languages":{"custom":["languages/helixql.json"]}}
  pip install 'git+https://github.com/HelixDB/helix-db.git#subdirectory=sdks/python'
  ```
</CodeGroup>

For the full project layout, generator setup, and authoring walkthrough, see
[TypeScript Project Setup](/database/typescript-project-setup),
[Rust Project Setup](/database/rust-project-setup),
[Go Project Setup](/database/go-project-setup), and
[Python Project Setup](/database/python-project-setup).

## In-Memory

<Warning>
  In-memory mode is development-only. Stopping or restarting the container wipes all data.
</Warning>

You can add this service to a local `docker-compose.yml`:

```yaml expandable theme={"languages":{"custom":["languages/helixql.json"]}}
services:
  helix:
    image: ghcr.io/helixdb/enterprise-dev
    restart: unless-stopped
    ports:
      - "6969:8080"
    environment:
      PATH_TO_QUERIES: /workspace/queries.json
    volumes:
      - ./queries.json:/workspace/queries.json:ro
```

To run without a preloaded bundle, omit `PATH_TO_QUERIES` and the mounted `queries.json` volume;
queries still execute as dynamic `POST /v1/query` requests.

## On-Disk

For persistent local development, point the `enterprise-dev` image at an S3-compatible object
store. The example below brings up MinIO, initializes the `helix-db` bucket, and configures the
`enterprise-dev` container to read and write to it. Data persists across container restarts as
long as the MinIO volume is preserved.

```yaml expandable theme={"languages":{"custom":["languages/helixql.json"]}}
services:
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    restart: unless-stopped
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - minio-data:/data

  minio-init:
    image: minio/mc:latest
    restart: "no"
    depends_on:
      - minio
    entrypoint:
      - /bin/sh
      - -c
      - |
        until mc alias set local http://minio:9000 minioadmin minioadmin; do sleep 1; done
        mc mb --ignore-existing local/helix-db

  helix:
    image: ghcr.io/helixdb/enterprise-dev:latest
    restart: unless-stopped
    depends_on:
      minio-init:
        condition: service_completed_successfully
    ports:
      - "6969:8080"
    environment:
      PATH_TO_QUERIES: /workspace/queries.json
      S3_BUCKET: helix-db
      S3_REGION: us-east-1
      DB_PATH: db/
      AWS_ACCESS_KEY_ID: minioadmin
      AWS_SECRET_ACCESS_KEY: minioadmin
      AWS_ENDPOINT: http://minio:9000
      AWS_ALLOW_HTTP: "true"
    volumes:
      - ./queries.json:/workspace/queries.json:ro

volumes:
  minio-data:
```

### Environment variables

| Variable                | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `S3_BUCKET`             | Bucket the database reads and writes to.                                 |
| `S3_REGION`             | Region passed to the S3 client. Any value works against MinIO.           |
| `DB_PATH`               | Prefix inside the bucket where the database keeps its files.             |
| `AWS_ACCESS_KEY_ID`     | Access key for the object store.                                         |
| `AWS_SECRET_ACCESS_KEY` | Secret key for the object store.                                         |
| `AWS_ENDPOINT`          | Custom endpoint URL — required for MinIO and other non-AWS S3 providers. |
| `AWS_ALLOW_HTTP`        | Set to `true` when the endpoint is plain HTTP (e.g. local MinIO).        |

The same variables work against any S3-compatible store — MinIO, LocalStack, Ceph RGW, or AWS S3
itself. Drop `AWS_ENDPOINT` and `AWS_ALLOW_HTTP` to talk to real AWS S3.

## Next Steps

<CardGroup cols={2}>
  <Card title="Working with Helix Cloud" icon="rocket" href="/database/working-with-enterprise">
    Authoring `queries.json` and the runtime workflow.
  </Card>

  <Card title="Querying" icon="magnifying-glass" href="/database/querying">
    Traversal DSL, dynamic queries, and transactions.
  </Card>

  <Card title="CLI Getting Started" icon="terminal" href="/cli/getting-started">
    Install the Helix CLI, scaffold a project, and send your first query.
  </Card>

  <Card title="Local Workflow" icon="code" href="/cli/workflows/local">
    Iterate on dynamic JSON queries against a local v2 instance.
  </Card>
</CardGroup>