HelixDB Docs

Guide

The ghcr.io/helixdb/helixdb:v0.0.5 image runs the standalone HelixDB server. It supports Linux on amd64 and arm64. It exposes the same operation-tree request contract used by Helix Cloud at POST /v2/query; gateway-only Cloud features are not included.

Choose storage

Mode	Persistence	Use when
Memory	Lost when the server stops	Fast local iteration and tests
Native directory (`HELIX_DATA_DIR`)	Preserved in a mounted volume or directory	Running the image directly with local persistence
CLI disk (`--disk`)	Preserved in a CLI-managed MinIO volume	Testing restart and persistence through the CLI
Existing S3-compatible store	Owned outside Helix	Reusing MinIO, LocalStack, Ceph, or AWS S3

Start with the CLI

macOS and Linux:

curl -sSL "https://install.helix-db.com" | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex

Then, in your shell:

mkdir my-helix-app
cd my-helix-app
helix init local --name dev # add --disk to make persistence the project default
helix start dev             # add --disk to persist this instance

The standalone server accepts queries at http://localhost:6969/v2/query. For an existing project, set tag = "v0.0.5" in its [local.dev] block in helix.toml before starting it. An explicitly saved tag overrides the CLI default.

helix query dev \
  -e 'readBatch().varAs("count", g().nWithLabel("User").count()).returning(["count"])'

The default mode is in-memory. helix stop and helix restart discard its data.

Use an existing object store

Place credentials in a project-root .env file or export them:

.env

AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
# AWS_SESSION_TOKEN=your-session-token

Do not commit .env.

MinIO
AWS S3

helix start dev \
  --storage-uri s3://helix-db/my-app \
  --s3-region us-east-1 \
  --s3-endpoint-url https://minio.example.com \
  --persist

Add --s3-allow-http only for a plain HTTP endpoint.

helix start dev \
  --storage-uri s3://my-bucket/my-app \
  --s3-region eu-west-2 \
  --persist

--persist stores the resolved configuration in helix.toml. Helix does not delete externally managed object-store data during stop, restart, or prune.

Run the image directly

Memory mode is selected by leaving both HELIX_DATA_DIR and S3_BUCKET unset:

docker run --rm --name helixdb \
  -p 6969:8080 \
  ghcr.io/helixdb/helixdb:v0.0.5

The standalone server exposes liveness and readiness checks:

curl -fsS http://127.0.0.1:6969/healthz
curl -fsS http://127.0.0.1:6969/readyz

Do not set S3_BUCKET=IN_MEMORY. Every defined S3_BUCKET value selects S3-compatible storage and is interpreted as a real bucket name. Setting HELIX_DATA_DIR and S3_BUCKET together causes startup to fail.

Run with native directory persistence

Set HELIX_DATA_DIR to a mounted directory inside the container:

docker volume create helixdb-data
docker run --rm --name helixdb \
  -p 6969:8080 \
  -e HELIX_DATA_DIR=/var/lib/helix \
  --mount type=volume,source=helixdb-data,target=/var/lib/helix \
  ghcr.io/helixdb/helixdb:v0.0.5

Stop the server with docker stop helixdb. Starting a new container with the same volume preserves its database. Removing the volume deletes the data. This mode does not require MinIO; the CLI’s --disk mode still uses MinIO. The image runs as user and group 65532:65532. Its /var/lib/helix directory is prepared for that user, including when initializing a new Docker named volume. If you use a bind mount or an existing volume, its directory must be writable by that user.

Run with MinIO persistence

This Compose configuration creates a bucket and stores HelixDB objects in the minio-data volume:

docker-compose.yaml

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/helixdb:v0.0.5
    restart: unless-stopped
    depends_on:
      minio-init:
        condition: service_completed_successfully
    ports:
      - "6969:8080"
    environment:
      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:
  minio-data:

Run docker compose down to replace the HelixDB container without deleting the MinIO data. docker compose down -v deletes the persisted database. For an existing object store, use the same HelixDB environment variables and omit the MinIO services. For AWS S3, omit the endpoint and HTTP override.

Variable	Purpose
`HELIX_DATA_DIR`	Selects native disk storage and names its container directory; mount a volume there for persistence
`S3_BUCKET`	Selects S3 mode and names the object-store bucket; omit both storage selectors for memory mode
`S3_REGION`	Region supplied to the S3 client; falls back to `AWS_REGION`, then `AWS_DEFAULT_REGION`, then `us-east-1`
`DB_PATH`	Logical database prefix inside the selected store, including under `HELIX_DATA_DIR`; defaults to `db/`
`AWS_ACCESS_KEY_ID`	Access key
`AWS_SECRET_ACCESS_KEY`	Secret key
`AWS_SESSION_TOKEN`	Optional temporary-credential token
`AWS_ENDPOINT` or `AWS_ENDPOINT_URL_S3`	Non-AWS S3 endpoint
`AWS_ALLOW_HTTP`	Set to `true` or `1` to permit an HTTP endpoint

The endpoint must be reachable from inside the container; container localhost is not the host machine. DB_PATH is a logical prefix, not the storage directory. To use native directory persistence, set HELIX_DATA_DIR and mount the directory there.

Stop or inspect

helix status
helix logs dev
helix stop dev

Next steps

Get Started

Create and traverse a small graph.

Embedded database

Open HelixDB directly inside your process.

Helix Cloud

Move the same application requests to a managed cluster.

Local CLI workflow

Manage instances and raw requests.

Start Here

Core Concepts

Query Guides

Local server

Choose storage

Start with the CLI

Use an existing object store

Run the image directly

Run with native directory persistence

Run with MinIO persistence

Stop or inspect

Next steps

Get Started

Embedded database

Helix Cloud

Local CLI workflow

​Choose storage

​Start with the CLI

​Use an existing object store

​Run the image directly

​Run with native directory persistence

​Run with MinIO persistence

​Stop or inspect

​Next steps

Get Started

Embedded database

Helix Cloud

Local CLI workflow

Choose storage

Start with the CLI

Use an existing object store

Run the image directly

Run with native directory persistence

Run with MinIO persistence

Stop or inspect

Next steps