Installation

Voxeltron ships as two static binaries: the daemon (voxeltrond) and the TUI client (voxeltron). No runtime dependencies. No package manager drama. Just copy and run.

CI/CD policy: temporary manual releases on build-mac; automation is fallback only.

Method 1: Install Script (Recommended)

The fastest way to get started. Run this on your server:

$ curl -sSL https://voxeltron.dthink.ai/install.sh | bash

The script:

• Detects your OS and architecture
• Downloads the latest release binaries from GitHub
• Installs them to /usr/local/bin
• Creates a voxeltrond.service systemd unit
• Creates a voxeltron user with minimal privileges

Method 2: Manual Binary Install

# Linux x86_64 (most servers)
$ curl -LO https://github.com/voxeltron/voxeltron/releases/latest/download/voxeltrond-linux-x86_64.tar.gz
$ curl -LO https://github.com/voxeltron/voxeltron/releases/latest/download/voxeltron-linux-x86_64.tar.gz

# macOS (for local TUI only)
$ curl -LO https://github.com/voxeltron/voxeltron/releases/latest/download/voxeltron-darwin-arm64.tar.gz

$ curl -LO https://github.com/voxeltron/voxeltron/releases/latest/download/SHA256SUMS
$ sha256sum --check SHA256SUMS --ignore-missing

$ tar -xzf voxeltrond-linux-x86_64.tar.gz
$ tar -xzf voxeltron-linux-x86_64.tar.gz
$ sudo mv voxeltrond voxeltron /usr/local/bin/
$ sudo chmod +x /usr/local/bin/voxeltrond /usr/local/bin/voxeltron

$ sudo tee /etc/systemd/system/voxeltrond.service <<'EOF'
[Unit]
Description=Voxeltron Daemon
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=voxeltron
ExecStart=/usr/local/bin/voxeltrond start
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

$ sudo useradd -r -s /bin/false voxeltron
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now voxeltrond

Method 3: Build from Source

For contributors or the deeply suspicious:

# Prerequisites: Rust 1.82+, Go 1.22+

$ git clone https://github.com/voxeltron/voxeltron
$ cd voxeltron

# Build the daemon
$ cargo build --release -p voxeltrond

# Build the TUI
$ cd tui && go build -o voxeltron ./cmd/voxeltron

Method 4: Signed Package Repository Snapshots (APT/DNF)

Each release also ships signed APT and DNF repository snapshots for offline/mirrored environments.

APT (Debian/Ubuntu)

# Download snapshot + metadata + signing key from a release
$ curl -LO https://github.com/jaikoo/voxeltron/releases/download/vX.Y.Z/voxeltron-apt-repo.tar.gz
$ curl -LO https://github.com/jaikoo/voxeltron/releases/download/vX.Y.Z/voxeltron-signing-key.asc
$ curl -LO https://github.com/jaikoo/voxeltron/releases/download/vX.Y.Z/voxeltron-apt-Release
$ curl -LO https://github.com/jaikoo/voxeltron/releases/download/vX.Y.Z/voxeltron-apt-Release.gpg

# Verify metadata signature
$ gpg --import voxeltron-signing-key.asc
$ gpg --verify voxeltron-apt-Release.gpg voxeltron-apt-Release

# Install from local repo snapshot
$ sudo mkdir -p /opt/voxeltron-repo
$ sudo tar -xzf voxeltron-apt-repo.tar.gz -C /opt/voxeltron-repo
$ sudo install -D -m 0644 voxeltron-signing-key.asc /etc/apt/keyrings/voxeltron.asc
$ echo "deb [signed-by=/etc/apt/keyrings/voxeltron.asc] file:///opt/voxeltron-repo/apt stable main" | sudo tee /etc/apt/sources.list.d/voxeltron.list
$ sudo apt update && sudo apt install voxeltron

DNF (Fedora/RHEL)

# Download snapshot + metadata + signing key from a release
$ curl -LO https://github.com/jaikoo/voxeltron/releases/download/vX.Y.Z/voxeltron-rpm-repo.tar.gz
$ curl -LO https://github.com/jaikoo/voxeltron/releases/download/vX.Y.Z/voxeltron-signing-key.asc
$ curl -LO https://github.com/jaikoo/voxeltron/releases/download/vX.Y.Z/voxeltron-rpm-repomd.xml
$ curl -LO https://github.com/jaikoo/voxeltron/releases/download/vX.Y.Z/voxeltron-rpm-repomd.xml.asc

# Verify metadata signature
$ gpg --import voxeltron-signing-key.asc
$ gpg --verify voxeltron-rpm-repomd.xml.asc voxeltron-rpm-repomd.xml

# Install from local repo snapshot
$ sudo mkdir -p /opt/voxeltron-repo
$ sudo tar -xzf voxeltron-rpm-repo.tar.gz -C /opt/voxeltron-repo
$ sudo cp voxeltron-signing-key.asc /opt/voxeltron-repo/voxeltron-signing-key.asc
$ cat <<'EOF' | sudo tee /etc/yum.repos.d/voxeltron.repo
[voxeltron]
name=Voxeltron
baseurl=file:///opt/voxeltron-repo/rpm
enabled=1
gpgcheck=1
gpgkey=file:///opt/voxeltron-repo/voxeltron-signing-key.asc
EOF
$ sudo dnf makecache && sudo dnf install voxeltron

Post-Install Verification

# Check versions
$ voxeltrond --version
voxeltrond v0.8.0

$ voxeltron --version
voxeltron v0.8.0

# Check daemon health
$ voxeltrond status
● voxeltrond.service - Voxeltron Daemon
   Active: active (running) since 2026-02-20 09:14:22 UTC
   Memory: 47.2M
   Uptime: 2h 14m 8s

Firewall Configuration

Open the required ports on your server:

# UFW (Ubuntu/Debian)
$ sudo ufw allow 80/tcp    # HTTP (redirected to HTTPS)
$ sudo ufw allow 443/tcp   # HTTPS
$ sudo ufw allow 7443/tcp  # gRPC management (restrict to your IP!)

# Better: restrict gRPC to your IP
$ sudo ufw allow from YOUR_IP to any port 7443

Uninstall

$ sudo systemctl disable --now voxeltrond
$ sudo rm /usr/local/bin/voxeltron /usr/local/bin/voxeltrond
$ sudo rm /etc/systemd/system/voxeltrond.service
$ sudo rm -rf /var/lib/voxeltrond  # WARNING: deletes all state