Configuration

The Voxeltron daemon is configured via a single TOML file. Every setting has a sensible default, so you only need to specify what you want to change.

Overview

The daemon reads its configuration from /etc/voxeltron/config.toml at startup. You can override the path with the --config flag:

voxeltrond --config /path/to/config.toml

Any setting in the config file can also be overridden via environment variables using the VOXELTRON_ prefix. See Environment Variable Overrides below.

Core Settings

Top-level keys that control how the daemon binds and stores data.

bind_address = "0.0.0.0"
grpc_port    = 7443
data_dir     = "/var/lib/voxeltron"
log_level    = "info"

Key	Type	Default	Description
`bind_address`	string	`"0.0.0.0"`	IP address the gRPC server listens on.
`grpc_port`	integer	`7443`	Port for the gRPC API. The TUI connects here.
`data_dir`	string	`"/var/lib/voxeltron"`	Root directory for application data, build cache, and database volumes.
`log_level`	string	`"info"`	Log verbosity: `trace`, `debug`, `info`, `warn`, `error`.

[tls]

Controls automatic TLS certificate provisioning via ACME (Let's Encrypt).

[tls]
acme_email     = "ops@example.com"
acme_directory = "https://acme-v02.api.letsencrypt.org/directory"

ACME (Production)

Set acme_email to a valid address. Certificates are automatically requested and renewed via Let's Encrypt.

Self-Signed Fallback

If acme_email is omitted, the daemon generates a self-signed certificate on first startup. Useful for local development and air-gapped environments.

Use the Let's Encrypt staging directory during testing to avoid rate limits: https://acme-staging-v02.api.letsencrypt.org/directory

[database]

Docker images used when provisioning managed database instances.

[database]
postgres_image = "postgres:16-alpine"
mysql_image    = "mysql:8.4"
redis_image    = "redis:7-alpine"
mongo_image    = "mongo:7"

Override these to pin a specific version or use a private registry mirror. The daemon pulls the image on first database creation if it is not already present locally.

[backup]

Automated backup schedule and storage target.

[backup]
schedule = "0 3 * * *"   # cron expression — daily at 03:00
target   = "local"       # "local" or "s3"

[backup.s3]
bucket          = "my-voxeltron-backups"
region          = "us-east-1"
endpoint        = ""                        # custom S3-compatible endpoint (optional)
access_key_id   = ""
secret_access_key = ""

Key	Default	Description
`schedule`	`"0 3 * * *"`	Cron expression for backup frequency.
`target`	`"local"`	Storage backend: `local` (writes to `data_dir/backups/`) or `s3`.
`s3.bucket`	—	S3 bucket name. Required when `target = "s3"`.
`s3.region`	`"us-east-1"`	AWS region or S3-compatible region identifier.
`s3.endpoint`	—	Custom endpoint for S3-compatible storage (MinIO, R2, etc.).
`s3.access_key_id`	—	S3 access key.
`s3.secret_access_key`	—	S3 secret key. Prefer `VOXELTRON_BACKUP_S3_SECRET_ACCESS_KEY` env var.

For S3 credentials, prefer environment variable overrides over storing secrets in the config file.

[secrets]

Controls how application secrets (env vars marked as sensitive) are stored and retrieved.

[secrets]
provider = "local"   # "local", "openbao", or "infisical"

[secrets.openbao]
address    = "https://vault.internal:8200"
mount_path = "secret"
role_id    = ""
secret_id  = ""

Local

Secrets are encrypted at rest in data_dir/secrets/. Good for single-node setups.

OpenBao / Vault

Connects to an OpenBao (or HashiCorp Vault) instance via AppRole auth. Recommended for production clusters.

Infisical

Integrates with Infisical for team-based secrets management. Configure via environment variables.

[cluster]

Multi-node cluster settings. Omit this section entirely for single-server deployments.

[cluster]
node_id             = "node-1"
seeds               = ["10.0.0.2:7946", "10.0.0.3:7946"]
cloud_discovery_url = ""

Key	Default	Description
`node_id`	hostname	Unique identifier for this node in the cluster. Defaults to the system hostname.
`seeds`	`[]`	List of `host:port` addresses of existing cluster members to join on startup.
`cloud_discovery_url`	—	URL for cloud-based node discovery (Voxeltron Cloud managed clusters only).

[ai]

Configure the AI assistant that powers natural-language DevOps commands.

[ai]
provider         = "anthropic"   # "anthropic" or "openai"
model            = "claude-sonnet-4-20250514"
api_key_env      = "ANTHROPIC_API_KEY"
permission_level = "suggest"     # "suggest", "confirm", or "auto"

Key	Default	Description
`provider`	`"anthropic"`	AI backend: `anthropic` or `openai`.
`model`	`"claude-sonnet-4-20250514"`	Model identifier. Must be supported by the chosen provider.
`api_key_env`	`"ANTHROPIC_API_KEY"`	Name of the environment variable holding the API key. The key itself is never stored in config.
`permission_level`	`"suggest"`	`suggest` — AI proposes commands, you approve. `confirm` — AI executes after explicit confirmation. `auto` — AI executes non-destructive commands automatically.

The AI API key is read from the environment variable named in api_key_env, not from the config file. This ensures secrets never touch disk in plain text.

Full Example

A complete config.toml with all sections:

# /etc/voxeltron/config.toml

bind_address = "0.0.0.0"
grpc_port    = 7443
data_dir     = "/var/lib/voxeltron"
log_level    = "info"

[tls]
acme_email     = "ops@example.com"
acme_directory = "https://acme-v02.api.letsencrypt.org/directory"

[database]
postgres_image = "postgres:16-alpine"
mysql_image    = "mysql:8.4"
redis_image    = "redis:7-alpine"
mongo_image    = "mongo:7"

[backup]
schedule = "0 3 * * *"
target   = "s3"

[backup.s3]
bucket          = "my-voxeltron-backups"
region          = "us-east-1"
endpoint        = ""
access_key_id   = "AKIA..."
secret_access_key = ""   # prefer env var

[secrets]
provider = "openbao"

[secrets.openbao]
address    = "https://vault.internal:8200"
mount_path = "secret"
role_id    = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
secret_id  = ""   # prefer env var

[cluster]
node_id = "node-1"
seeds   = ["10.0.0.2:7946", "10.0.0.3:7946"]

[ai]
provider         = "anthropic"
model            = "claude-sonnet-4-20250514"
api_key_env      = "ANTHROPIC_API_KEY"
permission_level = "confirm"

Environment Variable Overrides

Every config key can be overridden via an environment variable with the VOXELTRON_ prefix. Nested keys use underscores to replace dots and section separators.

# Core settings
export VOXELTRON_BIND_ADDRESS="127.0.0.1"
export VOXELTRON_GRPC_PORT="8443"
export VOXELTRON_LOG_LEVEL="debug"

# Nested sections
export VOXELTRON_TLS_ACME_EMAIL="ops@example.com"
export VOXELTRON_BACKUP_S3_BUCKET="prod-backups"
export VOXELTRON_BACKUP_S3_SECRET_ACCESS_KEY="wJalr..."
export VOXELTRON_SECRETS_OPENBAO_SECRET_ID="xxxxxxxx"
export VOXELTRON_AI_PROVIDER="openai"

Environment variables take precedence over values in config.toml. This makes it easy to inject secrets via your init system, container orchestrator, or CI pipeline without modifying the config file.

Precedence order (highest to lowest):

Environment variables (VOXELTRON_*)
Config file (/etc/voxeltron/config.toml)
Built-in defaults