Apple Silicon · macOS 26.0+

macOS,
on demand.

Headless, API-first macOS virtual machine management for Apple Silicon. Create, install, start and automate fresh macOS 26.0+ VMs through one agent and one REST API.

Download the Agent See API Flow

REST API
OCI images
SSH and VNC
Jeballtofile
Ephemeral VMs
2 concurrent VMs
macOS 26.0+

Runtime

One local service.
Full VM control.

JeballtoAgent runs as a menu bar app on Apple Silicon and exposes the full VM lifecycle through one REST API. CI integrations and the CLI are clients of that surface, not separate systems.

Headless by default.

One local endpoint. Every VM operation behind it.

The agent owns VM lifecycle, networking, images, automation and persistence so every client can stay small. Start with curl, use the CLI for local operations, then connect CI controllers or your own orchestrator when you need job automation.

It stays close to the platform with Apple Virtualization, restart-safe state and a small dependency surface. The interface stays the same whether you are booting one VM by hand or wiring it into CI.

VM modelPersistent machines or disposable workers
PersistenceVM state is saved to disk and restored after graceful agent restarts
Dependenciesoras, Sparkle and Yams
AutomationJeballtofile blueprints and keystroke injection

Features

Build, boot,
connect and reuse.

The core surface stays compact, but it covers the full path from blank disk to reusable image and repeatable automation.

REST lifecycle

Create, start, stop, pause, resume, clone, snapshot and delete VMs through explicit HTTP endpoints, including disposable CI workflows.

OCI images

Pull, push and reuse full macOS images through ECR, ACR, Artifact Registry or any OCI-compatible registry.

SSH & VNC

Forward terminal and graphical access automatically, then execute commands inside the guest, capture screenshots or inject keystrokes.

Parallel VMs

Run up to two virtual machines in parallel on one host, with graceful restart support for stateful machines when the agent comes back.

Jeballtofile

Describe provisioning in YAML or JSON, then let the agent run install, wait, execute and keystroke steps in order.

Automatic install

Download the latest IPSW from Apple or supply your own source, then automate Setup Assistant before SSH is ready.

Get Started

Install, launch,
make the first request.

Install the menu bar agent, copy its bearer token and your first macOS VM is only a few API calls away.

~/ terminal

# Grab the latest release
$ curl -LO github.com/jeballto/jeballto/releases/latest/download/JeballtoAgent.zip

# Unpack and install the app bundle
$ unzip JeballtoAgent.zip
$ mv JeballtoAgent.app /Applications/

# Launch the menu bar agent
$ open /Applications/JeballtoAgent.app

# Copy the bearer token from the menu bar
$ export TOKEN=your-token

# Create your first VM
$ curl -X POST \
    http://agent-host:8011/v1/vms \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name":"dev-vm"}'

Download the release

Grab the signed ZIP from GitHub Releases. Each release expands to a single JeballtoAgent.app bundle.
Move to Applications

Move JeballtoAgent.app into /Applications, launch it and let it sit in your menu bar.
Copy the token and call the API

Use the menu bar item to copy the bearer token or read it from ~/Library/Application Support/Jeballto/config.json. From there, your first POST /vms is one request away.

API Flow

Four calls
to a running Mac.

Same REST surface supports manual calls, CLI convenience and CI automation. Tabs below show the smallest useful path from VM definition to desktop access.

~ bootstrap.sh

# Create a VM with 4 cores, 8 GB RAM and 64 GB disk
curl -s -X POST http://agent-host:8011/v1/vms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-vm",
    "resources": {
      "cpuCount": 4,
      "memorySize": "8GB",
      "diskSize": "64GB"
    }
  }'

# Install macOS. Auto-downloads the latest IPSW from Apple.
curl -s -X POST http://agent-host:8011/v1/vms/$VM_ID/install \
  -H "Authorization: Bearer $TOKEN"

# Or specify an IPSW of your choice
curl -s -X POST http://agent-host:8011/v1/vms/$VM_ID/install \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "ipsw": "https://.../macOS-26.1.ipsw" }'

# Start the VM
curl -s -X POST http://agent-host:8011/v1/vms/$VM_ID/start \
  -H "Authorization: Bearer $TOKEN"

