Install and update errors
The install one-liner's refusals, a desktop app with no server binary, a refused restart, and a crashed badge.
Fix the failures around installing, updating, and restarting the server: the refusals the install scripts print, the desktop app's no-binary message, a restart that is refused, and a subshell that reads as crashed.
The install one-liner refuses
curl -fsSL …/install.sh?setup_key=… | bash can stop for several distinct reasons, and each message says which:
| What you see | What happened | What to do |
|---|---|---|
subshell: the setup key was rejected: invalid, expired, or already used. | Keys are single-use and expire in 24 h. | Mint a fresh one on the Nodes page and rerun the command. |
subshell: this server could not provide a linux-x64 node binary. (your triple in place of linux-x64) | The server has no binary on disk and could not fetch one from the project's release: an air-gapped host, SUBSHELL_RELEASE_URL empty, or the release host unreachable. The server's API answers the same case with No subshell build for "linux-x64" is published on this instance yet. | Check the server's log for the fetch failure; see the air-gapped note below. |
subshell: checksum mismatch: corrupt download or inconsistent server artifacts; (next line: nothing was installed, your existing binary untouched) | The bytes did not match the published digest. | Rerun; if it persists, the server's artifact and its sidecar disagree: republish or refetch server-side. |
subshell: could not reach <server URL>; nothing was installed (<install dir> untouched). (the script's $SERVER and $DEST expand to the URL you used and the target directory) | The machine never reached the server at all: a wrong address, a firewall, or the VPN was down. | Reach the address by hand (curl -I) and retry. |
desktop-client-vX.Y.Z publishes no darwin-x64 bundle (asset … is missing). (your version, triple, and asset name in place) | That release predates, or was cut without, the Intel image. | Pin a newer release with SUBSHELL_CLIENT_VERSION, or take the current one-liner from the download page (see Supported platforms). |
When the instance is configured not to fetch releases, the Add-node dialog warns up front (This server has no node binary for: the missing triples , and it is configured not to download one.). The remedies are the ones it names: publish binaries on the server by copying the subshell-node-cli-<triple> assets from a cli-node-v* GitHub Release into its node-artifacts dir, or install the node another way and run subshell setup directly. Add a node has the full path.
The desktop app reports no server binary
Symptom. Subshell Server's assistant says this build ships no server binary.
Fix. The bundle you installed is missing the server it wraps. Reinstall the app from the project's releases page. An official bundle carries the binary, so a refusal means the install itself is incomplete, not that your machine is unsupported. If a reinstall reproduces it, that is a bug worth reporting, with the OS and the app version from About.
"Restart the server" refuses, or is greyed out
Symptom. The restart action on Settings → Service says This server is not running under a service manager; restart it where you started it., or a restart that should work instead answers The installed service definition would close every running subshell on restart; reinstall the service definition, or pass force to restart anyway.
Cause. The first refusal is availability, not permission. A restart works by exiting for your service manager to respawn, and a bun run start, a container with no init, or a hand-run process has nothing to respawn it. There is deliberately no way to exit a server into nothing. The second refusal is pane safety: an old service definition kills the process group, which is every live tmux pane with it. subshell-server service status reads which definition you have, and teardown keeps panes = NO names the stale one.
Fix. For the first case, start the server from wherever it lives, or make it service-managed: run subshell-server service install on the host, or let the Subshell Server desktop app supervise it. For the second, reinstall the service definition so teardown keeps panes, or pass force when you really mean it; from the CLI that is subshell-server service restart --force. Stop, start, uninstall, and reset stay off the dashboard entirely by design. Each of them leaves the server unreachable, so a page the server serves is the wrong place to ask.
A subshell says crashed after a restart
Symptom. After the server (or the machine) came back, a subshell reads as crashed, or a push said Crashed, auto-restarting and then Crashed.
Cause. For panes, tmux is the source of truth and the database row is a statement of intent; a reconcile pass re-reads it every minute. So offline is not crashed: if a node was unreachable, the row waits rather than writing a verdict. A crashed badge means the pane process genuinely died: a harness exit, a reboot that took the tmux server with it, or an OOM kill. Auto-restart is opt-in, not default. Only subshells whose preset enables Auto-restart on exit are revived, with exponential backoff, and Crashed (the final form) is what you see after the backoff ladder gives up.
Fix. Open the subshell's log. The transcript holds the pane's last words, and the harness usually said why. Restart relaunches the same row and resumes the conversation when its transcript survived (Launch and manage subshells). If the whole machine rebooted and panes are gone, they are gone on that machine; relaunch.
Other pages
- Service and autostart: what supervision changes, and what stays off the dashboard
- Update the server and Update a node: what an update does and rolls back
Last updated on