Skip to content
Muxin
Docs · Boxes

On your machines

Boxes

Hand a task to an agent. It works on it by itself, in a container of its own on one of your machines.

A box is one task for an agent. Muxin makes a fresh checkout of your repository on a new branch, in a Docker container on one of your machines, and starts the agent on the task. The agent works by itself, with its permission prompts off: the container is its sandbox. When it’s done, it can push its branch and open a pull request.

The Boxes page: Add rate limit headers, working with Claude Code on Beacon, and Fix flaky webhook retry test, paused, with Codex. Each shows its task, branch, changes and pull request. Below them, the agents’ workspaces. The Boxes page: Add rate limit headers, working with Claude Code on Beacon, and Fix flaky webhook retry test, paused, with Codex. Each shows its task, branch, changes and pull request. Below them, the agents’ workspaces.
One box is working and one is paused. Agents’ workspaces are listed below them.

A box or a session? Use a session to work with an agent. Use a box to hand it a task and come back later.

Start one

Open Boxes (⌃3) and click New box. Then pick:

  1. The code. A GitHub repository (type to search yours), or a folder on a machine. A folder’s box starts from the checkout as it is, uncommitted changes included, and your checkout isn’t touched.
  2. The task. What the agent should do. Ask it to open a pull request when it’s done.
  3. The agent. Claude Code, Codex, Amp, OpenCode, Gemini CLI or Pi.
  4. Where it runs. Best one picks the online machine with Docker and the most free memory.
The New box dialog filled in from an issue: the repository acme/api, the task to fix the GitHub issue and open a pull request that closes it, Claude Code picked as the agent, and Best one as the machine. The New box dialog filled in from an issue: the repository acme/api, the task to fix the GitHub issue and open a pull request that closes it, Claude Code picked as the agent, and Best one as the machine.
New box, filled in from a GitHub issue.

The first box on a machine builds Muxin’s box image there, which takes a few minutes. Later boxes start in seconds. If the repository has an .agents/setup script, it runs first.

From a GitHub issue

Every issue has Hand off in a box. It opens New box filled in: the repository, a task to fix the issue and open a pull request that closes it, and a branch named for the issue. The issue’s title and description go to the agent too.

The issue Coupon total is wrong after tax, number 412 in acme/api, with the buttons Work on it with an agent, Hand off in a box, Open on GitHub and Copy link. The issue Coupon total is wrong after tax, number 412 in acme/api, with the buttons Work on it with an agent, Hand off in a box, Open on GitHub and Copy link.
Work on it with an agent opens a session. Hand off in a box gives the issue to a box.
  1. 01

    Pick an issue

    Click Hand off in a box, then Start.

  2. 02

    A box starts

    A fresh clone, on a branch like issue-412-coupon-total-wrong-after.

  3. 03

    The agent works

    By itself, with the issue as its task.

  4. 04

    A pull request

    One that closes the issue. Review it on GitHub.

Watch it

Click Open to see the agent’s terminal, like any session. Type in it to ask more. ⌘D opens a shell in the box beside it, with the same checkout and tools.

A box’s agent: Claude Code working on Add rate limit headers, marked Box, in a container on Beacon, with Actions, Hand off and Pause in its header. A box’s agent: Claude Code working on Add rate limit headers, marked Box, in a container on Beacon, with Actions, Hand off and Pause in its header.
A box’s agent. Pause stops the box; its files and conversation stay.

The Boxes page shows each box working, waiting for you or paused, with its branch, what it changed and its pull request.

It pauses by itself

When the agent has printed nothing for 15 minutes, or has quit, the box stops. Its files, branch and conversation stay. Ask it something more, or click Resume, and it picks up where it left off.

This works with Muxin closed. Muxin’s agent on the machine does it.

Already signed in

A box uses the machine’s own sign-ins. If the agent is signed in on that machine, it’s signed in in the box, with your settings and MCP servers. If not, sign in once from a box’s terminal (/login). Every box on that machine has it from then on.

On a Mac, Claude Code keeps its sign-in in the Keychain, which a container can’t read. Sign in once from a box’s terminal there.

Change its agent

On a box’s page, Hand off gives the task to another agent in the same box, with a note of the work so far. See Hand off and move.

Where it lives

A box is a folder on its machine, ~/muxen/boxes/<id>: its checkout and the agent’s home. Delete removes the folder and the container, with any work that wasn’t pushed. Its branch on GitHub stays.

The agent works as you, with your GitHub login, and its network isn’t closed off. Give boxes tasks for code you trust.

Machines that run boxes

Linux machines, and Macs with Docker Desktop, OrbStack or Colima. Not Windows yet.

Agents’ workspaces

Below the boxes, the Boxes page lists agents’ workspaces: folders on your machines that AI tools you use elsewhere work in through Muxin. See Workspaces.

From a terminal and from other agents

Your AI agents can start boxes too. The MCP tools are box_create, box_list, box_send, box_pause and box_destroy. The CLI has the same:

muxin box new acme/api "Add rate limit headers, with tests, and open a pull request"
muxin box new ~/code/app "Finish this refactor" --on beacon --agent codex
muxin box ls                                 # each box, and what it changed
muxin box send box-7k2m9q "Also update the docs"   # starts it again if it's paused
muxin box attach box-7k2m9q                  # its agent, in this terminal
muxin box shell box-7k2m9q                   # a shell in the box
muxin box pause box-7k2m9q
muxin box rm box-7k2m9q

See MCP for your agents and The command line.