Install on Linux

Install Subshell Server on an x86-64 or arm64 Linux machine, start it as a background service, and open its setup page in a browser.

Before you start

• A Linux machine you can sign in to, x86-64 or arm64.
• A browser on that machine, or on another device on the same network.
• tmux, or a way to install it. init checks for tmux before it writes anything; an interactive run whose machine lacks it can install it on the spot with apt-get or dnf. Declining that offer ends init with nothing written, so installing tmux and re-running is the whole fix.

Install and start the server

1. Open a terminal on the machine that will run the server and run the install script:

   curl -fsSL https://subshell.sh/install-server.sh | bash

   The script finds your platform, downloads 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.

2. 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.

3. Answer the last question, which decides how the server runs:

   Run Subshell Server in the background and start it at login?

   Choose Yes. This installs a per-user systemd service, with no sudo. With --yes, every question above is answered yes at once, each by an announced line. 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 host that also lacks tmux, the run stops at that check first, with nothing written.

4. 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.

With the account created, continue to Your first subshell.

Notes

• The binary is self-contained: the web UI is embedded, so the machine 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 macOS · the desktop setup app · Docker

Edit on GitHub