docs(container-gateway): fix Docker driver setup for containerized gateway

deploy/docker/docker-compose.yml

@@ -0,0 +1,128 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# OpenShell gateway — docker-compose setup (Docker compute driver)
+#
+# Prerequisites:
+#   - Docker Desktop (Windows / macOS) or Docker Engine + Compose plugin (Linux)
+#   - The openshell CLI installed on your workstation
+#
+# Quick start:
+#
+#   1. Start the gateway:
+#        docker compose up -d
+#
+#   2. Register the gateway with the CLI (one-time):
+#        openshell gateway add http://localhost:8080 --name openshell-docker
+#
+#   3. Configure an AI provider (example: Anthropic):
+#        ANTHROPIC_API_KEY=sk-ant-... \
+#          openshell provider create --type anthropic --from-existing
+#
+#   4. Create a sandboxed agent — Claude Code or OpenClaw:
+#        openshell sandbox create -- claude
+#        openshell sandbox create --from openclaw
+#
+# Sandbox containers are managed by the gateway, not by this Compose file.
+# Each `openshell sandbox create` call launches a fresh container; the gateway
+# tracks their lifecycle.
+#
+# Configuration:
+#   All gateway and driver settings live in gateway.toml in this directory.
+#   Three values cannot be expressed in the TOML file and remain as env vars:
+#     - OPENSHELL_DB_URL  (explicitly blocked from the config file to prevent
+#                          secrets from being committed to VCS)
+#     - XDG_DATA_HOME / HOME  (OS-level path-resolution vars outside the
+#                               gateway config schema)
+#
+# command: [] note:
+#   The gateway image's default CMD is ["--bind-address", "0.0.0.0", "--port",
+#   "8080"].  CLI flags beat TOML in the merge order, so without clearing the
+#   CMD the TOML's bind_address = "127.0.0.1:8080" is silently ignored and the
+#   gateway binds 0.0.0.0.  Setting command: [] lets the TOML file own all
+#   gateway settings.
+#
+# Data directory note:
+#   /var/lib/openshell is bind-mounted at the SAME absolute path in both the
+#   host and the container.  This is required so that the supervisor binary
+#   extracted from the supervisor image can be passed to Docker as a host-side
+#   bind-mount source when sandbox containers are created.  Named volumes
+#   cannot be used here because Docker resolves bind-mount sources against the
+#   host filesystem, not the container filesystem.
+#
+# Linux note:
+#   host.docker.internal and host.openshell.internal are not automatically
+#   added on Linux Docker.  Add the following under the gateway service:
+#     extra_hosts:
+#       - "host.docker.internal:host-gateway"
+#       - "host.openshell.internal:host-gateway"
+
+services:
+  gateway:
+    image: ghcr.io/nvidia/openshell/gateway:${IMAGE_TAG:-latest}
+    restart: unless-stopped
+
+    # Clear the default CMD so gateway.toml owns all settings (see note above).
+    command: []
+
+    # This setup is Docker-outside-of-Docker (DooD), not Docker-in-Docker (DinD).
+    # The gateway uses the host's Docker socket to create sibling containers on the
+    # host, rather than running a nested Docker daemon.  DooD does NOT require
+    # --privileged; it only needs read/write access to /var/run/docker.sock.
+    #
+    # Run as UID 0 so the gateway can:
+    #   - write the extracted supervisor binary to /var/lib/openshell
+    #   - access /var/run/docker.sock (typically owned by root or the docker group)
+    # Distroless images have no /etc/passwd, so the numeric UID must be used.
+    # This is appropriate for local development.  Production deployments
+    # should use a dedicated non-root UID with explicit docker-group membership.
+    user: "0"
+
+    ports:
+      # gRPC / control-plane API  (used by the openshell CLI and sandbox callbacks)
+      # The Docker driver injects host.openshell.internal:<gateway-port> into sandbox
+      # containers as the callback endpoint.  The gateway's internal port is 8080, so
+      # host port 8080 must be published at the same number so that
+      # host.openshell.internal:8080 routes to the gateway container.
+      # gateway.toml binds to 127.0.0.1 — the Docker driver adds the bridge listener
+      # automatically so sandbox containers can reach the gateway without 0.0.0.0.
+      - "127.0.0.1:${OPENSHELL_PORT:-8080}:8080"
+      # Health endpoint  (GET /healthz, GET /readyz)
+      - "127.0.0.1:${OPENSHELL_HEALTH_PORT:-8081}:8081"
+
+    volumes:
+      # Docker socket — lets the gateway create and manage sandbox containers.
+      - /var/run/docker.sock:/var/run/docker.sock
+
+      # Data directory — must be a bind-mount with source == target so that
+      # paths written inside the container are resolvable by Docker when it
+      # creates sandbox containers (see note above).
+      # /var/lib/openshell is intentionally not namespaced to a sub-path
+      # (e.g. /var/lib/openshell/gateway): the path must match exactly on
+      # both the host and inside the container, and a single gateway per host
+      # is the expected topology.
+      - type: bind
+        source: /var/lib/openshell
+        target: /var/lib/openshell
+        bind:
+          create_host_path: true
+
+      # TOML config — all gateway and driver settings live here.
+      - type: bind
+        source: ./gateway.toml
+        target: /etc/openshell/gateway.toml
+        read_only: true
+
+    environment:
+      # Point the gateway at the TOML config file mounted above.
+      OPENSHELL_GATEWAY_CONFIG: /etc/openshell/gateway.toml
+
+      # Database URL cannot be set in the TOML config file — it is explicitly
+      # blocked there to prevent secrets from being committed to VCS.
+      OPENSHELL_DB_URL: "sqlite:/var/lib/openshell/gateway.db?mode=rwc"
+
+      # XDG path variables are OS-level; they are not part of the gateway config
+      # schema.  Setting them ensures the extracted supervisor binary lands in the
+      # bind-mounted directory so its path is resolvable by the host Docker daemon.
+      XDG_DATA_HOME: /var/lib/openshell
+      HOME: /var/lib/openshell

