Machines

Machines

A machine is another computer Magnum reaches over SSH: a Linux server, a cloud VM, another Mac. Magnum installs its node there, and your agents run on it while you work in Magnum here.

Adding a machine

Choose Add instance at the bottom of the sidebar's Machines view, or Add instance… in the environment menu (the chip under the message box), in Control's Machines, on the start screen, or in ⌘O.

The dialog lists the hosts in your ~/.ssh/config that you haven't added yet, and its patterns, such as *.example.com, to complete. Or type an alias, user@host or user@host:port, and click Connect.

Magnum uses your SSH settings, as a terminal does. When SSH asks something, such as a password or whether to trust a new host, Magnum asks you in a dialog. If a step fails, the dialog says why and what to check; Try again starts over.

Once connected, choose a folder, a recent one or one you browse to, and Open it as a project on that machine. A machine without an agent offers Install Claude Code, which runs Anthropic's installer there without sudo. What it lacks for committing and pushing is offered too: git itself, who commits (copied from this Mac), and GitHub's sign-in (this Mac's, asked first).

Docker Sandboxes

With Docker's sbx installed and signed in (brew install docker/tap/sbx, then sbx login), the dialog lists your sandboxes in Docker's cloud under Docker Sandboxes, with New sandbox. Click one to connect: Magnum reaches it through sbx and leaves your ~/.ssh/config as it is. New sandbox makes one in Docker's cloud, magnum-1 and on, with Claude Code installed (2 CPUs, 4 GB, billed to your Docker account) and Docker's balanced network policy, so its agents reach GitHub and the package registries.

A sandbox stops when its time runs out and starts again, with its files, when Magnum next connects. While something runs in it and Magnum is connected, Magnum keeps it from stopping, up to Docker's limit of a day. A stopped sandbox runs nothing, and Magnum doesn't start one just to look at it.

OrbStack

With OrbStack on this Mac, the dialog lists its Linux machines under OrbStack, with New machine. Click one to connect: Magnum reaches it through OrbStack's own SSH (as ssh <machine>@orb does), leaves your ~/.ssh/config as it is, and a stopped machine starts. New machine makes an Ubuntu machine, magnum-1 and on, with your Mac's user name there.

Tailscale

Magnum doesn't need Tailscale. When it runs on this Mac, Magnum uses it: the dialog lists your tailnet's computers that are online and not added yet under Tailscale (not phones, not this Mac, not ones your ~/.ssh/config already reaches). Click one: the field gets @ and its tailnet name, with the cursor before it. Type the user to sign in as, and Connect. It's added under its name in the tailnet.

A machine reached by its tailnet name that can't be reached says why in the Machines view and in Control: Offline on Tailscale (since when), or Tailscale is off on this Mac. When it comes back online, or Tailscale starts here, Magnum reconnects at once.

Signing in on your machines

Claude Code on a machine uses that machine's own sign-in. To use this Mac's instead, give Magnum a token in Settings → Accounts (Add account → Sign-in for your other machines…): Get a token runs claude setup-token in the project's terminal, you sign in in the browser, then paste the token it prints and Save. Magnum tries it with one short answer from Haiku, keeps it in the Keychain, and Claude Code sessions on your other machines get it from their next start (projects on this Mac keep its own sign-in, and so do machines using another provider). Forget stops it.

What Magnum installs

Magnum installs its node in ~/.magnum on the machine, without sudo. The node runs your agents and terminals there and keeps them running when the connection drops. Magnum reaches it through SSH; the node opens no ports.

On a Linux machine with systemd, Magnum lets your user's services run without a login where it can, then sets the node up as a user service: it restarts after a crash and starts when the machine boots. When it can't (that needs sudo loginctl enable-linger there), Control and the machine's card say so. On a Mac, the node becomes your user's launchd agent: it restarts after a crash and starts when you log in at that Mac (macOS starts a user's agents at login, so a Mac that restarts with no one logged in waits for a login, or automatic login).

Agents keep running

An agent runs in its machine's node, so it keeps working while this Mac sleeps or the connection is down. When you quit Magnum, a session with a conversation keeps running; one with none yet ends. The next start picks them up. Magnum's SSH connections end when it quits, so a machine that signs in with a password asks again next time.

Sessions on this Mac run in a node too: Magnum Helper on a Mac, Magnum's node on Linux. It stays after you quit while agents run in it, and stops by itself once it has been idle for a while.

On a Mac, Magnum Helper's menu bar item lists the agents running here and on your machines, with Stop All Agents. On Linux, Magnum's node shows the same in a tray icon. See The Board.

Agents left running

An agent with no Magnum window on it, because Magnum quit or crashed while it ran, is listed under its machine in Control, with Open and Stop…; ⌘P has Reopen and Stop… too. Open opens its project and attaches the session to the running agent. Stop… asks first, then ends the agent; its conversation stays in history.

Machines that aren't connected are looked at too, over SSH, without asking you anything. Magnum never stops an agent for being quiet: an agent can work for days, so you decide.

Machines in the sidebar

The switch at the top of the sidebar shows Projects, Machines or Automations (also ⌘P, Show machines in the sidebar). Machines shows this Mac and every machine you added. Each has the mark of what it runs on (its Linux distribution, Docker when it's a container, Windows for WSL) with a dot for how it stands, where it is (its cloud's region, asked on the machine itself, else its time zone's city), what it can take on now (its CPU load, memory in use and disk free, read every few seconds) and the sessions running on it, with their project; agents left running with no window are there too. Hover it for its system, kernel and agents. A machine that isn't connected says why, with Try again. Its ⋯ on hover (also on right-click) has Open terminal (in its home folder, in place of the session; while a project is open), Open folder…, Connect, Update node now… (when a newer node waits), Rename… (what Magnum calls it everywhere; its own name stays), Copy address and Remove…. The Add instance dialog stays open when you click outside it.

Machines in Control

Control's Machines lists this Mac and every machine you added: how each stands, its system and its node's version, and under it its open sessions and agents left running. Connect connects a machine; Add instance… heads the list. Open it with Machines… in the environment menu, or with ⌘P and Machines.

Node updates

Magnum keeps each machine's node, and this Mac's, at its own build. When it finds another build running, its own takes that one's place, and the agents running there keep running. On a Mac, a node too old for that is replaced once nothing runs in it, and Magnum says so; Update node now… (in Control, and in the machine's menu) replaces it at once, stopping what runs in it, after you confirm.

Removing a machine

In Control, Remove… asks first. Magnum's node, its service and its logs go from the machine; worktrees there stay. Agents running there stop, and their conversations stay in history. If the machine can't be reached, Magnum offers to forget it here only, leaving its node there. Opening a project on a removed machine opens the Add instance dialog with its name filled in.

Connecting

When Magnum starts, the machines with sessions left open on them connect in the background, without asking anything. One that needs a password or a new host key, or doesn't answer, stays not connected.

Opening a session or project on a machine that isn't connected shows Connecting to it in the session's place, and the session once connected. SSH's questions ask in a dialog. A machine that doesn't answer within 15 seconds can't be reached: the session says why, with Try again. Opening something else meanwhile lets it go; the connection goes on.

Reconnecting

When a connection drops, a session on that machine says Reconnecting, with Try now, and Magnum tries again on its own, waiting longer each time, up to a minute. The agent keeps working there, and what you send goes once the connection is back. When this Mac wakes from sleep or its network changes, Magnum checks every connection at once and reconnects the ones that don't answer.

When SSH needs you, as when it refuses the sign-in or the host's key changed, Magnum stops trying: the session says Can't reach, with Reconnect, and the Board's queue tells you.