# State is saved across graceful agent restarts.
# SSH and VNC forwarding happens automatically.

# Open a graphical window
curl -s -X POST http://agent-host:8011/v1/vms/$VM_ID/gui \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

# Or capture a screenshot instead
curl -s http://agent-host:8011/v1/vms/$VM_ID/screenshot \
  -H "Authorization: Bearer $TOKEN" -o shot.png

CI Integrations

Fresh macOS workers,
per job.

Official adapters connect CI platforms to JeballtoAgent. Each one handles platform setup, labels and cleanup while the agent owns VM lifecycle.

Runner controller

GitHub Actions

Prepares ephemeral macOS runners through the agent, verifies the runner toolchain and cleans idle VMs after jobs finish.

Custom executor

GitLab CI

Maps GitLab lifecycle hooks to VM create, prepare, run and cleanup calls against JeballtoAgent.

Cloud plugin

Jenkins

Provisions labeled macOS workers, applies capacity rules and shields jobs from host-level VM details.

CLI

Use the Python CLI for day-to-day agent operations: create VMs, pull images, run Jeballtofiles and inspect state from a shell.

Resources

Releases, docs
and source.

Stable entry points for every public component. Start with release notes, then move into deployed documentation or source code.

Agent

JeballtoAgent

Menu bar app, REST API, VM lifecycle, images, GUI, SSH and VNC.

Releases Docs Source

GitHub

Actions Runner

Ephemeral runner controller for GitHub Actions jobs.

Releases Docs Source

GitLab

GitLab Executor

Custom executor that provisions one macOS VM per CI job.

Releases Docs Source

Jenkins

Jenkins Plugin

Cloud plugin for labels, templates, capacity and provisioning.

Releases Docs Source

CLI

Python CLI

Operator tool for VMs, images and Jeballtofile automation.

Releases Docs Source

Versions

Match releases
across components.

Keep the agent, CI adapters and CLI on the same release line unless release notes say otherwise.

Version Matrix

Use matched beta versions unless release notes say otherwise.

JeballtoAgent	GitHub	GitLab	Jenkins	CLI
`1.0.0-beta.1`	`1.0.0-beta.1`	`1.0.0-beta.1`	`1.0.0-beta.1`	`1.0.0b1`

License

Open components,
same license.

Official public components use Mozilla Public License 2.0.

Mozilla Public License 2.0

JeballtoAgent, the official CI integrations and the Python CLI are published under MPL 2.0. Each source repository includes its own license file and notices.

JeballtoAgent GitHub Actions Runner GitLab Executor Jenkins Plugin Python CLI

Contact

Questions, bugs,
or implementation support.

Whether you are evaluating the agent, wiring it into CI or debugging a specific workflow, the best route depends on whether you need support, want to report a bug or want to talk implementation details.

General topics contact@jeballto.com

Bugs, feature requests and technical support support@jeballto.com

Commercial users and cooperations business@jeballto.com

Install the agent.
Drive it with code.

Download the menu bar app, copy the bearer token and bring up a fresh macOS VM through one clean endpoint.

Download for macOS View on GitHub

Public beta software. APIs and behavior may change before the stable release.

One local service.Full VM control.

Headless by default.

Build, boot,connect and reuse.

REST lifecycle

OCI images

SSH & VNC

Parallel VMs

Jeballtofile

Automatic install

Install, launch,make the first request.

Download the release

Move to Applications

Copy the token and call the API

Four callsto a running Mac.

Fresh macOS workers,per job.

GitHub Actions

GitLab CI

Jenkins

Releases, docsand source.

JeballtoAgent

Actions Runner

GitLab Executor

Jenkins Plugin

Python CLI

Match releasesacross components.

Open components,same license.

Questions, bugs,or implementation support.

Install the agent.Drive it with code.

One local service.
Full VM control.

Build, boot,
connect and reuse.

Install, launch,
make the first request.

Four calls
to a running Mac.

Fresh macOS workers,
per job.

Releases, docs
and source.

Match releases
across components.

Open components,
same license.

Questions, bugs,
or implementation support.

Install the agent.
Drive it with code.