Skip to main content

​
1. Deploy

Build the binary and copy it to your server (see Installation for full details): 
make build-linux
scp bin/athanor-linux-amd64 root@your-server:/usr/local/bin/athanor
Run the setup script on the server: 
ssh root@your-server 'bash -s' < scripts/setup-vps.sh

​
2. Configure

Create a GitHub Personal Access Token at github.com/settings/tokens with repo:status scope. Generate a webhook secret: 
openssl rand -hex 32
Write the config on the server: 
cat > /etc/athanor/env << 'EOF'
GITHUB_TOKEN=ghp_your_token
WEBHOOK_SECRET=your_secret
LISTEN_ADDR=:8080
KERNEL_PATH=/var/lib/athanor/vmlinux
EOF
Start the service: 
systemctl start athanor

​
3. Set Up the Webhook

On your GitHub repository, go to Settings > Webhooks > Add webhook:
FieldValue
Payload URLhttp://your-server-ip:8080/webhook
Content typeapplication/json
SecretThe secret you generated
Eventspush and pull_request
Or use the GitHub CLI: 
gh api repos/OWNER/REPO/hooks --method POST --input - << EOF
{
  "config": {
    "url": "http://your-server-ip:8080/webhook",
    "content_type": "json",
    "secret": "your_secret"
  },
  "events": ["push", "pull_request"],
  "active": true
}
EOF

​
4. Push and Watch

Push a commit. The webhook fires, Athanor spins up a microVM, runs your workflow, and reports the result. Check the web dashboard at http://your-server-ip:8080/ to see the run in real time. Check the commit on GitHub — you’ll see an Athanor status check.

​
5. (Optional) Enable the Checks API

For full log output on GitHub (not just pass/fail), set up a GitHub App. See GitHub App Setup.

​
Local Mode

You can also run workflows locally with the terminal UI: 
# Interactive — pick a workflow
athanor

# Run a specific file
athanor --workflow .github/workflows/ci.yml
The TUI shows a split-panel view with the job/step tree on the left and scrollable log output on the right.