Quick Start

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:

Field	Value
Payload URL	`http://your-server-ip:8080/webhook`
Content type	`application/json`
Secret	The secret you generated
Events	`push` 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.

Getting Started

Guides

Reference

1. Deploy

2. Configure

3. Set Up the Webhook

4. Push and Watch

5. (Optional) Enable the Checks API

Local Mode

​1. Deploy

​2. Configure

​3. Set Up the Webhook

​4. Push and Watch

​5. (Optional) Enable the Checks API

​Local Mode

1. Deploy

2. Configure

3. Set Up the Webhook

4. Push and Watch

5. (Optional) Enable the Checks API

Local Mode