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 dockerWrite 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 --jsonValidation 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
| Key | Default | Meaning |
|---|---|---|
profile | "default" | default or sovereign. |
grpc_auth_enabled | true | Require a token on non-health gRPC calls. |
grpc_allow_insecure_nonloopback | false | Refuse plaintext gRPC on a public listener. |
auto_restore_on_boot | true | Reconcile 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 = falseThe 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 = "ops@example.com"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 = 15The 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 = falseThe 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 = falselocal 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 = falseThe 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 = falseBoth 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 = "ops@example.com"
[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.