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- Open
http://localhost:3080/setupon the Docker host. - Create the admin account.
- 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:latestOpen 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.
Last updated on