deploy/docker/gateway.toml

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# OpenShell gateway TOML configuration — Docker compute driver.
+#
+# This file is the primary configuration source for docker-compose.yml in this
+# directory.  It is mounted read-only at /etc/openshell/gateway.toml inside the
+# gateway container and loaded via OPENSHELL_GATEWAY_CONFIG.
+#
+# Why docker-compose.yml sets command: []:
+#   The gateway image's default CMD passes --bind-address 0.0.0.0 --port 8080
+#   as explicit CLI flags.  CLI flags beat the TOML file in the merge order, so
+#   bind_address = "127.0.0.1:8080" below would be silently ignored without
+#   clearing the CMD first.
+#
+# grpc_endpoint note:
+#   host.docker.internal is automatically resolvable from containers on
+#   Docker Desktop (Windows / macOS).  On Linux, add extra_hosts to the
+#   gateway service:
+#     extra_hosts:
+#       - "host.docker.internal:host-gateway"
+#       - "host.openshell.internal:host-gateway"
+
+[openshell]
+version = 1
+
+[openshell.gateway]
+# Bind to loopback only.  The Docker driver adds an extra listener on the
+# bridge interface automatically so sandbox containers can reach the gateway.
+bind_address        = "127.0.0.1:8080"
+health_bind_address = "127.0.0.1:8081"
+log_level           = "info"
+compute_drivers     = ["docker"]
+disable_tls         = true
+
+[openshell.drivers.docker]
+# Default image pulled for `openshell sandbox create` without --from.
+default_image     = "ghcr.io/nvidia/openshell-community/sandboxes/base:latest"
+# Supervisor image from which the openshell-sandbox binary is extracted on
+# first start.  The binary is cached to XDG_DATA_HOME and reused on restart.
+supervisor_image  = "ghcr.io/nvidia/openshell/supervisor:latest"
+# Only pull images that are not already cached locally.
+image_pull_policy = "IfNotPresent"
+# Prefix applied to sandbox container names.
+sandbox_namespace = "openshell"
+# Address sandbox containers use to call back to the gateway.
+# The Docker driver replaces the host with host.openshell.internal and the
+# port with the gateway's own bind port (8080).  Only the scheme survives.
+# The gateway must be published on port 8080 on the Docker host so that
+# host.openshell.internal:8080 resolves to the gateway container.
+grpc_endpoint     = "http://host.openshell.internal:8080"

