HelixDB Docs

For the complete documentation index optimized for AI agents, see llms.txt.

This page documents the configuration files the Helix CLI reads and writes:

helix.toml — per-project configuration in your project root.
~/.helix/config — user-global state, currently the selected workspace.
~/.helix/credentials — Helix Cloud credentials written by helix auth login.

`helix.toml`

helix init creates helix.toml in your project root. Everything the CLI knows about your project lives here.

[project]
name = "my-helix-app"

[local.dev]
port = 6969
image = "ghcr.io/helixdb/enterprise-dev"
tag = "latest"
# Optional; defaults to in-memory when omitted.
# storage = "disk"

[enterprise.production]
cluster_id = "ec_01HX..."
gateway_url = "https://gateway.example.com"

At least one [local.*] or [enterprise.*] instance is required. The CLI rejects an empty helix.toml.

`[project]`

Key	Type	Required	Default	Description
`name`	String	Yes	—	Project name. Used in the container name pattern `helix-<project>-<instance>`.
`id`	String	No	—	Linked Helix Cloud project ID. Set by `helix project switch`.
`workspace_id`	String	No	—	Linked Helix Cloud workspace ID. Set by `helix project switch`.
`container_runtime`	`docker` \| `podman`	No	`docker`	Runtime used to manage local containers.

`[local.<instance>]`

One block per local instance. The instance name is the table key (e.g. [local.dev]).

Key	Type	Default	Description
`port`	Number	`6969`	Host port published to container port `8080`.
`image`	String	`ghcr.io/helixdb/enterprise-dev`	Container image used by `helix start`.
`tag`	String	`latest`	Image tag.
`storage`	`memory` \| `disk`	`memory`	Local storage mode. `disk` uses a CLI-managed MinIO container and persistent volume.

You can define as many local instances as you want, each on a different port:

[local.dev]
port = 6969

[local.staging]
port = 9090
storage = "disk"

You can also use helix start <instance> --disk as a one-off disk-mode run without changing helix.toml.

`[enterprise.<instance>]`

One block per Helix Cloud instance. Most fields here are populated automatically by helix sync.

Key	Type	Required	Default	Description
`cluster_id`	String	Yes	—	Helix Cloud cluster ID. List clusters with `helix cluster list`.
`workspace_id`	String	No	—	Workspace the cluster belongs to.
`project_id`	String	No	—	Linked project ID.
`gateway_url`	URL	No (required at query time)	—	Runtime gateway base URL. Populated by `helix sync` when available.
`query_auth_header`	String	No	`Authorization`	HTTP header name used for query auth.
`query_auth_env`	String	No	`HELIX_API_KEY`	Environment variable read by `helix query` for the auth header value.
`availability_mode`	String	No	—	Cluster availability mode, returned by `helix sync`.
`gateway_node_type`	String	No	—	Gateway node type, returned by `helix sync`.
`db_node_type`	String	No	—	DB node type, returned by `helix sync`.

If gateway_url is missing, helix query <instance> fails with:

Enterprise gateway URL is not configured for '<instance>'.
Run 'helix sync <instance>' or set gateway_url in helix.toml.

`~/.helix/config`

User-global configuration written by helix workspace switch.

workspace_id = "ws_01HX..."

This file is independent of any project directory and applies to every Helix Cloud command you run.

`~/.helix/credentials`

Written by helix auth login. Plain key=value format:

helix_user_id=usr_01HX...
helix_user_key=hlxk_...

Remove with helix auth logout. Never commit this file.

Environment variables

Variable	Used by	Description
`HELIX_API_KEY` (default)	`helix query`	Per-cluster Helix Cloud API key sent in the configured auth header. The variable name is configurable per-instance via `query_auth_env`.

Troubleshooting

Port conflict on helix start — change the port in [local.<instance>] port, or pass helix start <instance> --port <port> to override for a single run.
Missing instances — helix.toml has no [local.*] or [enterprise.*] blocks. Add one with helix add.
Authentication required — run helix auth login for Helix Cloud commands.
gateway_url is still missing after helix sync — the cloud-side configuration has not been published yet. Re-run helix sync later, or set gateway_url manually under [enterprise.<instance>].

Configuration Guide

`helix.toml`

`[project]`

`[local.<instance>]`

`[enterprise.<instance>]`

`~/.helix/config`

`~/.helix/credentials`

Environment variables

Troubleshooting

Next Steps

Local workflow

Troubleshooting

​helix.toml

​[project]

​[local.<instance>]

​[enterprise.<instance>]

​~/.helix/config

​~/.helix/credentials

​Environment variables

​Troubleshooting

​Next Steps

Local workflow

Troubleshooting

`helix.toml`

`[project]`

`[local.<instance>]`

`[enterprise.<instance>]`

`~/.helix/config`

`~/.helix/credentials`

Environment variables

Troubleshooting

Next Steps