Installation

Voxeltron ships signed release archives for the Linux daemon and the CLI. The Linux installer verifies the archive before it installs anything other than minisign, then creates the service. Follow the signed installer steps below, or build from source.

Supported targets

  • Linux x86_64: voxeltrond, vxl and vxl-admin.
  • Linux arm64: voxeltrond, vxl and vxl-admin.
  • macOS arm64: vxl only.

Other platforms, including macOS on Intel, are not supported by the installer. Docker is the default runtime in Community v0.1. The installer provides Caddy 2.8 or later on Ubuntu and Debian. Firecracker is a preview and is not enabled by this installer.

Install Docker on Ubuntu or Debian

On a fresh host, choose one method below. We recommend the distro package when it provides Docker Engine 24 or later because apt manages its updates with the rest of the OS. Start by installing the download tools:

$ sudo apt-get update
$ sudo apt-get install -y ca-certificates curl

For the Ubuntu or Debian distro package:

$ sudo apt-get install -y docker.io

Alternatively, Docker's official convenience script detects Ubuntu or Debian and installs Docker from its own repository. Use this path for a test server. Download and read it first:

$ curl -fsSL https://get.docker.com -o get-docker.sh
$ less get-docker.sh
$ sudo sh ./get-docker.sh

Docker recommends the convenience script for testing and development only. For a production host whose distro package is older than 24, use Docker's official apt repository instructions forUbuntu orDebian. Do not mix distro and Docker repository packages.

After either method, start Docker and check that the Server version is 24 or later:

$ sudo systemctl enable --now docker
$ sudo docker version

The docker group is root-equivalent. To run docker build as your normal login user, grant that user access:

$ sudo usermod -aG docker $USER

The group applies to new login sessions. Log out and log in again, or runnewgrp docker in the current shell. Use sudo docker build meanwhile. Run docker version to confirm access to both Client and Server. Alternatively, keep your user out of the group and prefix Docker commands withsudo, including sudo docker build -t hello:latest . in the Quickstart. See Docker's user access guidance.

Without buildx, Ubuntu's docker.io uses the legacy builder and prints a harmless buildx deprecation notice. On Ubuntu 24.04, install docker-buildx to remove it with sudo apt-get install -y docker-buildx. The package is available inUbuntu's Noble archive.

Build from source

This works today. You need Rust, Go and the protobuf compiler. From a checkout of the repository:

$ cargo build --release -p voxeltrond
$ (cd tui && go build -o ../target/release/vxl ./cmd/vxl)
$ sudo install -m 0755 target/release/voxeltrond /usr/local/bin/voxeltrond
$ sudo install -m 0755 target/release/vxl /usr/local/bin/vxl

Then render a configuration, create the gRPC signing key and start the daemon. The README has the full sequence.

Install the daemon on Linux

On Ubuntu 22.04 or later or Debian, with Docker installed:

$ curl -fsSLo install.sh https://voxeltron.dev/install.sh
$ sudo env VOXELTRON_VERSION=0.1.3 sh ./install.sh

On Ubuntu or Debian the installer installs Caddy 2.8 or later from Caddy's official apt repository when Caddy is missing or older than 2.8.0. It leaves a newer Caddy in place and enables caddy.service with its default admin API on127.0.0.1:2019. Other distributions are not supported by the installer. Install Caddy 2.8 or later yourself fromCaddy's installation guide, runcaddy version to confirm the version, and enable the service with the admin API on loopback before you start Voxeltron.

The published site installer takes no flags. Always set VOXELTRON_VERSION=0.1.3to select this exact release. The release public key is built in, and the installer prints it before downloading. It verifies the Minisign signature onSHA256SUMS, then checks the pinned archive's checksum and installs the binaries under /usr/local/bin. It then writes:

  • /etc/voxeltron/voxeltron.toml, a complete rendered configuration.
  • /etc/voxeltron/voxeltrond.env, containing the local secrets passphrase.
  • /etc/systemd/system/voxeltrond.service, enabled and started.

It also initializes gRPC authentication. Mint your first operator token withsudo voxeltrond token mint --config /etc/voxeltron/voxeltron.toml --subject operator --ttl 86400. The default lifetime is one hour, and the default maximum is one day. Read the installer before you run it. Download it to a file first.

The installer may also install gnupg, minisign, nftables, Caddy and Caddy's apt repository. It verifies the release first; only minisign, which the check needs, may be installed before that. Caddy's repository is added only if its signing key has the pinned fingerprint 65760C51EDEA2017CEA2CA15155B6D79CA56EA34.

Check the Caddy configuration