docs/about/container-gateway.mdx

@@ -12,37 +12,79 @@ Use this approach when you want to run the OpenShell gateway as a container inst
 
 The gateway image is published at `ghcr.io/nvidia/openshell/gateway`.
 
+## Prerequisites for the Docker Driver
+
+When the gateway runs as a container and creates Docker-backed sandboxes, the gateway container
+communicates with the host Docker daemon via the mounted socket. This requires three things beyond
+a basic `docker run`:
+
+1. **Docker socket access.** The gateway process must be able to read and write the Docker socket.
+   Add the `docker` group (or the GID of `/var/run/docker.sock`) so the socket is accessible
+   without running as root.
+
+2. **gRPC endpoint.** Sandbox containers call back to the gateway over the `OPENSHELL_GRPC_ENDPOINT`
+   address. Set this to `http://127.0.0.1:8080` so the driver knows the scheme and port. The
+   docker driver automatically binds the gateway to the bridge network interface so sandbox
+   containers can reach it — you do not need to expose the port on `0.0.0.0`.
+
+3. **Supervisor binary on the host.** The gateway bind-mounts the `openshell-sandbox` supervisor
+   binary into each sandbox container. Because bind-mount paths are resolved by the host Docker
+   daemon (not inside the gateway container), the binary must exist at a path on the host
+   filesystem. Extract it before starting the gateway and mount it at the same path.
+
 ## Quick Start
 
-This example runs the gateway locally with TLS disabled. It is suitable for development on a single machine. Binding to `127.0.0.1` prevents remote access without authentication.
+Extract the supervisor binary to the host once, then start the gateway:
+
+```shell
+mkdir -p ~/openshell/supervisor
+docker create --name tmp-supervisor ghcr.io/nvidia/openshell/supervisor:latest
+docker cp tmp-supervisor:/openshell-sandbox ~/openshell/supervisor/openshell-sandbox
+docker rm tmp-supervisor
+chmod +x ~/openshell/supervisor/openshell-sandbox
+```
+
+Start the gateway:
 
 ```shell
 docker run -d \
   --name openshell-gateway \
   --restart unless-stopped \
+  --group-add docker \
   -p 127.0.0.1:8080:8080 \
   -v openshell-state:/var/openshell \
   -v /var/run/docker.sock:/var/run/docker.sock \
+  -v ~/openshell/supervisor/openshell-sandbox:~/openshell/supervisor/openshell-sandbox:ro \
   -e OPENSHELL_DRIVERS=docker \
+  -e OPENSHELL_GRPC_ENDPOINT=http://127.0.0.1:8080 \
+  -e OPENSHELL_DOCKER_SUPERVISOR_BIN=~/openshell/supervisor/openshell-sandbox \
   -e OPENSHELL_DB_URL=sqlite:/var/openshell/openshell.db \
   -e OPENSHELL_DISABLE_TLS=true \
   ghcr.io/nvidia/openshell/gateway:latest
 ```
 
-Register the gateway with the CLI:
+Register the gateway with the CLI. If running on the same machine, use `--local`:
 
 ```shell
 openshell gateway add http://127.0.0.1:8080 --local --name local
 ```
 
+If registering from a different machine on the same network, use the host IP and `--remote`:
+
+```shell
+openshell gateway add http://HOST_IP:8080 --remote --name remote
+```
+
 Confirm the CLI can reach the gateway:
 
 ```shell
 openshell status
 ```
 
 <Warning>
-Disabling TLS removes authentication. Binding to `127.0.0.1` limits access to the local machine. If you expose the port on `0.0.0.0`, enable TLS and local mTLS user authentication, or put the gateway behind a trusted proxy with its own authentication.
+Disabling TLS removes authentication. This example binds to `127.0.0.1` so only local
+connections are accepted. To accept remote connections, enable mTLS or restrict access with
+a firewall rule.
 </Warning>
 
 ## Full mTLS Setup
@@ -58,7 +100,9 @@ docker run --rm \
   -v "$HOME/.local/state/openshell:/home/openshell/.local/state/openshell" \
   -v "$HOME/.config/openshell:/home/openshell/.config/openshell" \
   ghcr.io/nvidia/openshell/gateway:latest \
