Configuration

The daemon reads one TOML file, /etc/voxeltron/voxeltron.toml. The file is rendered from the binary, so the defaults and the accepted keys match the version you run.

Render a complete file

voxeltrond config render prints a complete, validated configuration for a runtime. The installer uses this command to create the first file:

$ voxeltrond config render --runtime docker

Write it to a file, or compare it with the active file when a release adds keys:

$ sudo voxeltrond config render --runtime docker > /etc/voxeltron/voxeltron.toml.new
$ sudo diff -u /etc/voxeltron/voxeltron.toml /etc/voxeltron/voxeltron.toml.new

--profile default is the normal profile. --profile sovereign is an offline profile that does not execute AI actions. Most installs use the default.

Validate a file

$ sudo voxeltrond config validate
$ sudo voxeltrond config validate --json

Validation does not start the daemon. The daemon also validates the file at startup and exits instead of running with an invalid configuration. Use --config to point any command at another file.

Top-level keys

KeyDefaultMeaning
profile"default"default or sovereign.
grpc_auth_enabledtrueRequire a token on non-health gRPC calls.
grpc_allow_insecure_nonloopbackfalseRefuse plaintext gRPC on a public listener.
auto_restore_on_boottrueReconcile managed containers after a daemon restart.
build_cache_dir"/var/lib/voxeltron/build-cache"Build cache used by source deploys.
datasources[]Optional external data sources.

[grpc]

[grpc]
listen_addr = "127.0.0.1:50051"

[grpc.tls]
enabled = false

[grpc.auth]
max_token_ttl_secs = 86400
compat_unscoped_authz = false

The listener defaults to loopback. Reach it through an SSH tunnel, or enable TLS and publish it deliberately. grpc.auth.keys holds the signing-key ring; manage keys withvoxeltrond auth and voxeltrond token rather than editing them by hand.

compat_unscoped_authz exists for legacy single-operator installs. It disables project authorization for every database call, so leave it false.

[api] and [rest]

[api]
listen_addr = "127.0.0.1:7103"

[rest]
enabled = false
listen_addr = "127.0.0.1:8080"
allowed_ips = []

The REST API is off by default. Keep it off unless a client needs it.

[control_plane]

[control_plane]
metrics_public = false

/metrics on the API listener needs an API bearer token. Mutating node routes always need that token, including on loopback. Set metrics_public = true only when the listener is bound to loopback or sits behind a firewall you control. Remote callers of /health always get {"status":"ok"} and nothing else.

[proxy] and [proxy.acme]

[proxy]
http_port = 80
https_port = 443
caddy_admin_url = "http://127.0.0.1:2019"

[proxy.acme]
email = "[email protected]"

Caddy listens on the proxy ports. The ACME settings are described indomains and TLS.

[database]

[database]
path = "/var/lib/voxeltron/voxeltron.db"

This is the daemon's own state database. It is not a user database.

[deploy]

[deploy]
source_root = "/var/lib/voxeltron/apps"

source_root is the daemon-owned directory for uploaded source archives. It defaults to /var/lib/voxeltron/apps. The path must be absolute and must not contain ... At startup the daemon creates a missing directory with mode 0750 and leaves the mode of an existing directory unchanged. The daemon user must be able to create files in the directory. Set this key to a directory owned by the daemon user when the daemon does not run as root.

[build]

[build]
max_disk = "10GiB"
network = "bridge"

Voxeltron rejects a Dockerfile build when the source context plus the resulting image exceedsmax_disk. network is bridge or none. Bridge networking does not block a cloud metadata service at 169.254.169.254; use a host firewall rule for that address or set network = "none".

Voxeltron does not configure BuildKit memory or CPU limits. As an operator option, create a dedicated builder withdocker buildx create --name voxeltron-builder --driver docker-container --driver-opt memory=2g --driver-opt cpu-quota=200000, then select it with docker buildx use voxeltron-builder.

[container_runtime], [docker] and [runtime]

[container_runtime]
runtime = "auto"
docker_socket_path = "/var/run/docker.sock"
timeout_secs = 30

[docker]
socket_path = "/var/run/docker.sock"
timeout_secs = 30

[runtime]
policy = "docker"
bridge_name = "vxbr0"

The Community installer writes policy = "docker". Firecracker is a preview runtime and is not enabled by the installer.

[lifecycle]

[lifecycle]
health_interval_secs = 15

The lifecycle controller checks component health every 15 seconds by default.health_interval_secs accepts values from 5 to 3600 seconds. The first restart after an unexpected exit sends a crash_detected alert through the configured monitoring channels. Repeated crashes in the same incident send only the existing quarantine alert. A component must stay healthy for one full health interval before a new incident can send another detected alert. Restart limits and backoff are unchanged. Longer intervals delay crash detection.

[plugins]

[plugins]
enabled = false

The plugin host is disabled and the Community v0.1 build does not register the plugin service. See plugins.

[secrets] and [security]

[secrets]
provider = "local"

[security]
allowed_local_path_roots = []
operator_admins = []
compose_env_allowlist = []
compose_require_digest_pinned_images = false

local stores encrypted secrets with the daemon. Keepallowed_local_path_roots narrow if you enable local path deploys.

[backup]

[backup]
enabled = false
schedule = ""
retention_count = 0
encryption_enabled = false

[backup.target]
type = "local"
path = "/var/lib/voxeltron/backups"

[backup.target] is a tagged value: local, s3,r2 or gcs. Database backup uploads in v0.1 use the local and S3 paths. See backups.

[logging], [audit] and [notify]

[logging]
level = "info"
json = false

[audit]
enabled = true
retention_days = 90
backpressure = "drop"

[notify]
channels = []

notify.channels is empty by default. An AI tool that needs a channel reports an error until one is configured. See AI preview.

[ai]

[ai]
max_permission = "read"
allow_scheduled_actions = false

The operations agent is off until a provider is configured. Memory search in v0.1 uses keyword matching. If max_permission is above read, stored scheduled tool actions stay skipped until allow_scheduled_actions = true as well.

[ssh] and [tunnel.cloudflare]

[ssh]
enabled = false
listen_addr = "0.0.0.0:2222"

[tunnel.cloudflare]
enabled = false

Both are off by default. The SSH server serves the TUI over SSH when enabled. The Cloudflare tunnel is used only for routes that explicitly select the Cloudflare edge.

Example: a small production file

profile = "default"
grpc_auth_enabled = true

[grpc]
listen_addr = "127.0.0.1:50051"

[proxy.acme]
email = "[email protected]"

[runtime]
policy = "docker"

[plugins]
enabled = false

[backup.target]
type = "local"
path = "/var/lib/voxeltron/backups"

Render the file first and change only the keys you need. Several sections are required, so a partial hand-written file is rejected. A rendered file shows every default for the version you are running.