Both installers, site/public/install.sh downloaded above and the repository'sscripts/install.sh, recognize the verified stock/etc/caddy/Caddyfile by its checksum. They back that file up to/etc/caddy/Caddyfile.voxeltron-backup, replace it with an admin endpoint onlocalhost:2019 and no sites, and reload Caddy. A repeated install preserves the backup. A custom Caddyfile stays untouched, with a message that existing sites stay andvxl up will report any conflict.

An unmanaged Caddy route error means an existing route, including a catch-all welcome site, already serves the requested domain. Voxeltron refuses to overwrite it. For a custom site, choose another domain or remove only the conflicting route after reviewing it. Run sudo systemctl stop voxeltrond, then run the exactvoxeltrond edge remove-route command printed in the error with sudo. Keep its --index, --expect-sha256 and --yes arguments. Remove the corresponding site from the Caddyfile too so a later reload cannot restore it. Validate and reload Caddy, run sudo systemctl start voxeltrond, then retry the deploy.

Set the certificate contact address

A domain: route refuses to deploy without an ACME contact email:proxy.acme.email must be set to the contact address for Let's Encrypt. For a test box with no public DNS, use issuer = "internal" instead; see Domains and TLS for local certificate trust. Add email under the existing [proxy.acme] table in/etc/voxeltron/voxeltron.toml. Do not paste a second table header. The file holds the daemon's gRPC signing secret, so do not paste it anywhere. Reading or editing this protected file requires sudo:

$ sudo grep -A4 '^\[proxy.acme\]' /etc/voxeltron/voxeltron.toml
$ sudoedit /etc/voxeltron/voxeltron.toml

For a non-interactive alternative to sudoedit, run this once to insert the email under the existing table:

$ sudo sed -i '/^\[proxy.acme\]/a email = "[email protected]"' /etc/voxeltron/voxeltron.toml

The resulting table is:

[proxy.acme]
issuer = "acme"
email = "[email protected]"
directory_url = "https://acme-v02.api.letsencrypt.org/directory"

Validate the edited configuration and restart the daemon:

$ sudo voxeltrond config validate
$ sudo systemctl restart voxeltrond

Point your domain's DNS A record at the server's public address. Before DNS is ready, check a deployed route on the server withcurl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' -H 'Host: hello.example.com' http://127.0.0.1/, using your domain. This sends a GET and prints the status code and redirect URL. For a public domain, expect308 https://hello.example.com/. The route is live, and HTTPS takes over once DNS and the certificate are ready. For a name Caddy will not get a public certificate for, such as hello.test, expect 200 directly from the app. Public HTTPS needs the name to resolve to the server, ports 80 and 443 to be reachable and the certificate to be issued.

Back up the secrets passphrase

The installer creates /etc/voxeltron/voxeltrond.env once. The file holds VOXELTRON_SECRETS_PASSPHRASE=..., is owned by root, and has mode 0600. Reinstalling or upgrading preserves the existing file.

Back up the passphrase file together with /var/lib/voxeltron. Store the backup separately from the database and restrict access to it. Without the passphrase, encrypted secrets cannot be read, even when the database is restored.

To set the passphrase explicitly, edit the environment file while the daemon is stopped:

$ env_file=/etc/voxeltron/voxeltrond.env
$ sudo systemctl stop voxeltrond
$ sudoedit "$env_file"
VOXELTRON_SECRETS_PASSPHRASE=your-long-passphrase
$ sudo chown root:root "$env_file"
$ sudo chmod 0600 "$env_file"
$ sudo systemctl start voxeltrond

Use an existing passphrase when restoring a host. Changing the passphrase after secrets have been stored makes those secrets unreadable.

Install the CLI

On an Apple silicon Mac, the same signed site installer installs vxl only. The default /usr/local/bin usually needs sudo; the installer invokes sudo when that destination is not writable. To avoid sudo for the binary installation, create a directory you own and add it to PATH:

$ mkdir -p "$HOME/.local/bin"
$ curl -fsSLo install.sh https://voxeltron.dev/install.sh
$ env VOXELTRON_VERSION=0.1.3 VOXELTRON_INSTALL_BIN_DIR="$HOME/.local/bin" sh ./install.sh
$ export PATH="$HOME/.local/bin:$PATH"

Read install.sh before running it. Add the PATH export to ~/.zshrc for future shells. Install minisign first with brew install minisign if it is missing; the installer refuses to continue without it on macOS.

Every release archive contains vxl: voxeltron-<version>-linux-x86_64.tar.gz,voxeltron-<version>-linux-arm64.tar.gz and voxeltron-<version>-darwin-arm64.tar.gz. Linux archives also contain voxeltrond and vxl-admin; the installer installs all three binaries. On macOS the installer installs vxl only. To install by hand, download the archive andSHA256SUMS, verify the checksum, then place the binary on your path:

