HelixDB Docs

Guide

The ghcr.io/helixdb/helixdb:v0.0.3 image runs the standalone HelixDB server. 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 container is replaced	Fast local iteration and tests
Disk (`--disk`)	Preserved in a MinIO volume	Testing restart and persistence behavior
Existing S3-compatible store	Owned outside Helix	Reusing MinIO, LocalStack, Ceph, or AWS S3

Start with the CLI

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

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 gateway listens at http://localhost:6969/v2/query.

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 S3_BUCKET unset:

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

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.

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.3
    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
`S3_BUCKET`	Selects S3 mode and names the object-store bucket; omit it 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 object store; 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 not a host filesystem path, and mounting a volume at that path does not enable native directory persistence. The standalone image does not expose native directory storage; the CLI’s --disk mode uses MinIO.

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 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 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 MinIO persistence

Stop or inspect

Next steps