> ## 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 server
> Start HelixDB locally with ephemeral memory or persistent object storage
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
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
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`.
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
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:
```dotenv .env theme={"languages":{"custom":["languages/helixql.json"]}}
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
# AWS_SESSION_TOKEN=your-session-token
```
Do not commit `.env`.
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
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.
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
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:
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
docker run --rm --name helixdb \
-p 6969:8080 \
ghcr.io/helixdb/helixdb:v0.0.3
```
The standalone server exposes liveness and readiness checks:
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
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:
```yaml docker-compose.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/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
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
helix status
helix logs dev
helix stop dev
```
## Next steps
Create and traverse a small graph.
Open HelixDB directly inside your process.
Move the same application requests to a managed cluster.
Manage instances and raw requests.