Subshell Docs

Install Subshell Server on a Mac, start it as a background service, and open its setup page.

Install Subshell Server on an Apple silicon or Intel Mac, start it as a background service, and open its setup page in a browser.

Before you start

A Mac, Apple silicon (darwin-arm64) or Intel (darwin-x64). Both are published server targets.
A browser on that Mac.
tmux, or a way to install it. init checks for tmux before it writes anything; an interactive run whose Mac lacks it can install it on the spot with Homebrew, with MacPorts if the machine has that instead, and by installing Homebrew itself if it has neither. The rungs that escalate ask for your admin password. Declining ends init with nothing written, so installing tmux and re-running is the whole fix.

Install and start the server

Open a terminal on the Mac that will run the server and run the install script:
```
curl -fsSL https://subshell.sh/install-server.sh | bash
```
The script detects your platform, finds your platform's binary from the newest cli-server release, and checks the download against the release's published .sha256 digest before it runs anything. It installs the binary to ~/.local/bin/subshell-server and starts subshell-server init.
init asks for the port, address, base URL, extra trusted origins, and database path. Each question has a default, so you can press Enter through them. If ~/.local/bin is not on your PATH, it offers to add it: yes, the default, appends export PATH="$HOME/.local/bin:$PATH" to ~/.zprofile, creating that file if needed, and to ~/.zshrc only if one already exists.
Answer the last question, which decides how the server runs:
```
Run Subshell Server in the background and start it at login?
```
Choose Yes. On macOS this registers a launchd agent, with no sudo. With --yes, every question above is answered yes at once, each by an announced line; on a tmux-less Mac that includes the install, with any password prompt asked on your terminal. A run with no terminal to ask installs no service, prints the PATH line as instructions instead of an offer, and says what it skipped. On a Mac that also lacks tmux, the run stops at that check first, with nothing written.

When init finishes, it prints the address to open:

Open http://localhost:3080/setup in a browser to create the admin account.

Open the setup page

Open that address in a browser and create the first account. That first account is the administrator.

Do this before others can reach the machine

The setup page is public until the first account exists, so you can create one. On a shared network, anyone who opens the page before you creates the administrator account instead.

With the account created, continue to Your first subshell. Its wizard confirms tmux for the browser flow, and on a Mac its Install tmux screen can run the Homebrew install because that command needs no password.

Or use the desktop app

If you would rather have a window than a terminal, the Subshell Server app is the GUI route to the same server. It ships the server binary inside it, so nothing is downloaded on first run, and it is a signed, notarized .dmg for Apple silicon and Intel Macs, macOS 13 or later. Its setup assistant installs tmux when it is missing, starts the server on one press, and opens the dashboard in the same window. Install with the desktop app covers it screen by screen.

Notes

The binary is self-contained: the web UI is embedded, so the Mac needs no Bun, no checkout, and no separate frontend to serve.
init stores its settings in ~/.config/subshell-server/config.env and generates the sign-in secret once. A second run keeps the existing secret.
Every configuration question init asks has an environment-variable spelling for unattended runs; Install by hand lists them. The database path is the exception: it keeps its default unless you run init --db-path yourself. The PATH offer and the tmux check have no variable at all: a terminal gets those questions, and --yes answers them.
To reach the server from another machine, browse to an address that machine can reach and that the instance trusts. Networking and addresses explains which addresses a browser can sign in from.
If something looks wrong, run subshell-server status first. It reports the active settings, whether tmux and the port are up, and whether the admin account exists, and it does this without starting anything.
A machine outside the published targets (linux-x64, linux-arm64, darwin-arm64, darwin-x64) is refused by name, never silently mis-resolved.

Other install methods

Install on Linux · the desktop setup app · Docker

Edit on GitHub

Install on macOS