Skip to main content
This page takes a Mac that already meets the hosting requirements and makes it a Darkbloom Sandbox host. Setup installs the add-on in ~/DarkbloomSandbox, enrolls the Mac, and downloads the VM images in the background.
1

Install the add-on

With the Darkbloom provider CLI, update to 0.10.5 or later, then run setup:
Setup checks the Mac and asks before it changes anything. Without the CLI, run the add-on’s installer directly:
Setup refuses sudo. Run it as your own user, logged in at the desktop.Arguments go to the installer after sh -s --. For example:
2

Read the plan

Setup prints the cores, memory and disk it counted, how many Linux and macOS jobs the Mac can run at a time, and what limited them. With darkbloom sandbox setup, nothing is installed until you answer y.To see the plan without installing anything:
If no job fits, setup says how much disk one Linux job and one macOS job would need, and stops.
3

Approve the Mac

The installer opens the console’s device page with the Mac’s code filled in, and prints the link and code as well. Sign in with the Darkbloom account that should receive the earnings, check that the Mac and code are yours, and press Approve this Mac.
Sandbox console enrollment request page showing the code, the Mac's model and add-on version, and what approving does

The enrollment request page in the sandbox console: check the code and the Mac, then approve it. Example data.

Approve within 15 minutes, or the code expires and you run setup again for a new one. In add-on releases after 1.3.3, the installer also shows the time the code expires. Add --no-browser to print the link without opening a browser.If the account is not approved yet, the request joins a waitlist and the Mac waits; see waitlist and approval. From add-on 1.2.0 you can close the setup window, and the Mac keeps waiting across restarts and macOS updates.If the Mac hosted before, its code replaces the old host. The installer says which, and the approval page asks you to confirm the replacement: tick I am re-enrolling …, then Approve & replace.
4

Let the images download

After enrollment the agent starts, and the Mac downloads its VM images in the background: about 3 GB for Linux and 45 GB for macOS. On a Mac that runs only Linux jobs, that is the 3 GB. At 100 Mbps the macOS image takes about an hour.The Mac takes jobs once an image is installed. Add --wait-ready to setup to keep it open until then, or follow the download with darkbloom sandbox status. Getting no job in the first hour is normal.

What the plan counts

The installer sizes the slots from the Mac’s cores, memory and free disk. It prints the slots it chose and what limited them.
  • The owner keeps a quarter of the cores (at least 2) and a quarter of the memory (at least 8 GB). If the inference provider runs, it keeps another quarter of the memory.
  • A slot takes the smaller runner class of its platform: Linux 4 cores and 16 GB, macOS 8 cores and 16 GB.
  • Slots go out Linux, macOS, Linux, macOS, then Linux, while cores, memory and disk last.
  • macOS has at most 2 slots, the kernel’s limit, which counts your own macOS VMs too. Linux has at most 16.
  • Disk gives each Linux slot its job’s 30 GiB scratch disk, each macOS slot its job’s 40 GiB write budget, and the first slot of a platform its images (4 GiB for Linux, 46 GiB for macOS) unless they are already installed.
Slots are counted at the smaller VM size. Darkbloom places each job by the cores, memory and disk the Mac reports free at that moment, so a larger job needs more room. The plan names what stopped the hand-out from giving a platform another slot: free disk space, cores, memory, the 16-slot maximum, macOS's limit of 2 VMs, yours included, or your choice when you set the count.

Choose the number of slots

Ask for fewer jobs with --linux-slots and --macos-slots. Linux takes 0 to 16 and macOS 0 to 2; both 0 is refused.
  • --macos-slots 1 keeps one of macOS’s two macOS VMs for your own use.
  • --macos-slots 0 keeps both.
  • --linux-slots 0 gives macOS the whole disk.
Running setup again recomputes the slots, so give your options again each time. A rerun keeps the enrollment, rewrites agent.json, and restarts the agent only if something changed. Rerunning is always safe: if anything fails, the installer puts back what ran before, and it never moves a Mac to an older release.

Disk budget

