Kindling

Ephemeral GitHub Actions runners on Firecracker microVMs.

What is Kindling?

CI runners are either shared or persistent, and neither option is great. Shared runners introduce security risks and noisy-neighbor performance problems. Persistent, self-hosted runners drift over time, accumulate state between jobs, and become a maintenance burden. Organizations need isolated, ephemeral runners that start fast and leave no trace.

Kindling provisions a short-lived VM for every GitHub Actions job. Each runner gets a fresh virtual machine, executes the job, and is destroyed immediately afterward. Integration with GitHub Actions Scale Sets means the fleet scales on demand -- no idle capacity, no manual intervention.

Kindling uses Firecracker microVMs with sub-second boot times and jailer-based isolation on Linux.

Key features

• Ephemeral VMs -- fresh VM per job, destroyed after use, no state leakage between runs
• Sub-second boot -- Firecracker microVMs start in under 200ms
• GitHub Scale Sets -- native integration with Actions runner scale sets
• Best-fit scheduling -- bin-packing algorithm minimizes resource fragmentation across the fleet
• Jailer isolation -- per-VM chroot and UID namespace for defense in depth
• Fleet auto-scaling -- EC2 ASG capacity managed automatically based on queue depth
• Configurable runner sizes -- small, medium, and large presets with custom vCPU and memory

Architecture

graph LR
    GH[GitHub Actions] -->|Scale Set API| C[Controller]
    C -->|gRPC| A1[Agent]
    C -->|gRPC| A2[Agent]
    C -->|gRPC| AN[Agent N]
    A1 --> VM1[VM] & VM2[VM]
    A2 --> VM3[VM] & VM4[VM]
    AN --> VM5[VM] & VM6[VM]

Loading

Controller -- Singleton service. Receives GitHub webhook events, queues jobs, schedules runners across agents using best-fit decreasing, and manages EC2 fleet capacity.

Agent -- Runs on each host. Creates and destroys Firecracker microVMs, injects runner credentials via MMDS, and reports capacity to the controller.

Quick start

# Build
make

# Run preflight checks
kindling-agent --preflight

# Start the agent
kindling-agent --config agent.yaml

See the deployment guide for full setup instructions.

Build

make              # Build all binaries -> bin/
make proto        # Regenerate gRPC code
make test         # Run tests with race detector
make lint         # Run linter

Documentation

• Documentation hub -- comprehensive project walkthrough
• Architecture -- system design and data flows
• Configuration -- all YAML options for controller and agent
• Deployment -- Linux deployment with Terraform and Packer
• gRPC API -- protocol buffer definitions
• ADRs -- architecture decision records

License

MIT -- see LICENSE.