Subshell Docs

Run Subshell in Docker

Run the published Subshell server image with persistent data.

Before you start

Install Docker and make a data directory writable by the container's runtime user. Decide which project directories and agent credentials the container may access.

The published image is ghcr.io/subshell-ai/subshell. The repository's Compose example includes host-specific credential mounts; review them before using it.

Start a minimal server

This example publishes port 3080 and mounts your projects at the same absolute path inside the container:

mkdir -p "$HOME/.config/subshell-server" "$HOME/projects"
docker run -d --name subshell --restart unless-stopped -e SUBSHELL_CONTAINER_RESTART=1 \
  --user "$(id -u):$(id -g)" \
  -p 3080:3080 \
  -v "$HOME/.config/subshell-server:/data" \
  -v "$HOME/projects:$HOME/projects" \
  -e DATABASE_PATH=/data/subshell.db \
  -e APP_BASE_URL=http://localhost:3080 \
  ghcr.io/subshell-ai/subshell:latest
  1. Open http://localhost:3080/setup on the Docker host.
  2. Create the admin account.
  3. Confirm that the mounted project directory is available in the launch picker.

For another device or proxy, set APP_BASE_URL to the actual browser URL in your Docker command or Compose environment and recreate the container. For example, use -e APP_BASE_URL=http://192.168.1.20:3080 when that is your Docker host's address. Docker bridge networking hides the host's addresses from the server, so loading the page by another address can succeed while signup returns “Invalid origin.” See Addresses and trusted origins for additional browser URLs. Files and paths explains the configuration files and persistent state; this example mounts the host directory at /data.

Automatic LAN access on Linux

On a Linux Docker host, host networking lets the server discover and trust the host's own LAN addresses automatically, just as a native CLI installation does:

mkdir -p "$HOME/.config/subshell-server" "$HOME/projects"
docker run -d --name subshell --restart unless-stopped -e SUBSHELL_CONTAINER_RESTART=1 \
  --user "$(id -u):$(id -g)" \
  --network host \
  -v "$HOME/.config/subshell-server:/data" \
  -v "$HOME/projects:$HOME/projects" \
  -e DATABASE_PATH=/data/subshell.db \
  ghcr.io/subshell-ai/subshell:latest

Open http://your-host-ip:3080/setup. Host networking uses the host's ports directly, so port 3080 must be available. For a DNS name or reverse proxy, set APP_BASE_URL to that browser URL. On Docker Desktop, use the bridged example above and set APP_BASE_URL to the URL you open.

Credentials and persistence

The image's home directory is /home/subshell. Agent credentials mounted from the host must use that container destination. Running under a different UID may also require supplying your own agent binaries and state.

Credential mounts

Agents can read credentials mounted into their runtime account. Mount only credentials and projects you intend those agents to use.

Persist /data, including config.env, the SQLite database, and other instance state. Updating replaces the image, not the running server binary.

Next steps

See Update the server, Backups and restoration, and HTTPS and reverse proxies.

Save addresses and restart

Change browser addresses in Settings → Server Settings → Networking → Addresses. Other addresses apply immediately; changes to the public base URL, bind address, or listening port need a restart. The examples above pair SUBSHELL_CONTAINER_RESTART=1 with --restart unless-stopped, allowing the server to offer a dashboard restart. Restarting the Docker container closes running subshells. Only set this variable when Docker is configured to restart the container after the server exits.

For an existing container without that variable, save the settings and run docker restart subshell on its Docker host. On a Proxmox install, run pct exec <CT ID> -- docker restart subshell on the Proxmox host. See Addresses for the full settings reference.

Edit on GitHub

Last updated on

On this page