fix(docker): use supervisor image entrypoint path

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -63,6 +63,7 @@ Use gateway metadata, deployment values, or the user's setup notes to identify t
 docker info
 docker ps --filter name=openshell
 docker logs <container> --tail=200
+docker run --rm --entrypoint /openshell-sandbox "${OPENSHELL_DOCKER_SUPERVISOR_IMAGE:-ghcr.io/nvidia/openshell/supervisor:latest}" --version
 openshell status
 ```
 
@@ -71,6 +72,7 @@ Common findings:
 - Docker daemon unavailable: start Docker Desktop or Docker Engine.
 - Gateway process stopped: inspect exit status and logs.
 - Sandbox image missing or pull denied: verify image reference and registry credentials.
+- Docker driver cannot initialize because it cannot find `openshell-sandbox`: verify `OPENSHELL_DOCKER_SUPERVISOR_BIN`, the sibling binary next to `openshell-gateway`, or the configured supervisor image contains `/openshell-sandbox`.
 - Sandbox never registers: check gateway logs and supervisor callback endpoint.
 
 For source checkout development, restart the local gateway with:

.github/workflows/docker-build.yml

@@ -238,7 +238,6 @@ jobs:
             --cache-to "type=gha,mode=max,scope=${{ inputs.component }}-${{ matrix.arch }}"
 
       - name: Smoke check ${{ inputs.component }} image
-        if: ${{ !inputs.push }}
         run: |
           set -euo pipefail
           image="${IMAGE_REGISTRY}/${{ inputs.component }}:${IMAGE_TAG}"

architecture/build.md

@@ -12,7 +12,7 @@ OpenShell builds these main artifacts:
 |---|---|
 | Gateway binary | `crates/openshell-server` |
 | CLI package and Python SDK | `python/openshell` plus Rust binaries where packaged |
-| Gateway container image | `deploy/docker/Dockerfile.images` |
+| Gateway and supervisor container images | `deploy/docker/Dockerfile.images` |
 | Helm chart | `deploy/helm/openshell` |
 | VM driver/runtime assets | `crates/openshell-driver-vm` |
 | Published docs site | `docs/` rendered by Fern config in `fern/` |

architecture/compute-runtimes.md

@@ -38,7 +38,7 @@ The supervisor must be available inside each sandbox workload:
 
 | Runtime | Delivery model |
 |---|---|
-| Docker | Bind-mounted or extracted supervisor binary configured by the gateway. |
+| Docker | Bind-mounted local supervisor binary, or a binary extracted from the configured supervisor image. |
 | Podman | Read-only OCI image volume containing the supervisor binary. |
 | Kubernetes | Sandbox pod image or pod template configuration. |
 | VM | Embedded in the guest rootfs bundle. |

crates/openshell-driver-docker/README.md

@@ -34,6 +34,17 @@ contract:
 
 The agent child process does not retain these supervisor privileges.
 
+## Supervisor Binary Resolution
+
+The Docker driver bind-mounts a host-side Linux `openshell-sandbox` binary into
+each sandbox container. Resolution order is:
+
+1. `--docker-supervisor-bin` / `OPENSHELL_DOCKER_SUPERVISOR_BIN`.
+2. A sibling `openshell-sandbox` next to the running `openshell-gateway` binary.
+3. A local Linux cargo target build for the Docker daemon architecture.
+4. `--docker-supervisor-image` / `OPENSHELL_DOCKER_SUPERVISOR_IMAGE`, or the
+   release-matched default supervisor image, extracting `/openshell-sandbox`.
+
 ## Callback and TLS
 
 `OPENSHELL_ENDPOINT` is injected from the gateway's configured gRPC endpoint

crates/openshell-driver-docker/src/lib.rs

@@ -1759,7 +1759,7 @@ async fn extract_supervisor_binary_bytes(docker: &Docker, image: &str) -> CoreRe
             ),
             ContainerCreateBody {
                 image: Some(image.to_string()),
-                entrypoint: Some(vec!["/openshell-sandbox".to_string()]),
+                entrypoint: Some(vec![SUPERVISOR_IMAGE_BINARY_PATH.to_string()]),
                 cmd: Some(Vec::new()),
                 ..Default::default()
             },

crates/openshell-driver-kubernetes/src/driver.rs

@@ -688,19 +688,19 @@ fn supervisor_volume_mount() -> serde_json::Value {
 
 /// Path of the supervisor binary inside the supervisor image.
 ///
-/// The supervisor image places the binary at the filesystem root and ships
-/// nothing else. We invoke it directly — there is no shell, `cp`, or PATH
-/// resolution available inside the image.
+/// The supervisor image places the binary at the filesystem root. We invoke
+/// it directly so the init path does not depend on shell utilities or PATH
+/// resolution inside the image.
 const SUPERVISOR_IMAGE_BINARY_PATH: &str = "/openshell-sandbox";
 
 /// Build the init container that copies the supervisor binary into the emptyDir.
 ///
-/// The supervisor image contains only the supervisor binary at
-/// `/openshell-sandbox`. We invoke that binary with the `copy-self`
-/// subcommand so it copies itself into the shared emptyDir volume, where the
-/// agent container then executes it from a fixed, writable path. This pattern
-/// (binary self-copy) avoids requiring `sh`/`cp` in the supervisor image and
-/// mirrors the approach used by argoexec's emissary executor.
+/// The supervisor image contains the supervisor binary at `/openshell-sandbox`.
+/// We invoke that binary with the `copy-self` subcommand so it copies itself
+/// into the shared emptyDir volume, where the agent container then executes it
+/// from a fixed, writable path. This pattern (binary self-copy) avoids requiring
+/// `sh`/`cp` in the supervisor image and mirrors the approach used by argoexec's
+/// emissary executor.
 fn supervisor_init_container(
     supervisor_image: &str,
     supervisor_image_pull_policy: &str,
@@ -1559,8 +1559,8 @@ mod tests {
         assert_eq!(init_containers[0]["image"], "supervisor-image:latest");
         assert_eq!(init_containers[0]["imagePullPolicy"], "IfNotPresent");
 
-        // The supervisor image ships only the binary (no shell). The init
-        // container must invoke the binary directly with `copy-self <DEST>`.
+        // The init container must invoke the binary directly with
+        // `copy-self <DEST>` rather than depending on shell utilities.
         let init_command = init_containers[0]["command"]
             .as_array()
             .expect("init container command should be set");
@@ -1573,7 +1573,7 @@ mod tests {
         );
         assert!(
             !init_command.iter().any(|v| v == "sh"),
-            "init container must not depend on a shell (supervisor image ships only the binary)"
+            "init container must not depend on a shell"
         );
 
         // Agent container command should be overridden to the emptyDir path

crates/openshell-sandbox/src/main.rs

@@ -19,9 +19,9 @@ use openshell_sandbox::run_sandbox;
 
 /// Subcommand name used to self-copy the supervisor binary into a shared volume.
 ///
-/// The supervisor image only ships the binary itself, so init containers
-/// cannot rely on `sh`/`cp` to copy the binary out. Invoking the binary itself
-/// with this argument performs the copy in pure Rust.
+/// Init containers invoke the binary directly instead of relying on `sh`/`cp`
+/// to copy the binary out. Invoking the binary itself with this argument
+/// performs the copy in pure Rust.
 const COPY_SELF_SUBCOMMAND: &str = "copy-self";
 
 /// `OpenShell` Sandbox - process isolation and monitoring.
@@ -148,9 +148,8 @@ fn copy_self(dest: &str) -> Result<()> {
 
 fn main() -> Result<()> {
     // Handle `copy-self <DEST>` before clap so it works without any of the
-    // sandbox flags. The supervisor image only ships the binary itself, and
-    // Kubernetes init containers invoke this path to seed an emptyDir volume
-    // that the agent container then executes from.
+    // sandbox flags. Kubernetes init containers invoke this path to seed an
+    // emptyDir volume that the agent container then executes from.
     let raw_args: Vec<String> = std::env::args().collect();
     if raw_args.get(1).map(String::as_str) == Some(COPY_SELF_SUBCOMMAND) {
         let dest = raw_args.get(2).ok_or_else(|| {

deploy/docker/Dockerfile.images

@@ -120,3 +120,4 @@ CMD ["--bind-address", "0.0.0.0", "--port", "8080"]
 # the binary, breaking the Kubernetes init-container path.
 FROM nvcr.io/nvidia/base/ubuntu:noble-20251013 AS supervisor
 COPY --from=supervisor-binary /build/out/openshell-sandbox /openshell-sandbox
+ENTRYPOINT ["/openshell-sandbox"]

tasks/docker.toml

@@ -27,7 +27,7 @@ run = "tasks/scripts/docker-build-image.sh gateway"
 hide = true
 
 ["build:docker:supervisor"]
-description = "Build the supervisor image (FROM scratch, binary only)"
+description = "Build the supervisor image"
 run = "tasks/scripts/docker-build-image.sh supervisor"
 hide = true