Shells that keep running

Last updated: 2026-11-01

A shell in SpectaShell can outlive the connection that opened it. A small program, spectashell-keeper, holds the shell and its last output on the machine where it runs. When the network drops, your iPad sleeps, or SpectaShell quits or is updated, the shell and the programs in it carry on, and when you open it again it comes back with its screen.

This is what lets you start a build or a coding agent on the Mac, follow it on the iPad, answer it on the iPhone, and come back to the Mac to find it where you left it.

What a keeper does#

• It holds one shell. Each shell you open in a keeper has a keeper of its own, running as you, beside the shell.
• It keeps the last output. The last 1 MB of what the shell printed is kept, and drawn again when a device opens the shell, at the width it was written at, so lines wrap where the program wrapped them.
• It does not end with your connection. A dropped network, a sleeping iPad or iPhone, quitting SpectaShell or updating it leaves the shell running. Only one of your devices has it open at a time (see One device at a time).
• It ends with the shell. Closing the shell's pane, tab or window ends the shell and its keeper, as exit does. So does a restart of the machine it runs on (see After a restart).
• It opens no port. A keeper listens on no network port and never runs as root; everything reaches it over your own SSH login. See Security and privacy.
• It can tell you when you are away. Once a device of yours has notifications on, it tells every such device — iPhone, iPad or Mac — when a program needs you and none of your devices is in front (see When you are away).

On your Mac#

Every shell you open on your Mac runs in a keeper; there is nothing to choose. The iPad and iPhone have no shells of their own (see What SpectaShell does not do), but they can reach your Mac as a host, and keep its shells running as on any other host (see On a host).

When you quit SpectaShell, your local shells keep running. The next time you open it, your windows come back with their tabs and splits, each pane on its shell with its screen. A shell that no saved window holds — the app was quit before it could save its windows — gets a tab of its own in the window in front, so none is left without one. The window in front shows Hosts.

On a host#

Keep shells running?#

The first time you connect to a host, SpectaShell asks Keep shells running on gpu-box?, with the account you log in as. It says what it would put there: the program spectashell-keeper, in ~/.local/share/spectashell, with your shell files not changed.

• Keep Shells Running puts the keeper there and opens your shell in it. From then on, shells on that host keep running when you leave.
• Plain Shells puts nothing there. A shell on that host is a plain SSH shell, and it ends with its connection.
• Closing the question opens nothing, and it is asked again the next time.

You are asked once for each host. Your answer goes with your hosts to your other devices through iCloud (see Syncing through iCloud).

What is put on the host#

• The keeper program, in ~/.local/share/spectashell/<build>/, with a link current to the build put there last. It is sent over your SSH login, compressed when the host has gzip. When a newer SpectaShell puts its own build there, an older one is removed once nothing runs from it.
• Each shell's socket and description, in a folder only you can open: /tmp/spectashell-<your user id> on Linux, ~/Library/Application Support/SpectaShell/keepers on a Mac.
• Nothing else: your ~/.bashrc, ~/.zshrc and other shell files are not touched. Shell integration is added as each shell starts.

Keepers are made for Linux on x86-64 and ARM64, and for macOS on Apple silicon and Intel. On any other system — FreeBSD, a router's MIPS — a shell cannot start in a keeper, and the pane says "Could not connect to …" with "SpectaShell has no keeper for …". Choose Stop Keeping Shells for that host to use plain shells there.

Changing your answer#

• In the host's menu — the ••• on its card on the Mac and the iPad, or a right-click on the Mac, a touch and hold on the iPad and iPhone: Keep Shells Running, or Stop Keeping Shells once its shells are kept.
• In the host's editor (Edit… in its menu), under Shells: Ask First asks again at the next connection, Keep Running keeps them, Plain Shells does not.

Stopping ends nothing: shells already kept on the host go on running there, but Running no longer lists them, and a new shell there is a plain one. Choose Keep Shells Running again to see them.

How a host's card shows it#

