Repository navigation
Releases
v0.1.5
0.1.5 adds vxl mcp, so coding agents can plan and apply deploys with a digest check, and makes self-healing proposals and quarantines survive a daemon restart. From this release Voxeltron is free to use and distributed as signed binaries.
Changed
- Voxeltron is now free to use and distributed as signed binaries. The source is no longer public. 0.1.4 and earlier remain available under Apache-2.0.
- 0.1.4 servers upgrade by rerunning the installer from voxeltron.dev.
Added
vxl mcp, a stdio MCP server so coding agents can operate Voxeltron. It offers read-only tools (status, apps, logs, deployments, audit and more) by default. With--allow-apply, an agent can plan a deploy fromvoxeltron.yamland then apply exactly that plan:planreturns an id and a digest, andapplyrunsvxl up --expect-digest, which refuses if the manifest or sources changed since the plan. Apply also needs the app name as confirmation. Plans expire after 30 minutes.vxl up --expect-digest DIGESTrefuses to deploy unless the computed plan has that digest.- The audit log records the calling client's user agent on admitted changes, so changes made through
vxl mcpshow which agent made them. [ai] web_tools = falseturns off the operations agent'sweb_searchandhttp_clienttools.[self_healing] diagnosis_timeout_secs(default 120, from 30 to 3600): how long the AI diagnosis attached to a proposal may run.
Security
- A caller without permission on a project gets
PERMISSION_DENIEDfromSwitchDeploymentTraffic, whatever it asked for. Before, a gradual switch request was refused as unimplemented before the permission check. vxl mcpchecks that a manifest's build path stays inside the MCP root on the manifest it actually archived, so a manifest rewritten between the check and the plan cannot plan, or apply through a matching digest, a build from outside the root.
Fixed
- Self-healing proposals and quarantines survive a daemon restart. Before, both were kept only in memory: a restart dropped a proposal waiting for an operator, and the quarantined app was started again, by the boot-time restore of stopped apps and by a fresh restart budget, so it crashed and was proposed again. Now
vxl approvals listshows the same proposal after a restart, approving it runs the rollback, records the approver and runs the recovery check, and expiry still counts from the original request. The daemon database gains two tables,runbook_pending_approvalsandlifecycle_quarantined_deployments, created at startup; no action is needed to upgrade. If the daemon stopped after quarantining an app but before saving its proposal, the restarted daemon raisescrash_quarantineagain and proposes a fresh rollback, so no app stays stopped unnoticed; a saved proposal whose runbook step changed is closed as expired and replaced the same way. A decision on a saved proposal is recorded in the same transaction that removes it, so a proposal is never decided or run twice, and the resumed run gets its original parameters. Only proposals the daemon made itself are kept: a runbook an operator started is still dropped by a restart. With self-healing off, the next start releases saved quarantines and closes saved proposals as timed out. A proposal still pending when you upgrade from an earlier release was never saved; its quarantine was not saved either, so that app is handled as before. - Managed databases start on daemon boot before application restoration, with bounded engine readiness checks and alerts on failure. Database list/get report observed container state, and lifecycle supervision restarts stopped databases within the normal restart budget. Reboot battle tests now verify database containers and pre-reboot Postgres/Redis data.
- A rollback no longer restores the same release it is rolling back. Restarts can relaunch a crashing release as a new deployment, and rolling back to that copy changed nothing. When the previous deployment runs the same release (same image and tag, command, arguments, environment, resources, secret files, writable paths, egress and kernel enforcement),
vxl rollbackrefuses with "no different release to roll back to", and self-healing raisesremediation_no_targetinstead of proposing a rollback. A change to configuration alone, such as the memory limit, still rolls back. - A new deployment of a quarantined app, whether a redeploy or a rollback, gets a fresh restart budget and can raise a new proposal. Before, the quarantine stayed with the app name, so a redeploy under the same name was never restarted or escalated again ("Lifecycle remediation requires operator attention").
- The self-healing diagnosis no longer ends with the internal
[goal-verification] satisfied=... gaps=[...]text or starts withFINAL:. - A
query_logsfailure during a diagnosis now logs the reason. vxl statusandvxl status --jsongive the publichttps://URL, or none, as the app'surl. Before, an app with no public domain showed the container's internal address, which resolves only inside the server's Docker network. That address is noworigin_url.- Under
--json, SSH host key prompts and warnings go to stderr, so stdout is always exactly one JSON document. vxl ps --helpandvxl ls --helpno longer advertise an[app]argument the commands reject.- The built-in runbooks run as written.
- A partial
[ai]table loads, with the default agent name and prompt for any keys it leaves out. - The operations agent lists only tools that have a backend to read from.
- The TUI AI panel shows the model the server actually uses, and offers only commands that work.
vxl mcp'saudit_exportreturns the newest events.vxl deploy --strategyandvxl-admin create-deployment --strategyaccept onlyrollingandrecreate. The daemon's CreateDeployment returnsUNIMPLEMENTEDfor canary andINVALID_ARGUMENTfor an unknown strategy value, and SwitchDeploymentTraffic returnsUNIMPLEMENTEDfor gradual switching, instead of silently running the standard deploy path.- Self-healing proposals waiting for an operator, and quarantined apps, survive a daemon restart or upgrade. After a restart,
vxl approvals listshows the same proposal under the same id, and the quarantined app stays stopped. Expiry still counts from the original request.
Upgrade notes
- Upgrade a 0.1.4 server by rerunning the installer from voxeltron.dev. The installer verifies
SHA256SUMS.minisigwith the release key before installing anything. - The daemon database gains two tables,
runbook_pending_approvalsandlifecycle_quarantined_deployments, created at startup. No action is needed. - The guided move of
vxl bootstrapservers from root to thevoxeltronuser, planned for 0.1.5 in the 0.1.4 notes, is not in this release. Those servers keep running the daemon as root after upgrading. - Each archive's
LICENSEis now the Voxeltron free binary licence, andLICENSE.busyboxis new.
Third-party notice. The Linux voxeltrond and vxl-admin include BusyBox, under the GNU General Public License, version 2 only. Its complete source is attached to this release (busybox_1.36.1-6ubuntu3.1.dsc and its files, with BUSYBOX-SOURCE-README.md); the licence and written offer are in NOTICE-busybox.md and in each archive's THIRD-PARTY-NOTICES.md.
Voxeltron 0.1.4
0.1.4 is a security release. It fixes checks that could pass when they should
fail, tightens what the assistant and self-healing may do, stops the
deployment scan from printing secrets, and fixes the findings of an
independent security review.
Security
vxl-admin doctor auditjudges HARDEN-SEC-001 by the running daemon's secrets passphrase. Before, it readVOXELTRON_SECRETS_PASSPHRASEfrom the shell that ran the audit, so it passed from any ordinary shell even when the daemon used the debug-default passphrase. The daemon now writessecret-posture.jsonbeside its database at startup (mode 0600, yes or no facts and a length only, never a secret), and the audit reads it when run as root. When it cannot get the daemon's answer, SEC-001 reportsunknownwith the reason, and--fail-on highcounts that as a failure. ASECRET_KEY_BASEis checked only when set: shorter than 64 bytes fails.- The assistant's
exec_shell,apply_patch,write_fileandedit_filetools need the Mutate tier. Before, they were Safe, so any Safe-tier path could write files and run commands insideallowed_roots.write_fileandedit_filestill never write outsideallowed_roots, including through a symlink, and self-healing never gets these tools. vxl scanandvxl deploy --preflightname a suspected secret in a Dockerfile by its variable name and line only. Before, the finding included the whole line, value included, so the secret reached terminal output, JSON and CI logs.ENVandARGlines are both checked, and names match whole words, soKEYCLOAK_URLis no longer a secret.- Every decision on a self-healing proposal is recorded as a
runbook.approvalaudit event, whichever command made it, and an undecided proposal expires afterapproval_timeout_secs(24 hours). - A compose service can mount only volumes, and join only networks, that its own compose file declares. Before, a service could name another project's volume or network by its runtime name and admission let it through.
vxl bootstrapinstalls the daemon as thevoxeltronuser with the same systemd sandbox as the installer. Before, it ran as root with no sandbox. Docker is installed from Docker's apt repository with a pinned signing key instead ofcurl https://get.docker.com | sh.- With
ai.enable_system_tools = true, the system tools needai.system_tool_rootsat every tier, the read tier included, anddocker:<container>targets only containers of a Voxeltron deployment. Before, at the read tier with no roots they could read any host file and run in any container. - The assistant's anomaly diagnosis, verifier and self-healing get only a fixed list of tools that read deployment state, plus the actions the built-in runbooks need. Tools that reach the internet or run commands are never available without a person in the conversation.
- The assistant's git tools read a repository only when every setting in its own config is on a short list of settings that cannot run programs; filters, diff and merge drivers, SSH and editor commands, credential helpers, includes and fsmonitor are refused. Git runs with system and global config, hooks, attributes files, signing programs and all network transports turned off.
db_querystops a query after 10 seconds.- A project Admin can no longer change or remove an Owner. Only an Owner can, and never the last one.
- Viewers see secret names and the redacted database connection string, never secret values or database passwords.
vxl-admin backup createnever follows symlinks or hard links to files owned by someone else, and refuses a file or directory swapped while it runs. Backup files are created 0600 and directories 0700, and a database dump larger than 4 GiB (VOXELTRON_MAX_BACKUP_DUMP_BYTES) fails instead of filling memory.- Docker builds stop after
build.timeout_secs(30 minutes by default). Health.Watchserves at most 64 streams at once.
Upgrade notes
- A compose file that mounts a volume or joins a network it does not declare under top-level
volumesornetworksis now rejected withUNDECLARED_VOLUMEorUNDECLARED_NETWORK. Declare it, then deploy again. - A daemon with
ai.enable_system_tools = trueand an emptyai.system_tool_rootsno longer starts. List the directories the tools may use, or turn the tools off. - Servers set up with an earlier
vxl bootstrapkeep running the daemon as root aftervxl daemon upgrade. A guided move to thevoxeltronuser is planned for 0.1.5. - Viewers (and Responders) can no longer read secret values or managed database passwords.
GetSecretandGetConnectionStringwithredacted = falsenow need the Admin or Owner role, the same roles that write secrets. Viewers still list secret names and get the redacted connection string. Give a person who needs values the Admin role.
Fixed
vxl scanflags end-of-life base images (such as Node 14 and 16, Python 3.7 and 3.8, Debian stretch and buster, Ubuntu 18.04) as High. Before, it only looked at plainubuntuanddebianimages, sonode:14-busterpassed.- The suggested
HEALTHCHECKuses the app's port and thehealthpath from its manifest instead of a fixed port 8080. - Built-in runbooks whose tools are not available, such as
microvm-cold-start-recoveryon Community, are not registered, so self-healing never proposes an action that always fails. The daemon logs which ones it skipped.disk-cleanupis now "Disk Space Investigation" and only reads. - The docs say plainly that
vxl scanis a deployment readiness check and does not look for known vulnerabilities in dependencies or images.
Third-party notice. The Linux voxeltrond and vxl-admin include BusyBox, under the GNU General Public License, version 2 only. Its complete source is attached to this release (busybox_1.36.1-6ubuntu3.1.dsc and its files, with BUSYBOX-SOURCE-README.md); the licence and written offer are in NOTICE-busybox.md.
Voxeltron 0.1.3
0.1.3 carries the fixes from the last round of 0.1.2 testing, which were
finished after the 0.1.2 release was cut, and three fixes found by testing
the published 0.1.2.
Security
- With Loki configured,
query_logsreads only logs for containers that belong to a Voxeltron deployment, and masks the deployment's secret values and personal data in every line, as the container-log path already did. Before, it passed the requested container name straight into a Loki query, so it could read any container's logs in Loki, unmasked. Output is capped at 64 KiB. structured_logsreturns only entries for containers that belong to a Voxeltron deployment, masked the same way, and its counts cover only what it returns. It still searches the daemon's local log store, not Loki.
Fixed
investigate_incident,analyze_logs,correlate_eventsandsuggest_fixanswer in about a second instead of timing out after 30 seconds. Each one used to start a second, hidden agent session with its own model calls. They now make no model calls:analyze_logssummarises the logs it is given, and the other three run root cause analysis directly, with a 3 second limit on each log and metric query, and report any evidence source that is not configured or timed out. They are now available without an AI provider too.suggest_fixanalyses the service the issue is about (service, orcontext.apporcontext.service). Before, it always looked up a placeholder service and failed. Without a known service it still returns recommendations and says root cause analysis was skipped.investigate_incidentandcorrelate_eventsno longer analyse a placeholder service when none is given. They skip root cause analysis, say why, and return their other findings.- When the model asks for several read-only tools in one reply, up to three more of them run straight away instead of each costing another model round trip. Tools that change anything still get their own turn.
- On Ubuntu, unattended upgrades no longer restart
voxeltrondin the middle of a deploy. The installer adds/etc/needrestart/conf.d/voxeltron.conf, so needrestart listsvoxeltrondas a deferred restart. Restart it yourself in a maintenance window after security updates. When you remove Voxeltron, delete that file too. vxl bootstrapwrites the same needrestart file as the installer, whether you log in as root or as a user with passwordless sudo.vxl daemon upgradewrites it too, so servers bootstrapped earlier get it on their next upgrade. Hosts without needrestart are left alone.vxl deployandvxl deploy productwait up to 10 seconds for a daemon that is restarting, instead of failing at once with "connection refused". Requests are sent only once a connection is up, so nothing is ever sent twice.scripts/install.sh --versionon Ubuntu downloads the version you asked for. Before, it read/etc/os-releasein a way that replaced the requested version with Ubuntu's own (such as "24.04.4 LTS (Noble Numbat)"), so the download failed. The site installer was not affected.vxl-admin --versionprintsvxl-admin <version>, asvoxeltrond --versionandvxl --versiondo. Before, it was rejected as an unexpected argument.- Release archives built on macOS no longer carry macOS extended attributes, so GNU tar on the server no longer prints "Ignoring unknown extended header keyword" while unpacking them.
Third-party notice. The Linux voxeltrond and vxl-admin include BusyBox, under the GNU General Public License, version 2 only. Its complete source is attached to this release (busybox_1.36.1-6ubuntu3.1.dsc and its files, with BUSYBOX-SOURCE-README.md); the licence and written offer are in NOTICE-busybox.md.
Voxeltron 0.1.2
0.1.2 is the first release after 0.1.0. A 0.1.1 was built and signed but
never published; everything planned for it is in 0.1.2, together with the
fixes from the second round of battle testing.
Added
- Crashed apps deployed with
vxl deployare restarted automatically, up to[lifecycle.remediation] max_restarts(3) times inwindow_secs(600) with backoff, then quarantined with onecrash_quarantinealert. Before, they raisedcrash_detectedand stayed down. The limits and[lifecycle] healthy_window_secs(120) are configurable. - Approval-gated self-healing, off by default (
[self_healing] enabled = true). A quarantined crash loop becomes a proposal to roll back to the previous deployment; the request goes to your[monitoring.channels],vxl approvals list|approve|denydecides it, the daemon checks the app recovered (remediation_recoveredorremediation_failed), and a denial leaves the app quarantined (remediation_denied). Needs gRPC auth andsecurity.operator_admins. See "Crash recovery and self-healing" indocs/self-hosting.md. vxl audit exportprints the daemon audit trail. Runbook approvals now record the approver's token subject.
Upgrade notes
- After upgrading from 0.1.0, run
sudo vxl-admin node harden(or rerun the installer). Databases created on 0.1.0 are not adopted: recreate them. systemctl restart nftablesflushes the whole ruleset, including Docker's own firewall chains. Voxeltron's metadata egress table is reapplied automatically. Runsudo systemctl restart dockerafterwards to restore Docker's chains; until thenvxl-admin doctor auditreports HARDEN-FW-001.- On a host whose default routes use several interfaces, run
sudo vxl-admin node harden --public-interface <name>. - Hosts without nftables print "metadata egress block NOT installed: nftables missing". Install nftables, then run
sudo vxl-admin node harden. ops/upgrade.shrefuses hosts wherenft -ffails, such as unprivileged LXC containers.- The first daemon start after the upgrade recreates each managed Redis database's container so it requires its password (
managed Redis now requires its passwordin the log). Apps that connected without the password must useREDIS_URLorREDIS_PASSWORD. - Hosts installed with 0.1.0 use Docker's default address pools, which run out at about 15 apps. Rerun the installer, or add
default-address-poolsto/etc/docker/daemon.jsonasdocs/self-hosting.mdshows, thensudo systemctl restart docker.
Security
- Alerts from the built-in rules are readable on every edition, in the TUI and by the agent. Custom alert rules remain a Team and Enterprise feature.
- Each agent tool call in the audit log names its conversation (
session_id) and whether it came from the agent or a direct tool call. Calls refused by the permission ceiling or an entitlement are audited asdenied. - The release signing key was rotated on 1 Nov 2026. Releases are now signed with minisign key ID
AE5B254F98D5E1CA(public keyRWTK4dWYTyVbrgcV0LOIXqg6p6RQECLoyMXoLGZt6e9NcOzW33vpwu7+, also at https://voxeltron.dev/release-key.txt). Do not trust anything signed by the previous key, including the 0.1.0SHA256SUMS.minisig. The site installer,ops/upgrade.shandscripts/install.shtrust only the new key. - HSTS is not sent. An opt-in per-app
Strict-Transport-Securitysetting is planned for 0.1.2. - Apps with a domain are served over HTTPS only. Plain HTTP now redirects to HTTPS; before, Caddy's server listened on port 80 as well and served every app in clear text with no redirect. Existing hosts move over when the daemon starts. If your own Caddyfile puts the server that serves Voxeltron apps on port 80, the daemon logs an error at startup and
vxl-admin doctor auditfails HARDEN-EDGE-001. - The assistant's
http_requesttool (POST, PUT, DELETE and PATCH) is off by default. It exists only whenai.http_request.allowed_hostslists hosts, sends only to them, never follows a redirect, caps request bodies at 64 KiB, and refuses Cookie, forwarding and method-override headers. HTTP tools read at most 100 KiB of a response. Calls are audited with method, host, path (long segments hashed), status and sizes. There is no per-call approval, so list only hosts the assistant may change. - The assistant's verifier and anomaly diagnosis no longer exceed the operator's
ai.max_permission. Before, with the defaultreadceiling they could still run Safe-tier tools such as restarting or stopping a container. Verification is now capped at the lower of the configured ceiling and Safe, and anomaly diagnosis is strictly read-only. - Assistant tool calls refused for exceeding the permission ceiling or for a missing entitlement are now written to the audit log with outcome
denied, the caller, the tool and the reason. Parameters are never recorded. - SOPS and Infisical project reads no longer return global values. A SOPS project read now returns only
projects.<name>.<key>; if you relied on flat top-level keys being served to projects, move them underprojects.<name>. Infisical serves global secrets only until per-project mapping exists. - Compose
${vault:KEY}references resolve only secrets from the project (or the scope the reference names). A project reference no longer falls back to a global secret of the same name. - Credentials in Git URLs are redacted from logs and error messages.
- Installing a plugin is limited to operator admins, and plugin names must be lowercase letters, digits and hyphens (up to 64 characters, starting with a letter or digit). Plugins remain off by default.
- Log queries return at most 1000 entries per page.
- Managed Redis databases created with
vxl db createrequire their password. Before, Redis ran without one although apps were givenREDIS_PASSWORDand aREDIS_URLwith it, so any container on the project network could read and write it. The password reaches Redis through the container environment and a 0600 file on the container's tmpfs, never through an argument list. Existing Redis databases are recreated on the same volume, with their data, when the upgraded daemon starts.
Fixed
- The assistant's
get_project_statusreported a crash-looping app as "Creating". It now reports health asvxl statusdoes, with the current deployment, its container and any quarantine. voxeltrond config validaterefuses[ai] providerwithoutmodel. No provider has a default model; before, every call failed at runtime with an empty model name. The DeepSeek models are nowdeepseek-flashanddeepseek-v4-pro.- The installers wait up to 45 minutes (was 10) for the package lock that unattended-upgrades holds on a new server, say once a minute which process holds it, and stop with what to do if it stays held.
APT_LOCK_TIMEOUTaccepts up to 7200 seconds. - The assistant's log lines are scrubbed the same way from every source (URLs, secrets, one line each, at most 2,000 characters) and are marked as untrusted app output. Tools the edition does not include are no longer offered to the assistant.
- The operations agent can find apps by name (
list_apps, and app names inget_project_status,list_deployments,query_logsandquery_metrics). Before, it needed project UUIDs it had no way to discover. query_logsreads the app's container logs, with the app's secrets and personal data masked. Before, without Loki, it always returned nothing.query_metricsfinds an app's CPU, memory, restarts and health by app name, and says when a metric is not collected instead of returning an empty result. Restart counts are now recorded, so the built-in restart-loop runbook can detect a restart loop.- The agent keeps its own tool results between steps and never sends the same successful mutating request twice in a run. Before, with providers that return no text alongside a tool call (such as DeepSeek), it lost its results and could repeat a POST.
investigate_incident,analyze_logs,correlate_eventsandsuggest_fixuse the configured AI provider. Before, they always failed with "no AI provider configured".- A failed
vxl upis recorded:vxl statusand the agent show the failure and its fix (for example VXL-FS-001). Log evidence still stays with the CLI. - Apps deployed with
vxl upkeep their deployment record across a daemon restart, including when the deploy request was interrupted. Before, they could staypendingforever. ai.http_request.allowed_hostsexplains ahost:portentry correctly, and accepts a bare IPv6 address.- Apps with a managed database, and apps deployed with
vxl deploy, come back after a host reboot. - Rerunning the installer to upgrade restarts the daemon onto the new binary.
vxl-admin updateandops/upgrade.shkeep the daemon executable by its service user.vxl daemon upgrade --verify-runtime-compatworks on Docker installs. Releases now publish a signedrelease-manifest.json.vxl bootstrapandvxl daemon upgradework as a passwordless-sudo user, on Linux arm64, and when a prerequisite package must be installed.- A second app with a domain deploys (Caddy TLS policies are updated in place).
vxl deploytakes--git-commitor--git-tagfor git sources.vxl secretsandvxl composeaccept project names. Permission errors show the daemon's reason.vxl rollbackworks for apps deployed withvxl up.- The 14-day certificate expiry alert no longer fires for certificates from Caddy's local CA (
tls internal), which last about 12 hours and renew themselves. - A crash alert for an app the kernel killed for running out of memory says so, instead of only "exit code 137".
- More than about 15 apps on one host. Docker's default address pools allow about 31 networks, and Voxeltron uses one per project and one per deployment; past that, deploys and reboot restores failed. The installers now give Docker /24 pools (4096 networks) when
/etc/docker/daemon.jsondoes not exist, and ...