Getting Started

What this component does

The controller is a long-running process on the macOS host. It ties together:

• the GitHub API or webhook stream
• label-to-image routing
• the Jeballto VM lifecycle
• Actions runner startup and cleanup

Start with poll mode unless you need lower latency

Poll mode is the best first rollout because:

• it does not require public ingress
• it works behind NAT
• it is easier to reason about on a single Mac

Webhook mode is worth it when:

• your controller is reachable from GitHub
• you want lower reaction latency
• you want to reduce API polling noise

Prerequisites

Before you configure the controller, make sure you have:

• Apple Silicon Mac on macOS 26.0+
• a running Jeballto Agent on that host
• a GitHub App or PAT with the right permissions
• a GitHub repository with a simple workflow to test
• a Jeballto image that already contains the Actions runner at /Users/admin/actions-runner

Core rollout decisions

Authentication choice

Use a GitHub App for production. Use a PAT only for development or a fast smoke test.

Runner scope

For poll mode, target one repository. Poll mode needs github.repository because GitHub does not expose a cross-repo queued-job listing endpoint.

Label strategy

Keep the first rollout small:

• one label
• one image
• one CPU and memory profile

Add more labels only after the first successful workflow.

Next step

Move to Installation for the released binary, then follow Quickstart for the one-Mac poll-mode flow.