• The keeper badge, a green dot at the lower right of the host's tile, means its shells are kept. Hold the pointer over it on the Mac: "Keeps shells: they go on running on this host when you leave".
• Under the host's name, the card says how many of its shells are kept, such as "2 shells kept", or "not kept" when you chose plain shells.
• Clicking or tapping the card continues a kept shell rather than starting another. With none kept there, it opens a new shell. With one, it opens that one, taking it from the device that has it. With several, it asks "Continue a shell": choose one, or New Shell.
• New Shell, in the host's menu, always starts a new shell.
• Running Shells…, in the host's menu, lists every shell kept there, oldest first, each with what runs in it, its folder, how long it has run and whether it is "open here", "on" another device, or ended. Choosing one opens it here. Unlike Running, this list logs in to the host when it must, asking what the login needs.

Running#

Running lists the shells that keep running — on this Mac and on your hosts — whichever of your devices started them, with what each one is doing.

• On the Mac and the iPad, Running is the row under Hosts in the sidebar. It opens the Hosts page, whose first section is Running: "the last lines of each, wherever it is open".
• On the iPhone, Running is the first section of the Hosts tab.

Running has one line per machine: its name, how many shells run there, and how many wait for you or need you, with the dot of the most pressing one. Click or tap a line to open it to its shells' cards, which are named by what runs in them and their folder. A machine where a shell waits or needs you is open by itself; others stay closed until you open them. A line you open or close stays as you left it on this device, until one of its shells asks more of you than when you left it.

The list holds the shells open in a pane on this device, first, and the shells kept on your hosts that no pane here holds. On the Mac it also lists this Mac's own, under "this Mac". Only hosts whose shells you keep are listed.

Running asks your hosts again every 30 seconds while it, or its row in the sidebar, is on the screen. It asks without asking you anything: with this device's listing key (see The listing key), or with a key that needs no passphrase. A host that cannot be asked that way is left out until you connect to it. Listing a host never takes a shell from the device that has it.

One machine saved under two names — the book's "GPU Box" and ~/.ssh/config's gpu, or one address on the LAN and another over a VPN — shows each of its shells once, under the host it was opened from.

A desk from another device#

A desk of several shells split side by side on one device shows on your other devices as one card at the top of its machine's line: its panes drawn as they are split, each with its shell's last lines, and under them its name, its shells, and Open as on MacBook Pro — the name of the device it was laid out on. Click or tap it to take its shells into one new desk here, split as they were, with the tabs each pane held. To work with one of them alone, open the desk, then move that tab to a desk of its own (see Moving tabs and desks). A desk of several shells open on this device has a card too, first, with Show Desk: it brings that desk to the front. When another device took its shells over, the card says Take Back: it takes them back into the panes they left, rather than opening the desk a second time. A single shell's card does the same for a shell taken from a pane here.

• Where the window is too small for a pane to keep 40 columns and 12 rows in your font, the smallest panes leave the split until the rest fit, and each becomes a tab of the pane beside it, so the desk stays together. The iPhone opens the desk whole and shows its panes one at a time: swipe sideways to move between them.
• Shells open here already stay where they are, and shells that ended are left out. The card shows while two or more of its shells can be opened here.
• Your devices still lay out their own windows. A desk opens only when you ask; nothing follows another device by itself. The card shows the desk as it is on the device that started its shells: taking it apart or merging it on another device changes nothing there.
• The desk is kept by its shells' keepers, so it lasts as long as they do and needs no iCloud. It holds the shells' keeper names and how the desk is split — no host, folder or command.
• Shells started by a SpectaShell from before 30 October 2026 are in no desk: their keepers are older and do not keep it. A shell started since is.

The Running dot#

The dot beside Running in the sidebar says how your shells are, and the number after it how many Running lists.

A shell elsewhere — open on another device, or in no pane at all — is amber while its program says it waits for you, as Claude Code does when it asks for permission or a question: its keeper reads it, and every device shows it. A finished command or a bell is known only on the device whose pane saw it (see Working in the terminal). While the dot is red, an amber number before the count says how many shells wait for you behind it. Hold the pointer over the row on the Mac to read it in words, such as "Running: 1 waiting for you, 2 running".