The add-on keeps its images and jobs in ~/DarkbloomSandbox, on the disk that holds your home folder, or on the work disks you give it.
  • Floor. Darkbloom keeps a floor of free space: a tenth of the disk, at least 50 GiB and at most 100 GiB (54 to 107 GB). No job starts, and no image downloads, if that could push free space below the floor.
  • Images. About 3 GB for Linux and 45 GB for macOS. A Mac downloads only the images of the jobs it runs. They download at setup and again when Darkbloom updates an image, and for a while both copies stay on the disk. Most macOS updates (the GitHub runner, Darkbloom’s own guest software) replace only a 0.5 GB part of the macOS image; a new macOS or Xcode version replaces the 45 GB disk.
  • Linux jobs. Each Linux slot needs 30 GiB (32 GB) above the floor for its job’s scratch disk, also while images download.
  • macOS jobs. Each macOS slot needs 40 GiB (43 GB) above the floor, the most a macOS job is expected to write, also while images download. That room is all a macOS job needs to start: its VM’s disk is 150 GiB (161 GB), but takes only what the job writes.
  • Guard. If free space still falls below the floor while jobs run, the add-on stops the running jobs within about 10 seconds and deletes what they wrote. Darkbloom runs those jobs elsewhere.
  • Agent sandbox images. With agent sandboxes on, the Linux sandbox image takes 10 GiB, which the installer keeps room for. On Macs that run macOS jobs the macOS one takes about 46 GiB: that image downloads only into the space left beyond the floor, the slots’ room and your CI images, and the Mac offers macOS sandboxes once it is in.
When it sizes the slots, the installer counts for the first slot of each kind its images too, rounded up (4 GiB for Linux, 46 GiB for macOS), unless they are already on the Mac. A job uses only the space it writes and frees it when it ends. For example, a 2 TB disk keeps a floor of 100 GiB (107 GB). With 157 GiB (169 GB) free before you install, a Mac gets one Linux slot and a 23 GiB build cache. With 220 GiB (236 GB) free, it gets a Linux and a macOS slot if its cores and memory allow, and no build cache until about 8 GiB more is free. If free space falls after you install and an image no longer fits, that image waits and the others still download, so their slots take jobs. status names the image and how much space to free, or run the installer again to fit the slots to the space you have.

Work disks

If the internal disk is what limits the Mac, give the images and jobs one or more other disks. The add-on itself, its settings and logs stay in ~/DarkbloomSandbox.
  1. Use a fast drive: a Thunderbolt or USB4 NVMe SSD. Every job reads its VM image and writes its scratch disk there, and a macOS image is 45 GB, so a spinning disk, a USB-A flash drive or a network share makes every job slow (network shares are refused). Use a drive the Mac keeps powered and connected. A job running on a drive that goes away is stopped and run elsewhere, unpaid.
  2. Format it as APFS in Disk Utility. ExFAT, FAT and Mac OS Extended (HFS+) drives are refused, and so is a disk image: its space is the disk that holds its file.
  3. Turn on ownership, which macOS leaves off for external drives:
  4. Give the drive to the installer. Repeat --disk for more drives, and add --disk ~ to keep using the internal disk too:
    Setup checks each drive before it installs anything. When ownership is off, it prints the command and offers to run it. Add --plan first to see what each disk would get.
Each disk keeps its own floor of free space (a tenth of the disk, 50 to 100 GiB) and holds the images of the jobs it runs: Darkbloom downloads an image once and copies it to the other disks that need it. The add-on uses a folder named DarkbloomSandbox at the top of each drive and nothing else on it. If you unplug a drive, its slots stop taking jobs and nothing is written in its place. Plug it back in and they take jobs again once the add-on has checked the images on it. A drive that mounts after you log in is used as soon as it appears. status shows each disk, its free space and its slots.

An ExFAT drive

To keep an ExFAT drive’s files, let the add-on make one encrypted disk image on it (a single file at its top; nothing is erased), and give that disk to the installer:
It prints the --disk to give. Its key stays on this Mac, and uninstall needs --delete-managed-disks to delete it with the install.

Build cache

From add-on 1.2.1 your Mac keeps a build cache for the jobs it runs, on by default. A job restores its dependencies and build outputs from your disk instead of downloading them over your connection, and saves them there for the next job.
  • It takes up to 32 GiB on a 1 TB disk (16 GiB on 512 GB, 8 GiB on smaller ones), and only what the slots leave: never the floor, never a slot’s room.
  • With less than 8 GiB left, it stays off, and status says how much to free.
  • It gives way to jobs and images at once, deleting its oldest entries.
  • What it holds is encrypted inside the VM before it reaches your disk.
To size it or turn it off, run the installer with --cache-size 16 (GiB) or --no-cache. Without either, an earlier install’s size stays; a new install uses the default for its disk.

Scheduling and pause

To stop taking new work for a while:
No new job starts, and no agent sandbox starts or resumes on the Mac; jobs already running finish and are paid. The Mac stays paused after restarts and updates, and the console shows it as Paused by owner. You do not need to sign in. Without the CLI, use ~/DarkbloomSandbox/darkbloom-sandbox pause and resume. To take jobs only in the hours you choose, set a weekly schedule in the Mac’s local time:
Days are mon … sun, ranges such as mon-fri, or daily, weekdays, weekends; an end before the start runs past midnight. Outside every window no new job starts; a job still running when a window ends finishes. status and the console show Paused by schedule until the next window.

Agent sandboxes

Agent sandboxes are on by default from add-on 1.3.0. Their workspaces live in the same store as the build cache, with their own allowance: 96 GiB by default, set with the installer’s --workspace-size. Each workspace takes its disk’s room when it is created, and the room it may still grow into is kept beside CI jobs. To turn agent sandboxes off, run the installer again with --no-agent-sessions. Later installs and updates keep them off, and CI jobs do not change.
To stop new work only for a while, use pause or a schedule. They stop new CI jobs and new sandboxes alike.

Updates

Updates are automatic. When Darkbloom approves a new release, the agent hears about it over its connection and checks within about two minutes; otherwise it checks every five minutes. (Add-on 1.2.0 and earlier check every hour.) Darkbloom may approve a release for some Macs before others. The agent installs a release only if all of these hold:
  • The app is signed with Darkbloom’s Apple Developer ID, and the release is signed with Darkbloom’s release key, which the installed app pins.
  • The release is newer than the running version and supports your macOS version.
  • Darkbloom’s servers already accept that build for your Mac.
The agent then stops taking jobs and waits for the running ones to finish. After that it swaps the app and restarts. You do not need to enroll again. If the new version does not connect to Darkbloom within three starts, or Darkbloom refuses it, the agent goes back to the previous version and skips the new one from then on. status shows the last check.

Uninstall

Pause first and wait until status shows no job running: uninstalling stops the agent and any running job, and a stopped job is not paid.
The add-on’s own command is ~/DarkbloomSandbox/darkbloom-sandbox uninstall. It removes ~/DarkbloomSandbox (the app, images and state, except the workspaces it keeps), each work disk’s DarkbloomSandbox folder (only while that disk is mounted; it says which stays), and the LaunchAgent. Uninstalling keeps the agent sandbox workspaces the Mac stores (add-on releases after 1.3.8). A workspace holds the files of someone’s sandbox, stopped or running. It exists on your Mac alone, so deleting it cannot be undone. uninstall prints how many it kept, how much disk they use and where they are:
  • The disk space printed as used is what they cost you. If you set the Mac up again the same way (the same disks), it finds them, and until you delete them they count against its workspace allowance, so it takes fewer new sandboxes. The room they may still grow into is also kept from its CI jobs, so it may take fewer CI jobs too.
  • Today no sandbox can resume from a kept workspace, not even on this Mac set up again: Darkbloom sees that Mac as a new one. Keeping the workspace is what will let it resume once Darkbloom supports that. Darkbloom ends a sandbox that stays stopped for 30 days; after that its workspace is of no use to anyone, and nothing deletes it for you yet.
  • To delete them as you uninstall, add --delete-workspaces. --yes alone never deletes them.
After an uninstall, the Mac stays registered to your account but gets no work. To revoke it, remove it in the console: Macs, then the Mac, then Remove Mac. A removed Mac’s sandboxes can never resume. The Mac’s keychain keeps which host it was, so setting it up again replaces that host instead of adding a second one; you confirm the replacement when you approve the code. To make the Mac forget it, add --forget:
For a Mac that is no longer enrolled and fails to approve a replacement code, see check your Mac’s status.