<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>https://potluck.sh/blog</id>
  <title>Potluck blog</title>
  <subtitle>Guides and notes on running GitHub Actions jobs and coding agents on your team's idle machines, from the people who make Potluck.</subtitle>
  <link rel="alternate" type="text/html" href="https://potluck.sh/blog"/>
  <link rel="self" type="application/atom+xml" href="https://potluck.sh/feed.xml"/>
  <updated>2026-11-19T00:00:00Z</updated>
  <author><name>Sengi</name></author>
  <entry>
    <id>https://potluck.sh/blog/pool-spare-macs-and-linux-boxes-for-builds-and-agents</id>
    <title>How to pool your team's spare Macs and Linux boxes for builds and coding agents</title>
    <link rel="alternate" type="text/html" href="https://potluck.sh/blog/pool-spare-macs-and-linux-boxes-for-builds-and-agents"/>
    <published>2026-11-16T00:00:00Z</published>
    <updated>2026-11-19T00:00:00Z</updated>
    <author><name>Sengi</name></author>
    <summary>How a pool of a team's or friends' spare computers works: who can use whose machine, what a machine owner shares, and how a Mac owner takes it back.</summary>
    <content type="html">&lt;p&gt;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.&lt;/p&gt;
&lt;h2 id=&quot;what-is-a-pool-and-what-do-the-words-mean&quot;&gt;What is a pool, and what do the words mean?&lt;/h2&gt;
&lt;p&gt;Potluck uses a few words, and these four matter most here:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pool.&lt;/strong&gt; The group of machines you and your friends lend and use. One machine runs it, with &lt;code&gt;potluck create&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Host.&lt;/strong&gt; A machine that shares some of itself with a pool, with &lt;code&gt;potluck host&lt;/code&gt;. It shares half of its cores and memory by default, which you change with &lt;code&gt;--share&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Member.&lt;/strong&gt; A person who runs sandboxes on the pool's machines.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Sandbox.&lt;/strong&gt; A fresh VM or container on a host, which you create, run commands in and remove.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Potluck has no accounts of its own. Machines reach each other over Tailscale by default, or over a tunnel you set up with &lt;code&gt;--via tunnel&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;who-can-use-whose-machine&quot;&gt;Who can use whose machine?&lt;/h2&gt;
&lt;p&gt;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:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Invite&lt;/th&gt;&lt;th&gt;Command&lt;/th&gt;&lt;th&gt;What the person can do&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;Member&lt;/td&gt;&lt;td&gt;&lt;code&gt;potluck invite sam&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Runs sandboxes on the pool's machines.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Host, trusted&lt;/td&gt;&lt;td&gt;&lt;code&gt;potluck invite carl --host&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Shares a machine. Sees nothing else of the pool.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Host, public&lt;/td&gt;&lt;td&gt;&lt;code&gt;potluck invite dee --host --trust public&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Shares a machine as a stranger's. Sees nothing else of the pool.&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;A host's trust is the owner's choice at invite time, and the machine cannot change it. The difference matters:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A &lt;strong&gt;trusted&lt;/strong&gt; machine, a friend's, has sandboxes placed on it without being asked. It may run &lt;a href=&quot;/github-actions-runner&quot;&gt;GitHub Actions jobs&lt;/a&gt; and receive the secrets a member sends to a sandbox.&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;public&lt;/strong&gt; machine, a stranger's, runs only sandboxes a member names with &lt;code&gt;--on&lt;/code&gt;. It never runs GitHub Actions jobs and never receives a secret.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;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 &lt;code&gt;--via tunnel&lt;/code&gt; so can the tunnel's provider. Join only a pool whose owner you would trust with that.&lt;/p&gt;
&lt;h2 id=&quot;what-does-each-job-run-in-and-what-can-it-reach&quot;&gt;What does each job run in, and what can it reach?&lt;/h2&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;p&gt;A lender can check this on their own machine:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck isolation test &amp;lt;machine&amp;gt;-c2m4
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Sizes are matched by exact name, and &lt;code&gt;potluck host&lt;/code&gt; names each one &lt;code&gt;&amp;lt;machine&amp;gt;-&amp;lt;size&amp;gt;&lt;/code&gt; (&lt;code&gt;potluck isolation&lt;/code&gt; 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.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-start-a-pool-step-by-step&quot;&gt;How do you start a pool, step by step?&lt;/h2&gt;
&lt;h3 id=&quot;step-1-install-and-check-the-first-machine&quot;&gt;Step 1: Install and check the first machine&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;curl -fsSL https://raw.githubusercontent.com/sengirunners/potluck/main/install.sh | sh
potluck doctor
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A Mac needs to be Apple silicon with &lt;a href=&quot;/tart&quot;&gt;Tart&lt;/a&gt; and Softnet. A Linux box needs Docker with Kata or gVisor. &lt;code&gt;potluck doctor&lt;/code&gt; says what is missing.&lt;/p&gt;
&lt;h3 id=&quot;step-2-create-the-pool-and-share-this-machine&quot;&gt;Step 2: Create the pool and share this machine&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck create friends
potluck host
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The first &lt;code&gt;potluck create&lt;/code&gt; with the Tailscale default prints a login link and waits for you to sign in. On a Mac, the first &lt;code&gt;potluck host&lt;/code&gt; pulls a macOS image of about 27 GB and wants about 60 GB free.&lt;/p&gt;
&lt;h3 id=&quot;step-3-invite-people&quot;&gt;Step 3: Invite people&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck invite ana
potluck invite carl --host
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Each prints a one-time code that works for 24 hours by default (&lt;code&gt;--ttl&lt;/code&gt; changes it).&lt;/p&gt;
&lt;h3 id=&quot;step-4-friends-join-and-share&quot;&gt;Step 4: Friends join and share&lt;/h3&gt;
&lt;p&gt;Ana runs &lt;code&gt;potluck join '&amp;lt;code&amp;gt;'&lt;/code&gt; and can then create sandboxes. Carl runs &lt;code&gt;potluck host '&amp;lt;code&amp;gt;'&lt;/code&gt; 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.&lt;/p&gt;
&lt;h3 id=&quot;step-5-run-work&quot;&gt;Step 5: Run work&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck sandbox create --ref HEAD
potluck sandbox exec &amp;lt;id&amp;gt; --timeout 600 -- make test
potluck sandbox rm &amp;lt;id&amp;gt;
potluck run -- make test
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;potluck sandbox create&lt;/code&gt; picks the smallest shared size that fits. &lt;code&gt;--ref HEAD&lt;/code&gt; sends your checkout's current commit in; without it the sandbox has no code and &lt;code&gt;make test&lt;/code&gt; would run in an empty home directory. &lt;code&gt;exec&lt;/code&gt; kills a command after 30 seconds unless you pass &lt;code&gt;--timeout&lt;/code&gt; (at most 600), so for longer work use &lt;code&gt;potluck run&lt;/code&gt;, whose limit is 30 minutes by default. &lt;code&gt;potluck run&lt;/code&gt; 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 &lt;code&gt;potluck runners&lt;/code&gt; and &lt;code&gt;potluck agent-runner&lt;/code&gt;. To keep one group from using up everyone's time, &lt;code&gt;potluck usage limit &amp;lt;area&amp;gt; &amp;lt;minutes&amp;gt;&lt;/code&gt; sets a minutes limit for an area, such as &lt;code&gt;potluck usage limit team 600 --per week&lt;/code&gt; (day, week or month; a project owner or admin sets it).&lt;/p&gt;
&lt;h2 id=&quot;how-does-a-mac-owner-take-the-machine-back&quot;&gt;How does a Mac owner take the machine back?&lt;/h2&gt;
&lt;p&gt;A Mac owner has three levels of control, and the second and third are single commands.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Automatic.&lt;/strong&gt; 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. &lt;code&gt;--reclaim-idle-s&lt;/code&gt; changes the idle time, and &lt;code&gt;0&lt;/code&gt; shares all the time.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Wind down.&lt;/strong&gt; &lt;code&gt;potluck host set drain&lt;/code&gt; stops new work. Running work finishes and is cut after 30 minutes by default. &lt;code&gt;--deadline 10m&lt;/code&gt; changes the limit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Stop now.&lt;/strong&gt; &lt;code&gt;potluck host set closed&lt;/code&gt; refuses new work and ends running work immediately.&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck host set drain
potluck host set closed
potluck host set auto
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;auto&lt;/code&gt; returns to the machine's own rules. &lt;code&gt;--for 2h&lt;/code&gt; and &lt;code&gt;--until 23:00&lt;/code&gt; return the machine to &lt;code&gt;auto&lt;/code&gt; at a set time. On a Mac there is also a menu bar item with Wind down and Stop now entries. Install it with &lt;code&gt;curl -fsSL https://raw.githubusercontent.com/sengirunners/potluck/main/install.sh | sh -s -- --menubar&lt;/code&gt;, which installs the app but does not start it, then open it with &lt;code&gt;open ~/Applications/&amp;quot;Potluck Menu.app&amp;quot;&lt;/code&gt;. It is not yet signed with an Apple Developer ID.&lt;/p&gt;
&lt;p&gt;To stop sharing for good, &lt;code&gt;potluck host stop&lt;/code&gt; removes every size the machine shared, and &lt;code&gt;potluck leave&lt;/code&gt; leaves the pool.&lt;/p&gt;
&lt;h2 id=&quot;can-you-lend-a-mac&quot;&gt;Can you lend a Mac?&lt;/h2&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;h2 id=&quot;faq&quot;&gt;FAQ&lt;/h2&gt;
&lt;h3 id=&quot;is-it-a-cluster-scheduler&quot;&gt;Is it a cluster scheduler?&lt;/h3&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;h3 id=&quot;can-i-join-a-pool-as-a-friend-without-giving-access-to-my-files&quot;&gt;Can I join a pool as a friend without giving access to my files?&lt;/h3&gt;
&lt;p&gt;Yes. A job runs in a throwaway sandbox that is meant to be walled off from your machine, its network and your credentials, and &lt;code&gt;potluck isolation test &amp;lt;machine&amp;gt;-c2m4&lt;/code&gt; checks that by sample on your machine. You still trust the pool's owner with what the pool's machine can read.&lt;/p&gt;
&lt;h3 id=&quot;can-strangers-use-my-machine&quot;&gt;Can strangers use my machine?&lt;/h3&gt;
&lt;p&gt;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 &lt;code&gt;--trust public&lt;/code&gt;, which gives it no secrets and no GitHub Actions jobs.&lt;/p&gt;
&lt;h3 id=&quot;what-if-my-machine-goes-to-sleep-or-reboots&quot;&gt;What if my machine goes to sleep or reboots?&lt;/h3&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;h3 id=&quot;is-it-a-volunteer-computing-network&quot;&gt;Is it a volunteer-computing network?&lt;/h3&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;h3 id=&quot;does-it-cost-anything&quot;&gt;Does it cost anything?&lt;/h3&gt;
&lt;p&gt;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; &lt;a href=&quot;https://sengi.run/blog/github-actions-billing-explained&quot;&gt;how GitHub bills Actions minutes&lt;/a&gt; explains what they would cost on GitHub's runners.&lt;/p&gt;
&lt;p&gt;Code and docs: &lt;a href=&quot;https://github.com/sengirunners/potluck&quot;&gt;github.com/sengirunners/potluck&lt;/a&gt;&lt;/p&gt;</content>
  </entry>
  <entry>
    <id>https://potluck.sh/blog/self-hosted-github-actions-runner-on-your-mac</id>
    <title>How to run a self-hosted GitHub Actions runner on your own Mac, with a fresh VM for each job</title>
    <link rel="alternate" type="text/html" href="https://potluck.sh/blog/self-hosted-github-actions-runner-on-your-mac"/>
    <published>2026-11-16T00:00:00Z</published>
    <updated>2026-11-19T00:00:00Z</updated>
    <author><name>Sengi</name></author>
    <summary>Run GitHub Actions jobs on your own Mac or Mac mini, each in a fresh throwaway VM, so one job never touches your files or the next job.</summary>
    <content type="html">&lt;p&gt;You can run GitHub Actions jobs on a Mac you own by registering it as a self-hosted runner, but a plain runner runs every job directly on that Mac, so jobs share its files, its keychain and each other's leftovers. Potluck runs each job in its own fresh VM on your Mac or Mac mini and deletes the VM when the job ends. It is open source (Apache-2.0), and you set it up with a handful of commands.&lt;/p&gt;
&lt;h2 id=&quot;why-is-a-plain-self-hosted-runner-on-your-mac-risky&quot;&gt;Why is a plain self-hosted runner on your Mac risky?&lt;/h2&gt;
&lt;p&gt;A standard self-hosted runner is a program on your Mac that runs each job directly on it. GitHub's own guidance (GitHub Docs, &amp;quot;Secure use reference&amp;quot;, read November 2026) says self-hosted runners &amp;quot;do not have guarantees around running in ephemeral clean virtual machines&amp;quot; and &amp;quot;should almost never be used for public repositories&amp;quot;, because anyone can open a pull request and compromise the environment.&lt;/p&gt;
&lt;p&gt;Three things follow from that:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A job can read what your Mac holds.&lt;/strong&gt; Your other projects, your shell history, your SSH keys and any signed-in accounts are all inside the job's reach.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Jobs leave things behind.&lt;/strong&gt; A cache, a changed setting or a background process from one job can change the next, so a build passes or fails depending on what ran before it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A bad pull request can damage the Mac.&lt;/strong&gt; Workflow code runs with the runner's permissions.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A plain runner is therefore a poor fit for a Mac you also sit at.&lt;/p&gt;
&lt;h2 id=&quot;what-does-a-fresh-vm-for-each-job-change&quot;&gt;What does a fresh VM for each job change?&lt;/h2&gt;
&lt;p&gt;A fresh VM changes where the job runs. Instead of running on your Mac, the job runs inside a virtual machine that Potluck starts for that one job and deletes afterward. Nothing the job writes survives, and the next job starts from the same clean image.&lt;/p&gt;
&lt;p&gt;Potluck's isolation claim (docs/isolation.md in the repository) is that a job's VM cannot reach the lending Mac 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 VM running at the same time, cannot send mail, and holds none of your credentials. &lt;code&gt;potluck isolation test&lt;/code&gt; checks the host, local network, Tailscale network and second-VM claims by sample on your own machine; &lt;code&gt;potluck host&lt;/code&gt; checks mail.&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;Plain self-hosted runner&lt;/th&gt;&lt;th&gt;Potluck, a fresh VM per job&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;Where a job runs&lt;/td&gt;&lt;td&gt;Directly on your Mac&lt;/td&gt;&lt;td&gt;A VM on your Mac&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Clean state for each job&lt;/td&gt;&lt;td&gt;Not guaranteed (GitHub Docs, read November 2026)&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Can reach your files and keychain&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Can reach your local network&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;
&lt;h2 id=&quot;how-does-potluck-run-one-job-in-one-vm&quot;&gt;How does Potluck run one job in one VM?&lt;/h2&gt;
&lt;p&gt;Potluck has a broker that watches for queued jobs in the GitHub repositories you connect. For each queued job it does this:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;It asks GitHub for a one-job runner registration for that repository.&lt;/li&gt;
&lt;li&gt;It starts a box, which is a fresh VM on one of the pool's machines (Tart VMs on a Mac), and hands the registration to the runner inside it.&lt;/li&gt;
&lt;li&gt;The runner takes that one job. A GitHub runner of this kind takes one job only, so when the job ends the runner and its VM are removed.&lt;/li&gt;
&lt;li&gt;A job-started hook inside the VM checks the job against the repository's rules and stops it if the rules refuse it.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Only code from people who can push to the repository is served. For a public repository, Potluck serves only its own branches, and pull requests from forks are never served. For a private repository, forks are refused unless you turn on &lt;code&gt;allow_fork_prs&lt;/code&gt; in the broker's config.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-set-it-up-step-by-step&quot;&gt;How do you set it up, step by step?&lt;/h2&gt;
&lt;p&gt;You need an Apple-silicon Mac with &lt;a href=&quot;/tart&quot;&gt;Tart&lt;/a&gt; and Softnet installed. The first &lt;code&gt;potluck host&lt;/code&gt; on a Mac pulls a macOS image of about 27 GB and wants about 60 GB free. Linux boxes with Docker and Kata or gVisor work too, for Linux jobs.&lt;/p&gt;
&lt;h3 id=&quot;step-1-install-potluck&quot;&gt;Step 1: Install Potluck&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;curl -fsSL https://raw.githubusercontent.com/sengirunners/potluck/main/install.sh | sh
&lt;/code&gt;&lt;/pre&gt;
&lt;h3 id=&quot;step-2-check-what-the-mac-can-share&quot;&gt;Step 2: Check what the Mac can share&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;potluck doctor&lt;/code&gt; lists what is missing and prints the one &lt;code&gt;sudo&lt;/code&gt; line it still needs.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck doctor
&lt;/code&gt;&lt;/pre&gt;
&lt;h3 id=&quot;step-3-start-a-pool-on-this-mac&quot;&gt;Step 3: Start a pool on this Mac&lt;/h3&gt;
&lt;p&gt;A pool is the group of machines that run your jobs. With one machine, the pool and the host are the same computer.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck create ci --via tunnel
&lt;/code&gt;&lt;/pre&gt;
&lt;h3 id=&quot;step-4-share-the-mac-with-the-pool&quot;&gt;Step 4: Share the Mac with the pool&lt;/h3&gt;
&lt;p&gt;On a Mac you sit at, a job ends when you touch the keyboard or pointer, and new jobs start only after five idle minutes. A Mac mini nobody sits at can share all the time:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck host --reclaim-idle-s 0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;For Xcode jobs, &lt;code&gt;potluck host --with xcode&lt;/code&gt; lends the pinned Cirrus Labs Xcode image instead of the base one, and the job asks for the extra label &lt;code&gt;xcode&lt;/code&gt;. That image is a 67.5 GB download and wants about 200 GB free.&lt;/p&gt;
&lt;h3 id=&quot;step-5-turn-on-the-runner-broker&quot;&gt;Step 5: Turn on the runner broker&lt;/h3&gt;
&lt;p&gt;Creating and linking the GitHub App needs an https address that your browser is sent back to, which you forward to the listener Potluck opens. Serving jobs does not need it: with no public address the broker asks GitHub for queued jobs every 15 seconds.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck runners setup ci --url https://runners.example.com --repo acme/app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The command prints one URL. Open it to create a private GitHub App, install the App, and sign in to say yes to linking it. The App is private and installs only on the account that owns it, so add &lt;code&gt;--org acme&lt;/code&gt; to create it under an organization when the jobs belong to one.&lt;/p&gt;
&lt;h3 id=&quot;step-6-connect-each-repository&quot;&gt;Step 6: Connect each repository&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck runners allow acme/app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A public repository needs &lt;code&gt;--public&lt;/code&gt;, which is your yes to serve its own branches.&lt;/p&gt;
&lt;h3 id=&quot;step-7-point-a-job-at-the-pool&quot;&gt;Step 7: Point a job at the pool&lt;/h3&gt;
&lt;p&gt;The label is the pool's name, and a Mac job names &lt;code&gt;macos&lt;/code&gt;:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-yaml&quot;&gt;jobs:
  build:
    runs-on: [self-hosted, macos, ci]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Or let Potluck prepare the edit: &lt;code&gt;potluck ci pr acme/app&lt;/code&gt; changes one job's &lt;code&gt;runs-on&lt;/code&gt; from a GitHub-hosted macOS label and prints a script that opens the pull request. The change keeps GitHub's runner for fork pull requests.&lt;/p&gt;
&lt;h3 id=&quot;step-8-push-a-commit-and-look-at-what-the-broker-did&quot;&gt;Step 8: Push a commit and look at what the broker did&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck runners jobs
potluck ci doctor acme/app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;potluck ci doctor&lt;/code&gt; is read-only. It runs numbered checks and gives one next step for each failure.&lt;/p&gt;
&lt;p&gt;To add more machines later, the pool needs a way for them to reach this one. A pool made with &lt;code&gt;--via tunnel&lt;/code&gt; and no tunnel configured works on this machine alone. A second machine needs either Tailscale (run &lt;code&gt;potluck create ci&lt;/code&gt; again without &lt;code&gt;--via tunnel&lt;/code&gt;, which is safe on an existing pool and brings Tailscale up, then &lt;code&gt;potluck invite &amp;lt;name&amp;gt; --host&lt;/code&gt;) or a tunnel you configure in &lt;code&gt;~/.potluck/config.json&lt;/code&gt; (see the README's &amp;quot;A tunnel instead of Tailscale&amp;quot;, then &lt;code&gt;potluck invite &amp;lt;name&amp;gt; --host --via tunnel --pool ci&lt;/code&gt;). On the other machine, run &lt;code&gt;potluck host '&amp;lt;code&amp;gt;'&lt;/code&gt;. Jobs go to whichever machine is free.&lt;/p&gt;
&lt;h2 id=&quot;what-does-the-mac-license-allow&quot;&gt;What does the Mac license allow?&lt;/h2&gt;
&lt;p&gt;Apple's macOS software license agreement (read November 2026) allows up to two macOS VMs on a Mac you own or control for uses such as development and testing, and its licence does not allow time-sharing or service-bureau use. The Potluck README's rule is that lending a macOS guest to your team or invited friends is fine and selling Mac time to the public is not. Potluck caps macOS guests at two per Mac. Read the license yourself; this is not legal advice.&lt;/p&gt;
&lt;p&gt;How the runner picks and refuses jobs is on the &lt;a href=&quot;/github-actions-runner&quot;&gt;self-hosted GitHub Actions runner&lt;/a&gt; page.&lt;/p&gt;
&lt;h2 id=&quot;faq&quot;&gt;FAQ&lt;/h2&gt;
&lt;h3 id=&quot;can-i-use-a-mac-mini-as-a-github-actions-runner&quot;&gt;Can I use a Mac mini as a GitHub Actions runner?&lt;/h3&gt;
&lt;p&gt;Yes, if it is Apple silicon. Install Potluck, run &lt;code&gt;potluck create&lt;/code&gt; and &lt;code&gt;potluck host --reclaim-idle-s 0&lt;/code&gt;, and each job runs in a fresh Tart VM on the mini.&lt;/p&gt;
&lt;h3 id=&quot;does-every-job-really-get-a-new-vm&quot;&gt;Does every job really get a new VM?&lt;/h3&gt;
&lt;p&gt;Yes. The broker registers a one-job runner, starts a new box for it, and removes the runner and the box when the job ends. A VM does not carry files from one job to the next.&lt;/p&gt;
&lt;h3 id=&quot;can-a-pull-request-from-a-fork-run-on-my-mac&quot;&gt;Can a pull request from a fork run on my Mac?&lt;/h3&gt;
&lt;p&gt;Not by default. A fork's pull request is never served for a public repository, and for a private one it is refused unless you set &lt;code&gt;allow_fork_prs&lt;/code&gt; in the broker's config.&lt;/p&gt;
&lt;h3 id=&quot;do-i-need-tailscale&quot;&gt;Do I need Tailscale?&lt;/h3&gt;
&lt;p&gt;No. A pool on one machine can use &lt;code&gt;--via tunnel&lt;/code&gt;. Machines in a pool with friends reach each other over Tailscale by default, or over a tunnel you set up. Setting up the GitHub App needs an https address your browser can be sent back to, but serving jobs does not.&lt;/p&gt;
&lt;h3 id=&quot;can-the-same-pool-run-linux-jobs&quot;&gt;Can the same pool run Linux jobs?&lt;/h3&gt;
&lt;p&gt;Yes, if a Linux box with Docker and Kata or gVisor joins the pool. A job that names no operating system is placed on Linux, as on GitHub's own runners, and a job that needs a Mac names &lt;code&gt;macos&lt;/code&gt; in &lt;code&gt;runs-on&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;what-does-it-cost&quot;&gt;What does it cost?&lt;/h3&gt;
&lt;p&gt;Potluck is open source under Apache-2.0 and has no price. The Mac and its power are the costs. Sengi, the company that makes Potluck, compares &lt;a href=&quot;https://sengi.run/blog/github-actions-runner-options-cost&quot;&gt;what hosted GitHub Actions runners cost&lt;/a&gt; for the Linux jobs you would rather not host yourself.&lt;/p&gt;
&lt;p&gt;Code and docs: &lt;a href=&quot;https://github.com/sengirunners/potluck&quot;&gt;github.com/sengirunners/potluck&lt;/a&gt;&lt;/p&gt;</content>
  </entry>
  <entry>
    <id>https://potluck.sh/blog/give-your-ai-agent-a-sandbox-over-mcp</id>
    <title>Give your AI agent a sandbox over MCP, on a machine you own</title>
    <link rel="alternate" type="text/html" href="https://potluck.sh/blog/give-your-ai-agent-a-sandbox-over-mcp"/>
    <published>2026-11-17T00:00:00Z</published>
    <updated>2026-11-18T00:00:00Z</updated>
    <author><name>Sengi</name></author>
    <summary>Add one line of MCP configuration and a coding agent gets throwaway VMs and sandboxes on your team's idle Macs and Linux boxes to run its commands in. What it can do and what it keeps away.</summary>
    <content type="html">&lt;p&gt;A coding agent is most useful when it can run things: tests, builds, a server, a script it just wrote. It is most dangerous for the same reason. Potluck's MCP server gives the agent a separate machine for that work, a fresh VM or sandbox on one of your team's idle computers, and lets it throw that machine away when it is done.&lt;/p&gt;
&lt;h2 id=&quot;what-you-need&quot;&gt;What you need&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Potluck installed, a pool, and one machine sharing itself with it. On one computer that is the quick start:&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck create trial --via tunnel
potluck host --reclaim-idle-s 0
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;On an Apple-silicon Mac, Tart and Softnet; on Linux, Docker with Kata or gVisor. &lt;code&gt;potluck doctor&lt;/code&gt; says what is missing. The &lt;a href=&quot;/agent-sandbox&quot;&gt;agent sandbox page&lt;/a&gt; has a prompt your agent can follow to do all of this for you.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;add-the-server&quot;&gt;Add the server&lt;/h2&gt;
&lt;p&gt;Put this in your MCP client's configuration (Claude Code and most editors read this shape):&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-json&quot;&gt;{&amp;quot;mcpServers&amp;quot;:{&amp;quot;potluck&amp;quot;:{&amp;quot;command&amp;quot;:&amp;quot;potluck&amp;quot;,&amp;quot;args&amp;quot;:[&amp;quot;mcp&amp;quot;]}}}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Codex reads TOML, in &lt;code&gt;~/.codex/config.toml&lt;/code&gt;:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-toml&quot;&gt;[mcp_servers.potluck]
command = &amp;quot;potluck&amp;quot;
args = [&amp;quot;mcp&amp;quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;With more than one pool, name it: &lt;code&gt;&amp;quot;args&amp;quot;:[&amp;quot;--pool&amp;quot;,&amp;quot;friends&amp;quot;,&amp;quot;mcp&amp;quot;]&lt;/code&gt;. The daemon must be running and the pool made before the tools work; the client can list the tools without a daemon, and a call says the daemon is missing.&lt;/p&gt;
&lt;h2 id=&quot;what-the-agent-can-do&quot;&gt;What the agent can do&lt;/h2&gt;
&lt;p&gt;The server offers sandbox tools and nothing else:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;create a sandbox, list sandboxes, extend one's time limit, stop, restart and delete it;&lt;/li&gt;
&lt;li&gt;run a command in it, and start and follow background processes;&lt;/li&gt;
&lt;li&gt;read and write files in it.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;It does not give the agent your pool's settings, invites or keys. It acts as your local identity, or as a caller named with &lt;code&gt;POTLUCK_AS&lt;/code&gt;; &lt;code&gt;POTLUCK_TOKEN&lt;/code&gt; hands it a restricted token instead. All of its standard output is MCP traffic, so nothing else prints into the client.&lt;/p&gt;
&lt;p&gt;A typical session: the agent creates a sandbox, writes the files it needs (or you create one with &lt;code&gt;--ref HEAD&lt;/code&gt; from the terminal so it starts with your checkout), runs the tests, reads the output, and deletes the sandbox.&lt;/p&gt;
&lt;h2 id=&quot;what-stays-away-from-the-agent&quot;&gt;What stays away from the agent&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Your laptop.&lt;/strong&gt; Its commands run on the pool's machine, inside the sandbox.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The lending machine and its network.&lt;/strong&gt; On a machine you trust, a sandbox reaches the internet but never the machine itself (on Tart, apart from Softnet's DNS forwarder on the host) or its local network (docs/network.md).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Your keys.&lt;/strong&gt; A sandbox starts with none of your credentials.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Yesterday's mess.&lt;/strong&gt; Each sandbox starts from the same image and is deleted at its time limit or when removed.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Treat what comes back from a sandbox as untrusted data: a test's output can carry text written to steer an agent.&lt;/p&gt;
&lt;p&gt;Give the agent no secret you would not want it to send elsewhere: a sandbox with a network can reach the internet.&lt;/p&gt;
&lt;p&gt;For Claude Code sessions started from claude.ai, or code written for E2B, see the other ways in on the &lt;a href=&quot;/agent-sandbox&quot;&gt;agent sandbox page&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-run-more-than-one-agent&quot;&gt;How do you run more than one agent?&lt;/h2&gt;
&lt;p&gt;To run several agents and keep track of them, &lt;a href=&quot;https://mezze.sh/&quot;&gt;Mezze for teams of coding agents&lt;/a&gt;, a separate product from the same makers that runs on Potluck, adds mail between agents and people and work items whose claims expire.&lt;/p&gt;</content>
  </entry>
  <entry>
    <id>https://potluck.sh/blog/run-coding-agents-in-a-sandbox-on-your-own-machines</id>
    <title>How to run Claude Code and Codex in a sandbox on your own machines instead of a hosted sandbox service</title>
    <link rel="alternate" type="text/html" href="https://potluck.sh/blog/run-coding-agents-in-a-sandbox-on-your-own-machines"/>
    <published>2026-11-16T00:00:00Z</published>
    <updated>2026-11-18T00:00:00Z</updated>
    <author><name>Sengi</name></author>
    <summary>Give Claude Code, Codex or another coding agent a throwaway sandbox on a Mac or Linux box you own. What a sandbox must isolate, and how Potluck sets it up.</summary>
    <content type="html">&lt;p&gt;You can run a coding agent such as Claude Code or Codex in a sandbox on machines you own, with no hosted sandbox service. Potluck starts a fresh VM or container on a Mac or Linux box in your pool (the ready-made agent image needs a Linux box), runs the agent's commands inside it, and deletes it afterward. The sandbox cannot reach the machine that hosts it, that machine's network, or other sandboxes.&lt;/p&gt;
&lt;h2 id=&quot;what-does-a-sandbox-for-a-coding-agent-have-to-isolate&quot;&gt;What does a sandbox for a coding agent have to isolate?&lt;/h2&gt;
&lt;p&gt;An agent runs shell commands, installs packages, edits files and fetches web pages. Some of what it does is wrong, and some of it may come from text it read, such as a web page or an issue, that tells it to do something harmful. A sandbox limits the damage. It should do six things:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Keep the agent off the host.&lt;/strong&gt; It cannot reach the machine running it, on any port, including the ports your own programs listen on (on Tart, apart from Softnet's DNS forwarder on the host).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep it off the local network.&lt;/strong&gt; No router, NAS, printer or other computers.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep sandboxes apart.&lt;/strong&gt; One agent cannot reach another agent's sandbox.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Hold none of your credentials.&lt;/strong&gt; The sandbox starts with no keys of yours, and a key goes in only when you send it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Start clean and end for good.&lt;/strong&gt; Each sandbox starts from the same image and is deleted at its time limit or when you remove it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Block mail.&lt;/strong&gt; Outbound mail ports are closed.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These are the claims in Potluck's isolation document. &lt;code&gt;potluck isolation test &amp;lt;machine&amp;gt;-c2m4&lt;/code&gt; checks the host, local network, Tailscale network and peer-sandbox ones by sample on your own machine; &lt;code&gt;potluck host&lt;/code&gt; checks mail.&lt;/p&gt;
&lt;h2 id=&quot;why-run-it-on-machines-you-own&quot;&gt;Why run it on machines you own?&lt;/h2&gt;
&lt;p&gt;A hosted sandbox service runs your code on someone else's machines, which can be the right choice. A sandbox on your own machines is a different tradeoff, set against running the agent directly on your laptop:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;Agent on your laptop&lt;/th&gt;&lt;th&gt;Potluck sandbox on your machines&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;Where commands run&lt;/td&gt;&lt;td&gt;Your laptop, as you&lt;/td&gt;&lt;td&gt;A VM or container on a machine you own&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Can the agent reach your files&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Who can read the code, output and secrets&lt;/td&gt;&lt;td&gt;You&lt;/td&gt;&lt;td&gt;You and the owner of the machine running the sandbox&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Who runs the hardware&lt;/td&gt;&lt;td&gt;You&lt;/td&gt;&lt;td&gt;You and your team&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;The machine that runs a sandbox can read everything in it, including your code, your commands, their output and any 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 &lt;code&gt;--via tunnel&lt;/code&gt; so can the tunnel's provider. Potluck's README says to join only a pool whose owner you would trust with that. On your own machines, that owner is you.&lt;/p&gt;
&lt;h2 id=&quot;how-does-potluck-give-an-agent-a-fresh-box&quot;&gt;How does Potluck give an agent a fresh box?&lt;/h2&gt;
&lt;p&gt;A pool is a group of machines you and your friends lend and use. A host is a machine that shares some of itself with a pool, half of its cores and memory by default. A sandbox is a fresh VM or container on a host. Potluck drives the layer underneath: Tart VMs on an Apple-silicon Mac, and Docker with Kata or gVisor on Linux. It does not run its own sandbox technology.&lt;/p&gt;
&lt;p&gt;When you ask for a sandbox, Potluck picks the smallest shared machine size that fits (sizes look like &lt;code&gt;c2m4&lt;/code&gt;: 2 cores, 4 GB of RAM), starts a box there, and prints its id.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-set-it-up-step-by-step&quot;&gt;How do you set it up, step by step?&lt;/h2&gt;
&lt;h3 id=&quot;step-1-install-and-check-the-machine&quot;&gt;Step 1: Install and check the machine&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;curl -fsSL https://raw.githubusercontent.com/sengirunners/potluck/main/install.sh | sh
potluck doctor
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;On a Mac you need &lt;a href=&quot;/tart&quot;&gt;Tart&lt;/a&gt; and Softnet. On Linux you need Docker with Kata or gVisor. &lt;code&gt;potluck doctor&lt;/code&gt; says what is missing. The &lt;code&gt;agent&lt;/code&gt; template in Step 3 and &lt;code&gt;potluck agent-runner&lt;/code&gt; need a Linux box with Docker and Kata or gVisor in the pool; a Mac-only pool can run plain sandboxes but not those.&lt;/p&gt;
&lt;h3 id=&quot;step-2-start-a-pool-and-share-the-machine&quot;&gt;Step 2: Start a pool and share the machine&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck create team --via tunnel
potluck host
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;On a Mac you sit at, add &lt;code&gt;--reclaim-idle-s 0&lt;/code&gt;. By default a Mac's sandbox ends when you touch the keyboard or pointer, which would cut an agent off mid-task.&lt;/p&gt;
&lt;h3 id=&quot;step-3-create-a-sandbox-with-the-agent-image&quot;&gt;Step 3: Create a sandbox with the agent image&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck sandbox create --template agent --ref HEAD
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The &lt;code&gt;agent&lt;/code&gt; template is Potluck's Linux image plus git, gh, Node 22, Go, Python 3, ripgrep, jq, build-essential, and the Claude Code and Codex command-line tools. It needs a Linux box in the pool, since the template is built from Potluck's Linux image. &lt;code&gt;--ref HEAD&lt;/code&gt; sends the current commit of your checkout in as a git bundle. Add &lt;code&gt;--dirty&lt;/code&gt; to include uncommitted changes.&lt;/p&gt;
&lt;h3 id=&quot;step-4-run-commands-in-it&quot;&gt;Step 4: Run commands in it&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck sandbox exec &amp;lt;id&amp;gt; --timeout 600 -- npm test
potluck sandbox shell &amp;lt;id&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;exec&lt;/code&gt; takes a literal argument list and exits with the command's exit code. It kills the command after 30 seconds unless you pass &lt;code&gt;--timeout&lt;/code&gt; (at most 600); &lt;code&gt;--detach&lt;/code&gt; with &lt;code&gt;potluck sandbox logs -f&lt;/code&gt; suits longer commands. &lt;code&gt;shell&lt;/code&gt; opens a terminal in the sandbox, so you can start an agent there. &lt;code&gt;potluck sandbox cp&lt;/code&gt; copies files in and out.&lt;/p&gt;
&lt;h3 id=&quot;step-5-remove-it&quot;&gt;Step 5: Remove it&lt;/h3&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck sandbox rm &amp;lt;id&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;For a single command, &lt;code&gt;potluck run -- make test&lt;/code&gt; does all five steps: it creates a sandbox, sends the commit, runs the command, streams the output and removes the sandbox.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-let-an-agent-create-its-own-sandboxes&quot;&gt;How do you let an agent create its own sandboxes?&lt;/h2&gt;
&lt;p&gt;Potluck can serve sandbox tools to an agent over MCP. Add it to an MCP client's configuration:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-json&quot;&gt;{&amp;quot;mcpServers&amp;quot;:{&amp;quot;potluck&amp;quot;:{&amp;quot;command&amp;quot;:&amp;quot;potluck&amp;quot;,&amp;quot;args&amp;quot;:[&amp;quot;--pool&amp;quot;,&amp;quot;team&amp;quot;,&amp;quot;mcp&amp;quot;]}}}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The server exposes only sandbox tools: create, execute, list, extend, stop, restart, delete, background processes, and file reads and writes. With one pool, &lt;code&gt;--pool&lt;/code&gt; is optional. Output from a sandbox is treated as data, never as instructions.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-run-claude-codes-self-hosted-runner-in-sandboxes&quot;&gt;How do you run Claude Code's self-hosted runner in sandboxes?&lt;/h2&gt;
&lt;p&gt;Claude Code has a self-hosted runner mode, &lt;code&gt;claude self-hosted-runner&lt;/code&gt;, described in Anthropic's Claude Code documentation under &amp;quot;Self-hosted environments&amp;quot;. Potluck's agent-runner document describes the key it needs as an environment secret, which you save to a file. This path needs a Linux box with Docker and Kata or gVisor in the pool: Potluck's agent image is pinned only for Linux, and macOS guests take no secrets yet, so a Mac-only pool cannot run it. Then:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck agent-runner claude --secret-file ~/.config/claude/environment-secret --image ghcr.io/sengirunners/potluck-box-agent
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Potluck starts one fresh sandbox per runner and keeps a fresh one going as each ends. &lt;code&gt;--count&lt;/code&gt; runs several at once, &lt;code&gt;--timeout&lt;/code&gt; sets a time limit (default one hour), &lt;code&gt;--allow-tool&lt;/code&gt; pre-approves a tool for sessions, and &lt;code&gt;--deny-tool&lt;/code&gt; blocks one. The default image, the first one a machine lends, does not ship &lt;code&gt;claude&lt;/code&gt;, so pass &lt;code&gt;--image&lt;/code&gt; with the &lt;code&gt;agent&lt;/code&gt; image, which ships &lt;code&gt;claude&lt;/code&gt;, git and Python 3. Check that its &lt;code&gt;claude&lt;/code&gt; has the runner mode before relying on it: &lt;code&gt;potluck sandbox create --template agent&lt;/code&gt;, then &lt;code&gt;potluck sandbox exec &amp;lt;id&amp;gt; -- claude self-hosted-runner --help&lt;/code&gt;. Potluck installs nothing itself.&lt;/p&gt;
&lt;h2 id=&quot;how-do-you-keep-the-vendor-key-safe&quot;&gt;How do you keep the vendor key safe?&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;The machine that runs the sandbox, and the agent's session in it, can read the key. Lend runners only to machines you would give the key to, and rotate it after any session you suspect.&lt;/li&gt;
&lt;li&gt;A sandbox on a trusted machine reaches the internet and never the machine or its LAN (on Tart, apart from Softnet's DNS forwarder on the host). On Linux it reaches the internet only once the root line from &lt;code&gt;potluck doctor&lt;/code&gt; has made the filtered network. &lt;code&gt;--net off&lt;/code&gt; gives it no network at all.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;how-do-you-keep-track-of-several-agents&quot;&gt;How do you keep track of several agents?&lt;/h2&gt;
&lt;p&gt;To run several agents and keep track of them, &lt;a href=&quot;https://mezze.sh/&quot;&gt;Mezze for teams of coding agents&lt;/a&gt;, a separate product from the same makers that runs on Potluck, adds mail between agents and people and work items whose claims expire.&lt;/p&gt;
&lt;h2 id=&quot;faq&quot;&gt;FAQ&lt;/h2&gt;
&lt;h3 id=&quot;can-i-run-claude-code-in-a-potluck-sandbox&quot;&gt;Can I run Claude Code in a Potluck sandbox?&lt;/h3&gt;
&lt;p&gt;Yes. Create a sandbox with &lt;code&gt;--template agent&lt;/code&gt;, open it with &lt;code&gt;potluck sandbox shell&lt;/code&gt;, and start Claude Code there. For sessions started from claude.ai on your own machines, use &lt;code&gt;potluck agent-runner claude&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;does-it-work-with-codex-and-other-agents&quot;&gt;Does it work with Codex and other agents?&lt;/h3&gt;
&lt;p&gt;The &lt;code&gt;agent&lt;/code&gt; image includes the Codex command-line tool, so you can start it in a sandbox the same way. The built-in runner adapter exists only for Claude Code today. Adapters for other vendors are listed as not built.&lt;/p&gt;
&lt;h3 id=&quot;do-i-need-a-second-machine&quot;&gt;Do I need a second machine?&lt;/h3&gt;
&lt;p&gt;No. The pool and the host can be the same computer, with no account. A second machine is the point once you invite friends.&lt;/p&gt;
&lt;h3 id=&quot;what-happens-if-the-sandbox-runs-too-long&quot;&gt;What happens if the sandbox runs too long?&lt;/h3&gt;
&lt;p&gt;It ends at its time limit. Use &lt;code&gt;--ttl&lt;/code&gt; when you create it, and &lt;code&gt;potluck sandbox extend &amp;lt;id&amp;gt;&lt;/code&gt; to add time within the machine's cap.&lt;/p&gt;
&lt;h3 id=&quot;how-is-this-different-from-a-container-on-my-laptop&quot;&gt;How is this different from a container on my laptop?&lt;/h3&gt;
&lt;p&gt;A container on your laptop shares your laptop's network and often your files. A Potluck sandbox runs on a host, in a VM or an isolated container, and is walled off from the host, its network and other sandboxes.&lt;/p&gt;
&lt;h3 id=&quot;does-it-cost-anything&quot;&gt;Does it cost anything?&lt;/h3&gt;
&lt;p&gt;Potluck is open source under Apache-2.0 and has no price. You pay for your own machines and power.&lt;/p&gt;
&lt;p&gt;Code and docs: &lt;a href=&quot;https://github.com/sengirunners/potluck&quot;&gt;github.com/sengirunners/potluck&lt;/a&gt;&lt;/p&gt;</content>
  </entry>
  <entry>
    <id>https://potluck.sh/blog/use-the-e2b-sdk-on-your-own-machines</id>
    <title>Use the E2B SDK on your own machines</title>
    <link rel="alternate" type="text/html" href="https://potluck.sh/blog/use-the-e2b-sdk-on-your-own-machines"/>
    <published>2026-11-17T00:00:00Z</published>
    <updated>2026-11-17T00:00:00Z</updated>
    <author><name>Sengi</name></author>
    <summary>potluck-e2b answers the calls the E2B Python and TypeScript SDKs make, so code written for E2B sandboxes runs on your team's idle Macs and Linux boxes with only its environment changed. What it covers and how to set it up.</summary>
    <content type="html">&lt;p&gt;If you have code written against E2B's SDK and spare machines on your team, you can run that code's sandboxes on those machines without changing it. &lt;code&gt;potluck-e2b&lt;/code&gt; is a small gateway that the Potluck installer puts beside &lt;code&gt;potluck&lt;/code&gt;. It answers the E2B control plane and the parts of a sandbox's own API the SDK uses, and turns them into Potluck sandboxes.&lt;/p&gt;
&lt;h2 id=&quot;set-it-up&quot;&gt;Set it up&lt;/h2&gt;
&lt;p&gt;You need a Potluck pool with a machine sharing itself (the &lt;a href=&quot;https://github.com/sengirunners/potluck#quick-start&quot;&gt;quick start&lt;/a&gt;, or the prompt on the &lt;a href=&quot;/agent-sandbox&quot;&gt;agent sandbox page&lt;/a&gt;). Then, on a machine in the pool:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;potluck-e2b keygen     # makes an API key and prints it; keys live in $POTLUCK_HOME/e2b/keys (mode 0600)
potluck-e2b            # serves on localhost:49982 and prints the lines to export
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;On start it prints three things to set in the program that uses the SDK: &lt;code&gt;E2B_DOMAIN&lt;/code&gt; (by default &lt;code&gt;e2b.localhost:49982&lt;/code&gt;), &lt;code&gt;E2B_API_KEY&lt;/code&gt; (a key from the keys file), and &lt;code&gt;SSL_CERT_FILE&lt;/code&gt; for Python on Linux or &lt;code&gt;NODE_EXTRA_CA_CERTS&lt;/code&gt; for Node, naming the certificate authority the gateway made for itself (on macOS the Python SDK trusts only the keychain). Code that uses only the calls listed below needs no other change; network rules, pause, volumes, PTY, stdin streaming and lower-case environment variable names are refused. Names under &lt;code&gt;.localhost&lt;/code&gt; always point at your own machine, and the gateway signs a certificate for each name it serves, limited to its own domain.&lt;/p&gt;
&lt;h2 id=&quot;what-it-covers&quot;&gt;What it covers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;Sandbox.create&lt;/code&gt;, placed on your pool's machines the way &lt;code&gt;potluck sandbox create&lt;/code&gt; places them;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;commands.run&lt;/code&gt;, with its exit code, standard output and standard error;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;files.read&lt;/code&gt; and &lt;code&gt;files.write&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;get_info&lt;/code&gt;, &lt;code&gt;Sandbox.list&lt;/code&gt;, &lt;code&gt;set_timeout&lt;/code&gt;, &lt;code&gt;Sandbox.connect&lt;/code&gt; and &lt;code&gt;kill&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A sandbox's environment variables reach a command as secret files, never on its command line, so the secrets rules apply: they go only to a machine you trust whose sandboxes can hold secrets.&lt;/p&gt;
&lt;h2 id=&quot;how-it-is-checked&quot;&gt;How it is checked&lt;/h2&gt;
&lt;p&gt;A test runs the unmodified E2B Python and TypeScript SDKs against the gateway: it creates a sandbox, runs commands, writes and reads a file, lists, connects and kills (&lt;code&gt;TestRealSDK&lt;/code&gt; in internal/e2bgateway).&lt;/p&gt;
&lt;h2 id=&quot;when-to-use-e2b-instead&quot;&gt;When to use E2B instead&lt;/h2&gt;
&lt;p&gt;E2B runs the machines for you, in its cloud, and covers more of its own API. Use it when you have no spare machines or need more sandboxes at once than your team owns. Use &lt;code&gt;potluck-e2b&lt;/code&gt; when the machines are already yours and you would rather your code ran on them.&lt;/p&gt;</content>
  </entry>
</feed>
