How to pool your team's spare Macs and Linux boxes for builds and coding agents
A pool is a group of machines that a team or friends lend to each other for builds and coding agents. With Potluck, one machine runs the pool, other people join with one-time invite codes, and each job runs in a fresh VM or sandbox on whichever machine is free. A machine's owner chooses how much to share and can wind it down or stop it with one command.
What is a pool, and what do the words mean?
Potluck uses a few words, and these four matter most here:
- Pool. The group of machines you and your friends lend and use. One machine runs it, with
potluck create. - Host. A machine that shares some of itself with a pool, with
potluck host. It shares half of its cores and memory by default, which you change with--share. - Member. A person who runs sandboxes on the pool's machines.
- Sandbox. A fresh VM or container on a host, which you create, run commands in and remove.
Potluck has no accounts of its own. Machines reach each other over Tailscale by default, or over a tunnel you set up with --via tunnel.
Who can use whose machine?
The pool's owner decides, because every person and machine joins with a one-time invite code that the owner makes. There are two kinds of invite, and they are different roles:
| Invite | Command | What the person can do |
|---|---|---|
| Member | potluck invite sam | Runs sandboxes on the pool's machines. |
| Host, trusted | potluck invite carl --host | Shares a machine. Sees nothing else of the pool. |
| Host, public | potluck invite dee --host --trust public | Shares a machine as a stranger's. Sees nothing else of the pool. |
A host's trust is the owner's choice at invite time, and the machine cannot change it. The difference matters:
- A trusted machine, a friend's, has sandboxes placed on it without being asked. It may run GitHub Actions jobs and receive the secrets a member sends to a sandbox.
- A public machine, a stranger's, runs only sandboxes a member names with
--on. It never runs GitHub Actions jobs and never receives a secret.
Two limits are worth knowing before you invite anyone. The machine that runs a sandbox can read everything in it, including code, commands, output and secrets. The machine that runs the pool can read the commands, output and secrets passing through it, until commands are sealed to the host's key, and over --via tunnel so can the tunnel's provider. Join only a pool whose owner you would trust with that.
What does each job run in, and what can it reach?
Every job runs in a throwaway VM or isolated container, not on the host itself. Potluck's isolation document says the sandbox cannot reach the lending machine on any port (on Tart, apart from Softnet's DNS forwarder on the host), cannot reach its local network or its Tailscale network, cannot reach another sandbox running at the same time, cannot send mail, and holds none of the lender's credentials.
A lender can check this on their own machine:
potluck isolation test <machine>-c2m4
Sizes are matched by exact name, and potluck host names each one <machine>-<size> (potluck isolation lists the names this machine serves). The test boots sandboxes of that size and tries to reach this machine's addresses, the router, Tailscale's resolver and a second sandbox. It passes only if every check ran and failed to get through. On Linux, a sandbox that has a network relies on a firewall the machine's owner sets up.
How do you start a pool, step by step?
Step 1: Install and check the first machine
curl -fsSL https://raw.githubusercontent.com/sengirunners/potluck/main/install.sh | sh
potluck doctor
A Mac needs to be Apple silicon with Tart and Softnet. A Linux box needs Docker with Kata or gVisor. potluck doctor says what is missing.
Step 2: Create the pool and share this machine
potluck create friends
potluck host
The first potluck create with the Tailscale default prints a login link and waits for you to sign in. On a Mac, the first potluck host pulls a macOS image of about 27 GB and wants about 60 GB free.
Step 3: Invite people
potluck invite ana
potluck invite carl --host
Each prints a one-time code that works for 24 hours by default (--ttl changes it).
Step 4: Friends join and share
Ana runs potluck join '<code>' and can then create sandboxes. Carl runs potluck host '<code>' on the machine he lends. That command checks the machine, pulls the image, runs a quick conformance check per size, and joins only if a size passes. A machine that fails never joins, and the code stays unspent.
Step 5: Run work
potluck sandbox create --ref HEAD
potluck sandbox exec <id> --timeout 600 -- make test
potluck sandbox rm <id>
potluck run -- make test
potluck sandbox create picks the smallest shared size that fits. --ref HEAD sends your checkout's current commit in; without it the sandbox has no code and make test would run in an empty home directory. exec kills a command after 30 seconds unless you pass --timeout (at most 600), so for longer work use potluck run, whose limit is 30 minutes by default. potluck run creates a sandbox, sends your checkout's commit, runs the command and removes the sandbox. GitHub Actions jobs and coding agents use the same pool: see potluck runners and potluck agent-runner. To keep one group from using up everyone's time, potluck usage limit <area> <minutes> sets a minutes limit for an area, such as potluck usage limit team 600 --per week (day, week or month; a project owner or admin sets it).
How does a Mac owner take the machine back?
A Mac owner has three levels of control, and the second and third are single commands.
- Automatic. By default a Mac's sandbox ends when the owner touches the keyboard or pointer, and none starts until the Mac has been idle for five minutes.
--reclaim-idle-schanges the idle time, and0shares all the time. - Wind down.
potluck host set drainstops new work. Running work finishes and is cut after 30 minutes by default.--deadline 10mchanges the limit. - Stop now.
potluck host set closedrefuses new work and ends running work immediately.
potluck host set drain
potluck host set closed
potluck host set auto
auto returns to the machine's own rules. --for 2h and --until 23:00 return the machine to auto at a set time. On a Mac there is also a menu bar item with Wind down and Stop now entries. Install it with curl -fsSL https://raw.githubusercontent.com/sengirunners/potluck/main/install.sh | sh -s -- --menubar, which installs the app but does not start it, then open it with open ~/Applications/"Potluck Menu.app". It is not yet signed with an Apple Developer ID.
To stop sharing for good, potluck host stop removes every size the machine shared, and potluck leave leaves the pool.
Can you lend a Mac?
Apple's macOS software license agreement (read November 2026) allows up to two macOS VMs per Mac you own or control, and Potluck caps macOS guests at two. The README's rule is that lending a macOS VM to your team or invited friends is fine and selling Mac time to the public is not. Read the licence yourself; this is not legal advice.
FAQ
Is it a cluster scheduler?
No. Potluck runs builds, GitHub Actions jobs and coding agents in VMs and containers on ordinary Macs and Linux boxes, and its README says it is not a scheduler for clusters.
Can I join a pool as a friend without giving access to my files?
Yes. A job runs in a throwaway sandbox that is meant to be walled off from your machine, its network and your credentials, and potluck isolation test <machine>-c2m4 checks that by sample on your machine. You still trust the pool's owner with what the pool's machine can read.
Can strangers use my machine?
Only people the pool's owner invites as members can run sandboxes on it, and each invite code works once. A stranger's machine can share with the pool only through --trust public, which gives it no secrets and no GitHub Actions jobs.
What if my machine goes to sleep or reboots?
On a Mac, Potluck keeps the Mac from idle sleep while a VM runs, though the display may still sleep. With FileVault on, a Mac that reboots runs nothing until its owner logs in. VMs end at their deadline even if the daemon is down.
Is it a volunteer-computing network?
No. Potluck runs a team's own builds, GitHub Actions jobs and coding agents on machines the team or its invited friends already own. Nothing goes to people the pool's owner has not invited.
Does it cost anything?
Potluck is open source under Apache-2.0 and has no price. Each owner pays for their own machine and power. Jobs on a pool's machines use none of GitHub's minutes; how GitHub bills Actions minutes explains what they would cost on GitHub's runners.
Code and docs: github.com/sengirunners/potluck