-  generate-certs --output-dir /home/openshell/.local/state/openshell/tls
+  generate-certs \
+    --output-dir /home/openshell/.local/state/openshell/tls \
+    --server-san host.openshell.internal
 ```
 
 This writes the server and client certificates under `~/.local/state/openshell/tls/`, writes sandbox JWT signing keys under `~/.local/state/openshell/tls/jwt/`, and copies the client bundle to `~/.config/openshell/gateways/openshell/mtls/` so the CLI picks it up automatically.
@@ -69,10 +113,14 @@ Start the gateway with mTLS enabled:
 docker run -d \
   --name openshell-gateway \
   --restart unless-stopped \
+  --group-add docker \
   -p 127.0.0.1:8080:8080 \
   -v "$HOME/.local/state/openshell:/home/openshell/.local/state/openshell" \
   -v /var/run/docker.sock:/var/run/docker.sock \
+  -v ~/openshell/supervisor/openshell-sandbox:~/openshell/supervisor/openshell-sandbox:ro \
   -e OPENSHELL_DRIVERS=docker \
+  -e OPENSHELL_GRPC_ENDPOINT=https://127.0.0.1:8080 \
+  -e OPENSHELL_DOCKER_SUPERVISOR_BIN=~/openshell/supervisor/openshell-sandbox \
   -e OPENSHELL_DB_URL=sqlite:/home/openshell/.local/state/openshell/openshell.db \
   -e OPENSHELL_LOCAL_TLS_DIR=/home/openshell/.local/state/openshell/tls \
   -e OPENSHELL_TLS_CERT=/home/openshell/.local/state/openshell/tls/server/tls.crt \
@@ -93,20 +141,41 @@ openshell gateway add https://127.0.0.1:8080 --local --name local
 
 ## Docker Compose
 
-Save the following as `compose.yml`. This uses the TLS-disabled configuration bound to localhost, suitable for local development.
+The following `compose.yml` runs the gateway with the Docker driver on an immutable OS or any
+Docker host. It includes all required configuration for sandbox containers to call back to the
+gateway.
+
+Before starting, extract the supervisor binary to a host path. The path must be the same on
+both the host and inside the gateway container because the host Docker daemon uses it as a
+bind-mount source when creating sandbox containers:
+
+```shell
+mkdir -p ~/openshell/supervisor
+docker create --name tmp-supervisor ghcr.io/nvidia/openshell/supervisor:latest
+docker cp tmp-supervisor:/openshell-sandbox ~/openshell/supervisor/openshell-sandbox
+docker rm tmp-supervisor
+chmod +x ~/openshell/supervisor/openshell-sandbox
+```
+
+Save the following as `~/openshell/compose.yml`, substituting your home directory for `HOME`:
 
 ```yaml
 services:
   gateway:
     image: ghcr.io/nvidia/openshell/gateway:latest
     restart: unless-stopped
+    group_add:
+      - docker
     ports:
       - "127.0.0.1:8080:8080"
     volumes:
       - openshell-state:/var/openshell
       - /var/run/docker.sock:/var/run/docker.sock
+      - HOME/openshell/supervisor/openshell-sandbox:HOME/openshell/supervisor/openshell-sandbox:ro
     environment:
       OPENSHELL_DRIVERS: docker
+      OPENSHELL_GRPC_ENDPOINT: "http://127.0.0.1:8080"
+      OPENSHELL_DOCKER_SUPERVISOR_BIN: "HOME/openshell/supervisor/openshell-sandbox"
       OPENSHELL_DB_URL: "sqlite:/var/openshell/openshell.db"
       OPENSHELL_DISABLE_TLS: "true"
 
@@ -120,12 +189,19 @@ Start the gateway:
 docker compose up -d
 ```
 
-Register the gateway with the CLI:
+Register the gateway with the CLI. If registering from the same machine:
 
 ```shell
 openshell gateway add http://127.0.0.1:8080 --local --name local
 ```
 
+If registering from a different machine on the same network, replace `HOST_IP` with the
+machine's LAN address:
+
+```shell
+openshell gateway add http://HOST_IP:8080 --remote --name remote
+```
+
 ## Using Podman
 
 Replace `docker` with `podman` in the commands above. Mount the Podman socket instead of the Docker socket and set the driver to `podman`: