Subshell Docs

Run the server in Proxmox LXC

Deploy Subshell Server in a dedicated Proxmox LXC container.

Before you start

Use a Proxmox VE 8 or newer host where you can create containers as root. The server container defaults to a 40 GB disk; the minimum is 16 GB, and a smaller number only fits a thin-provisioned storage you watch. lvm-thin and ZFS allocate only what the container writes, so the default costs the pool nothing it hasn't used. The helper downloads a Debian template and creates an unprivileged container with nesting enabled for Docker.

Review the server helper before running it. The server helper and node helper create different kinds of installation.

Install

Download the helper on the Proxmox host:

curl -fsSL https://subshell.sh/proxmox-server.sh -o proxmox-server.sh
bash proxmox-server.sh
  1. Choose installation in the helper's menu.
  2. Review the container ID, storage, bridge, resources, and hostname.
  3. Enter any additional browser IPs, domains, or full URLs as a comma-separated list. Bare IPs and domains use HTTP and your selected web port; use full HTTPS URLs for proxies.
  4. Complete the installation and open the setup address it prints.
  5. Create the first admin account.

The helper installs Docker inside the container and runs the published server image. It detects the container's address and saves it as the server's base URL before startup, so you can create the admin account from the printed address. Server data and this configuration remain in the mounted data directory across updates.

If you plan to use a DNS name or reverse proxy, set APP_BASE_URL to that browser URL when launching the helper:

APP_BASE_URL=https://subshell.example.com bash proxmox-server.sh install

After signing in as an administrator, open Settings → Server Settings → Networking → Addresses to change the public base URL or additional browser addresses. See Addresses and trusted origins for the complete procedure, and Files and paths for the server configuration inside the container.

Maintain the installation

Use the helper's update operation to pull the newest published image and recreate the container. Updates follow latest unless you pass a tag, which applies to that run:

SUBSHELL_VERSION=3.3.1 bash proxmox-server.sh update

Don't replace the binary inside a running image with the server's CLI update command.

The helper also exposes backup, restore, and removal operations. Backups contain instance credentials and require protected storage.

Container removal

Removing the LXC container can remove the server and its data. Verify a usable backup before confirming removal.

Next steps

For a separate machine that runs agents, use Proxmox nodes. Review Backups and restoration.

Mesh clients installed in the LXC

Subshell runs in Docker inside the Debian LXC. NetBird or another mesh client installed directly in Debian stays installed when the helper updates Subshell, because the update replaces the Docker container, not the LXC.

The dashboard's network plugins check inside Docker. They can't detect or manage a mesh client installed in the surrounding LXC; a “not installed” status there doesn't mean the Debian client stopped working. Manage that client in Debian and add its IPs or domains under Settings → Server Settings → Networking → Addresses. See Addresses for the browser address settings.

Edit on GitHub

Last updated on

On this page