A shell's program ended by a crash — SIGSEGV, SIGBUS, SIGABRT and the like — or killed with SIGKILL (as the system's out-of-memory killer does) counts as red. An exit code alone does not: a shell exits with the status of its last command, so "exit 1" says nothing about trouble.

The cards#

Each shell is a card. A card is tall, with the last four lines of the shell's screen, when those are known: for a shell open here, and for one whose keeper is of a recent SpectaShell. A program that fills the whole screen — Claude Code, an editor, top — shows the title it set, with "claude · full screen", rather than a piece of its screen. A shell whose keeper came from an earlier SpectaShell has a short card, without lines.

Under the screen are the shell's project — the last name of its folder, such as webapp — in bold, and under it, small, what runs in it and how long it has run, with the ids a program is given (a session's UUID) left out: claude --resume. At the right is its state:

• Waiting, in amber: it waits for you.
• How long it has run, for a shell open here; at prompt when nothing runs in it.
• on iPad Pro: another device has it open.
• ended · exit 0, ended · SIGHUP: its program ended.
• reconnecting…, host not reached, connection lost: see When the connection drops.

The dot on the card's tile is the shell's own: green while it runs, amber while it waits, grey once it ended or while it reconnects, and red with ! while it needs you. When two shells would read the same — the same host, the same program, the same folder — the second is numbered: "webapp · 2".

What you can do with a card:

• Open it with a click or a tap. A shell open here comes forward in its pane. A shell elsewhere opens in a new tab here, and the device that had it lets go of it (see One device at a time).
• Watch it, from its menu (a right-click on the Mac, a touch and hold on the iPad and iPhone): see it without taking it (see Watching a shell).
• Reconnect, on the card of a shell open here whose connection was lost, or whose host has not been reached for a minute, connects it again in its pane.
• Remove, on the card of an ended shell, ends its keeper, and the shell leaves Running on every device. Removing one may log in to its host. If it cannot, SpectaShell says "The shell was not removed", and why.
• Remove Ended (3), at the top of Running when two or more shells have ended, removes them all at once. On the iPhone it is on the page of all running shells.

An ended shell you leave alone goes by itself a day after it ended, if no device opens it.

On the iPhone each shell is a row rather than a card, with the same words and dot but not the lines of its screen. Swipe a row to the left for Remove or Reconnect.

One device at a time#

A shell is open on one of your devices at a time. Opening it on another — from its card, from Running Shells…, or by tapping its host — moves it there: the device that had it lets go, and the shell goes on running, with its programs and its screen.

The pane on the device that let go keeps the shell's last screen, dimmed, and says so: "Another device took this shell over", over "Another device opened this shell. It still runs here" for a shell on your Mac, or "It still runs on gpu-box" for one on a host. When the host's keeper could not tell that another device took it, the title is "The connection to gpu-box ended". It offers:

• Take Back, which takes the shell back to this device;
• Watch, which follows it here without taking it.

Watching a shell#

Watching shows a shell as the device that has it uses it, without taking it from that device: a long build followed from the sofa on the iPad while the Mac types.

• Choose Watch in a Running card's menu, or in the pane of a shell another device took.
• The pane's line says who has the keyboard — "Watching · MacBook Pro has the keyboard", or "No one has the keyboard" — over "What you type here goes nowhere until you take the keyboard." The screen is not dimmed.
• The shell keeps the size of the screen typing into it. A smaller screen watching shows all of it, scaled down to fit.
• Take Keyboard makes this device the one typing, at its own size; the device that had the keyboard then watches.
• Closing a pane that watches only stops watching: the shell keeps running.
• A watching pane comes back watching after SpectaShell restarts, and after a dropped connection; it never takes the keyboard by itself.

People who share a host's account in a team can watch each other's shells the same way: see Teams. Opening a card, rather than choosing Watch, takes the shell, whoever has it.

When the connection drops#

A shell in a keeper waits on its host while SpectaShell connects again by itself: at once, then after 1, 2, 4 seconds and so on, up to every 30 seconds — and at once whenever the Mac wakes, the app comes back to the screen, or the network changes.

• Meanwhile the pane keeps its screen, dimmed, and says "Reconnecting to gpu-box…": "The connection dropped. The shell keeps running there and comes back with its screen." Running says "reconnecting…".
• After a minute without reaching the host, the line turns amber: "gpu-box cannot be reached. Still trying…", with Reconnect to try again now. Running says "host not reached", in red. Check that the host is on, and that this device is on its network or VPN.
• Once the host answers, the shell comes back with its screen, as it was. If the login needs you — a password, Face ID for the device key — you are asked.

A plain shell — on a host whose shells are not kept — ends with its connection. Its pane says "The connection to gpu-box ended", and why, with "Nothing on gpu-box kept this shell." Reconnect opens a new shell there; what ran in the old one is gone.

Show Logs, beside the pane's actions, lists each step of the connection and how long it took (see When something goes wrong).

How a shell ended#

When you open a shell whose keeper is gone — from a saved window, or with Take Back — its pane says what happened, as the keeper left word before it ended:

• "This shell on gpu-box was closed", "Closed on MacBook Pro at 00:22." — a device closed its pane.
• "This shell on gpu-box has ended", "Its program exited with code 3." — the shell itself ended, and how; with "No device opened it within a day." when it was left that long.
• "This shell on gpu-box was stopped", with when.
• "Its keeper stopped without a word: it was killed, or gpu-box shut down."
• "Its keeper is gone and left no word of how." — the keeper came from an earlier SpectaShell, or its word was lost.

For a shell on your Mac the line says "here" instead of the host. Close Ended Desks, in a desk's menu, closes every desk whose shells have all ended.

After a restart#

No shell survives a restart of the machine it runs on: the keepers end with it. SpectaShell keeps what each pane was — its folder, and the command that resumes a coding agent that ran there — so you can open it again.

After a host restarts, a pane of a shell that ran there says "gpu-box restarted, and this shell ended with it", with Reopen. Reopen starts a new shell in the pane, in the folder the old one was in. Where Claude Code or Codex was running, the command that resumes its conversation (such as claude --resume …) is typed at the prompt, and runs only when you press Return.

After your Mac restarts, SpectaShell asks at launch: "Your Mac restarted", with how many windows and shells it had, and whether a coding agent ran in one of them.

• Reopen opens each window again with its tabs and splits, a new shell in each pane's folder, and each agent's resume command typed in, ready to run with Return.
• Don't Reopen forgets them.
• Not Now keeps them, and asks again the next time SpectaShell starts.

The programs that ran and the output on the screens do not come back; only the windows, the folders and the resume commands do.

Leaving and coming back#

• On the Mac, quitting SpectaShell leaves every shell in its keeper, on the Mac and on your hosts. Closing a window does not: it asks "Close this window?", and the shells it started end; those another device started keep running. A shell on a host without a keeper ends when SpectaShell quits.
• Closing a shell another device started — one you opened from Running — leaves it running for that device to take back. End Shell, in the tab's or pane's menu, ends it.
• On the iPad and iPhone, the system stops SpectaShell soon after it leaves the screen, and its connections with it. Shells in keepers lose nothing: when you come back, each pane connects again and its screen is drawn as the shell left it. A plain shell is usually gone and offers Reconnect. A window you close in the app switcher leaves its shells running in their keepers. See On the iPad and iPhone.

Good to know#

• Closing a pane, a tab or a window ends its shell, kept or not, unless the pane only watches it. To leave a shell running, quit SpectaShell, leave the device, or open the shell on another device.
• A keeper ends when its host restarts, and nothing brings back what ran; Reopen opens a new shell in the same place.
• On some Linux servers, logging out of your last session ends every process you started, keepers included, as it ends tmux. On a shared server, a keeper's folder made by someone else is refused. Both are explained, with what to do, in When something goes wrong.
• A waiting program reaches you while SpectaShell is closed only once a device of yours has Settings ▸ Notifications ▸ Notify This Device on (see When you are away); the shell itself goes on in its keeper either way.
• Choosing Stop Keeping Shells for a host hides its kept shells from Running but does not end them.