Installation

Prerequisites

Go 1.26+ (install Go)
A Linux server with KVM support (for microVM mode)

Build from Source

git clone https://github.com/alexisbouchez/athanor.git
cd athanor
make build

The binary is written to bin/athanor.

Cross-Compile for Linux

If you’re building on macOS for a Linux server:

make build-linux

Produces bin/athanor-linux-amd64 and bin/athanor-linux-arm64.

Deploy to a Server

Copy the binary to your server:

scp bin/athanor-linux-amd64 root@your-server:/usr/local/bin/athanor

Server Requirements

Your server needs:

Requirement	Minimum	Notes
KVM	`/dev/kvm` present	Required for CloudHypervisor
RAM	4 GB	~1 GB per concurrent VM
Disk	20 GB	~4 GB for the rootfs image
OS	Ubuntu 22.04+	Tested on Ubuntu 24.04
Network	Public IP	For receiving GitHub webhooks

Automated Setup

The repo includes a setup script that installs all dependencies:

# On the server
sudo ./scripts/setup-vps.sh

This installs:

cloud-hypervisor, the VMM
virtiofsd, the virtiofs daemon for workspace sharing
Go, for running workflows that need it
Network bridge + NAT for VM internet access
Rootfs image (Ubuntu 24.04 with Go, git, SSH)

Manual Setup

If you prefer to set things up yourself:

Install cloud-hypervisor:

curl -sL "https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v45.0/cloud-hypervisor-static" \
    -o /usr/local/bin/cloud-hypervisor
chmod +x /usr/local/bin/cloud-hypervisor

Install virtiofsd:

apt install virtiofsd
ln -sf /usr/libexec/virtiofsd /usr/local/bin/virtiofsd

Set up the network bridge:

ip link add br0 type bridge
ip addr add 192.168.100.1/24 dev br0
ip link set br0 up
sysctl -w net.ipv4.ip_forward=1
iptables -t nat -A POSTROUTING -s 192.168.100.0/24 ! -o br0 -j MASQUERADE

Copy the host kernel for VMs:

cp /boot/vmlinuz-$(uname -r) /var/lib/athanor/vmlinux
chmod 644 /var/lib/athanor/vmlinux

Build the rootfs:

sudo ./scripts/build-rootfs.sh

Generate an SSH key pair for VM access:

ssh-keygen -t ed25519 -f /var/lib/athanor/vm-ssh-key -N "" -C "athanor-vm"

Systemd Service

Install the service file:

cp deploy/athanor.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable athanor

Create the config file at /etc/athanor/env:

mkdir -p /etc/athanor
cat > /etc/athanor/env << 'EOF'
GITHUB_TOKEN=ghp_your_token_here
WEBHOOK_SECRET=your_webhook_secret_here
LISTEN_ADDR=:8080
WORKSPACE_DIR=/var/lib/athanor/workspaces
KERNEL_PATH=/var/lib/athanor/vmlinux
ROOTFS_PATH=/var/lib/athanor/rootfs.ext4
SSH_KEY_PATH=/var/lib/athanor/vm-ssh-key
VM_DISK_DIR=/var/lib/athanor/vm-disks
VM_CPUS=2
VM_MEMORY_MB=1024
VM_MAX_PARALLEL=0
EOF
chmod 600 /etc/athanor/env

Start the service:

systemctl start athanor
journalctl -u athanor -f

Run Tests

make test
make vet

Getting Started

Guides

Reference

Prerequisites

Build from Source

Cross-Compile for Linux

Deploy to a Server

Server Requirements

Automated Setup

Manual Setup

Systemd Service

Run Tests

​Prerequisites

​Build from Source

​Cross-Compile for Linux

​Deploy to a Server

​Server Requirements

​Automated Setup

​Manual Setup

​Systemd Service

​Run Tests

Prerequisites

Build from Source

Cross-Compile for Linux

Deploy to a Server

Server Requirements

Automated Setup

Manual Setup

Systemd Service

Run Tests