CLI Reference

Commands

`athanor serve`

Start the webhook server.

athanor serve

Reads configuration from environment variables (or /etc/athanor/env via systemd).

`athanor` (default)

Launch the interactive TUI to run workflows locally.

# Interactive - pick a workflow
athanor

# Run a specific workflow
athanor --workflow .github/workflows/ci.yml

# Custom workflow directory
athanor --workflow-dir ./my-workflows

Flags (Local Mode)

Flag	Default	Description
`--workflow-dir`	`.github/workflows`	Directory to search for workflow files
`--workflow`	(none)	Path to a specific workflow file (skips the selection TUI)

Environment Variables (Server Mode)

Required

Variable	Description
`WEBHOOK_SECRET`	GitHub webhook secret for signature validation
`GITHUB_TOKEN`	Personal access token with `repo:status` scope

Server

Variable	Default	Description
`LISTEN_ADDR`	`:8080`	Address to listen on
`WORKSPACE_DIR`	`/var/lib/athanor/workspaces`	Where repos are cloned

MicroVM

Set KERNEL_PATH to enable VM mode. If unset, steps run directly on the host.

Variable	Default	Description
`KERNEL_PATH`	(none)	Path to vmlinux kernel. Enables VM mode.
`ROOTFS_PATH`	`/var/lib/athanor/rootfs.ext4`	Base rootfs image
`SSH_KEY_PATH`	`/var/lib/athanor/vm-ssh-key`	SSH private key for VM access
`VM_DISK_DIR`	`/var/lib/athanor/vm-disks`	Directory for per-VM rootfs copies
`VM_CPUS`	`2`	vCPUs per VM
`VM_MEMORY_MB`	`2048`	RAM per VM in MB
`VM_MAX_PARALLEL`	`0` (auto)	Max concurrent VMs. `0` = auto-detect from host RAM.

GitHub App (Optional)

For Checks API support with full logs. See GitHub App Setup.

Variable	Description
`GITHUB_APP_ID`	GitHub App ID
`GITHUB_APP_INSTALLATION_ID`	Installation ID
`GITHUB_APP_PRIVATE_KEY_PATH`	Path to the `.pem` private key

HTTP Endpoints

Method	Path	Description
`GET`	`/`	Web dashboard
`GET`	`/health`	Health check (returns `ok`)
`POST`	`/webhook`	GitHub webhook receiver
`GET`	`/api/runs`	Recent runs as JSON
`GET`	`/api/events`	SSE stream of run updates

Make Targets

Target	Description
`make build`	Build binary to `bin/athanor`
`make build-linux`	Cross-compile for Linux (arm64 + amd64)
`make test`	Run all tests
`make vet`	Run `go vet ./...`
`make run`	Build and launch the TUI
`make run-workflow WORKFLOW=path`	Build and run a specific workflow
`make clean`	Remove build artifacts

Getting Started

Guides

Reference

Commands

`athanor serve`

`athanor` (default)

Flags (Local Mode)

Environment Variables (Server Mode)

Required

Server

MicroVM

GitHub App (Optional)

HTTP Endpoints

Make Targets

​Commands

​athanor serve

​athanor (default)

​Flags (Local Mode)

​Environment Variables (Server Mode)

​Required

​Server

​MicroVM

​GitHub App (Optional)

​HTTP Endpoints

​Make Targets

Commands

`athanor serve`

`athanor` (default)

Flags (Local Mode)

Environment Variables (Server Mode)

Required

Server

MicroVM

GitHub App (Optional)

HTTP Endpoints

Make Targets