$ shasum -a 256 -c SHA256SUMS --ignore-missing
$ tar -xzf voxeltron-<version>-linux-x86_64.tar.gz
$ sudo install -m 0755 vxl /usr/local/bin/vxl
$ vxl --version

The archive names on the release page include the version and target. Seebinary verification for signature checks.

Connect on the server

Run these commands on the server as your normal login user. The installer also installsvxl. This profile connects directly to loopback and needs no SSH login to itself:

$ sudo voxeltrond token mint --config /etc/voxeltron/voxeltron.toml --subject operator --ttl 86400 | vxl server add prod --host 127.0.0.1 --runtime docker --auth-token-stdin
$ vxl server use prod
$ vxl server inspect prod

Expect Transport: plaintext over loopback. The bearer token authenticates calls without TLS or an insecure override. Keep gRPC bound to 127.0.0.1:50051. Only the mint command uses sudo, so the profile belongs to your login user. Run later vxl commands as that same user.

Tokens expire after one hour by default. This pipeline requests 86400 seconds, the default maximum of one day. Repeat it when the token expires. The token travels through stdin instead of argv. Keep it secret. VXL_TOKEN is also supported when another tool already supplies the token through the environment.

From your laptop

Install vxl on the laptop first. Replace 203.0.113.10 andadmin below with your server address and SSH user. That user must have SSH key login and permission to run the token mint command with sudo. The pipeline needs noninteractive sudo for token minting. If sudo requires a password, mint the token in an interactive server session and supply it through stdin on the laptop instead. Voxeltron uses your local SSH agent or keys in ~/.ssh. Use --key for a specific key.

Through your provider's console or an existing trusted server session, run this on the server to read its Ed25519 host key fingerprint:

$ ssh-keyscan -t ed25519 localhost 2>/dev/null | ssh-keygen -lf -

Voxeltron accepts the SHA256 fingerprint of any host key type returned byssh-keyscan, including RSA, ECDSA and Ed25519. If the server has no Ed25519 key, use -t rsa or -t ecdsa in the console command instead. Pin the verified fingerprint with --host-key-fingerprint SHA256:... onvxl server add. An unknown host error prints the presented fingerprints and a pin command.

On the laptop, OpenSSH also needs the verified key in ~/.ssh/known_hosts. Run ssh [email protected], compare the fingerprint it prints on first connect with the fingerprint obtained from the console for that key type, and answer yesonly if they match. This saves the key to ~/.ssh/known_hosts. Confirm SSH works, then exit back to the laptop before running the pipeline below.

Alternatively, --accept-host-key explicitly enables trust on first use. This records the first key presented without independently verifying who owns it. The example below uses that alternative. Do not combine the two flags. Later connections verify the recorded key strictly and reject a changed key.vxl bootstrap uses the same --accept-host-key and--host-key-fingerprint options. When replacing a profile, supply its connection options and token again.

The token pipeline must pass only the token to stdin. Do not add 2>&1 to the SSH half or mix diagnostics or other output into the pipe.

$ ssh [email protected] sudo voxeltrond token mint --config /etc/voxeltron/voxeltron.toml --subject operator --ttl 86400 | \
    vxl server add prod --host 203.0.113.10 --user admin --ssh-tunnel \
    --runtime docker --accept-host-key --auth-token-stdin
$ vxl server use prod
$ vxl server inspect prod

Expect Transport: SSH tunnel to 203.0.113.10, plaintext inside. SSH protects the connection to the server, and the bearer token authenticates gRPC inside it. Keep the management port on loopback. The Quickstart's image build runs on the server, where the daemon needs the image. A laptop build alone does not place it there.

What runs where

  • On the server: the app source, Dockerfile and docker build. The daemon needs the image locally.
  • On the laptop: voxeltron.yaml and every vxl command, including vxl up, vxl app status and vxl down. Run them from the directory containing the manifest.

After creating the app in step 5 of the Quickstart, copy its manifest from the server into your laptop's app directory, or keep the project in git on both machines:

$ scp [email protected]:~/hello/voxeltron.yaml .

Install with your own release mirror

VOXELTRON_RELEASE_BASE_URL points the installer at a mirror that holds the same signed archives and checksum manifest. Keep the pinned public key independent of the mirror. The installer still checks signatures against its built in key.

Upgrade or remove

Use upgrading for upgrades. The installer has no uninstall mode. To remove Voxeltron, stop and disable voxeltrond, then remove the binary, configuration and data directories you created, along with/etc/needrestart/conf.d/voxeltron.conf. Back up /var/lib/voxeltron first.