OpenShell 0.1.4 — Docker sandbox supervisor fails to fetch startup configuration on macOS #4683

User Story

Environment

macOS on Apple Silicon

Docker Desktop Engine 29.8.2

Docker context: desktop-linux

OpenShell 0.1.4

Local gateway with mTLS

Observed behavior

The OpenShell gateway reports healthy, and openshell doctor check passes.

Creating a sandbox using an Alpine image succeeds at the gateway level, but the supervisor fails before the workload becomes ready.

Error:

ControlSupervisorStartFailed
Startup configuration fetch failed after 5 attempts:
failed to connect to OpenShell server

The sandbox remains in Error, with ConfigurationReady: False and ConfigurationPending.

Diagnostics

A separate Docker container can reach the gateway using its CA certificate, with TLS verification enabled.

The test returns HTTP 404 at the root endpoint.

The supervisor also reports log push connect failed.

Docker shows no surviving sandbox containers after failure.

Sandbox debug logs return no output.

Question

Is there a known issue in OpenShell 0.1.4 involving supervisor-to-gateway connectivity on Docker Desktop for macOS? What is the supported, secure configuration that preserves mTLS and does not require broad host-directory sharing?

Problem Statement

OpenShell 0.1.4 fails to start Docker-based sandboxes on macOS with Docker Desktop 29.8.2, even though the local OpenShell gateway is healthy and all prerequisite checks pass.

The sandbox creation request succeeds, but the supervisor cannot establish a gRPC connection to the OpenShell gateway to retrieve its startup configuration. After five retries, the supervisor exits with ControlSupervisorStartFailed, leaving the sandbox in an Error state.

A separate Docker container successfully connects to the gateway using its trusted CA certificate with TLS verification enabled, indicating that basic container-to-host connectivity works. However, the OpenShell supervisor cannot complete its connection.

The root cause is not yet identified. We need to determine whether this is an OpenShell 0.1.4 defect or a Docker Desktop/macOS networking, endpoint, or TLS configuration issue, and identify a supported fix that preserves TLS verification and sandbox isolation.

Impact / Why This Matters

This issue completely blocks the use of OpenShell's Docker-based sandbox functionality on the affected macOS environment.

Although the OpenShell gateway starts successfully and passes prerequisite checks, newly created sandboxes fail before becoming operational. As a result, users cannot execute workloads, validate sandbox security policies, or test isolated agent execution.

The failure also creates a difficult troubleshooting situation: the supervisor container exits and is removed, while sandbox debug logs provide no additional diagnostic information. This makes it difficult to distinguish between networking, TLS, configuration, and runtime compatibility problems.

For organizations evaluating OpenShell for secure, governed AI-agent execution, this is a significant adoption blocker. Sandbox isolation, policy enforcement, and reliable supervisor-to-gateway communication must be validated before sensitive or proprietary workloads can be entrusted to the runtime.

A documented root cause, supported fix, and improved diagnostic error reporting would help users deploy OpenShell securely without weakening TLS verification or host isolation.

Acceptance Criteria

The issue will be considered resolved when the following criteria are met:

1. Successful sandbox startup: OpenShell 0.1.4, or a subsequent fixed release, can create and start Docker-based sandboxes on the affected macOS and Docker Desktop environment without supervisor startup failures.

2. Reliable gateway connectivity: The sandbox supervisor successfully establishes its authenticated gRPC connection to the OpenShell gateway, retrieves its startup configuration, and transmits logs.

3. Successful configuration admission: The sandbox completes configuration validation, transitions from ConfigurationPending to a ready state, and permits authorized workload execution.

4. Security preservation: The solution maintains TLS certificate verification, authenticated gateway communication, sandbox isolation, and default-deny security policies. It must not require disabling TLS verification, exposing the gateway publicly, or granting unnecessarily broad host filesystem access.

5. Functional verification: A basic Alpine-based sandbox can start, execute a simple command, and return its output successfully.

6. Reliable diagnostics: If supervisor startup fails, OpenShell provides actionable error messages identifying whether the failure involves DNS resolution, network connectivity, certificate validation, authentication, or gateway configuration. Diagnostic logs should remain accessible after the supervisor exits.

7. Documented resolution: NVIDIA provides a supported fix or documented configuration procedure for Docker Desktop on macOS, including any required gateway networking or certificate-trust settings.

8. Reproducibility: The corrected configuration consistently supports sandbox creation, startup, shutdown, and subsequent restart without recurring supervisor-to-gateway connection failures.

Reproduction Steps

Environment

• macOS with Apple Silicon
• OpenShell CLI and gateway version 0.1.4
• Docker Desktop Engine 29.8.2
• Docker context: desktop-linux
• Local OpenShell gateway: https://localhost:17670
• TLS certificate verification enabled

Steps to Reproduce

1. Verify Docker prerequisites

Run:

openshell doctor check

Observed result:

Docker ............. ok (version 29.8.2)
DOCKER_HOST ........ (not set, using default socket)
All checks passed.

2. Verify the OpenShell gateway

Run:

openshell gateway info

The local OpenShell gateway reports healthy.

3. Create an isolated Alpine sandbox

Run:

openshell sandbox create --name aretivon-lab --from alpine:3.20 --cpu 1 --memory 512Mi --no-auto-providers --detach

The gateway accepts the sandbox creation request, but the supervisor fails during startup.

4. Inspect the sandbox status

Run:

openshell sandbox get aretivon-lab --output json

Observed results:

"phase": "Error"
"reason": "ControlSupervisorStartFailed"
"status": "False"
"type": "Ready"

The configuration remains pending:

"reason": "ConfigurationPending"
"state": "pending"
"current_policy_version": 0

5. Examine gateway logs

Run:

openshell logs aretivon-lab --source gateway --level debug

The logs show:

openshell_supervisor: Starting sandbox supervision
openshell_supervisor: Fetching sandbox policy via gRPC
Startup configuration fetch failed, retrying
openshell: log push connect failed:
failed to connect to OpenShell server

After five attempts:

Startup configuration fetch failed after 5 attempts:
failed to connect to OpenShell server

6. Inspect sandbox logs

Run:

openshell logs aretivon-lab --source sandbox --level debug

Observed result: No output.

7. Inspect Docker containers

Run:

docker --context desktop-linux ps -a --no-trunc

Observed result: No containers remain, preventing inspection of the failed supervisor container.

8. Independently verify container-to-gateway connectivity

Launch a temporary Alpine container on Docker's bridge network, provide the OpenShell CA certificate through standard input, and use curl --cacert to connect to:

https://host.docker.internal:17670

Observed result:

HTTP 404

This confirms that the gateway is reachable from a separate Docker container with TLS certificate verification enabled. The HTTP 404 is the response from the gateway's root path, not evidence that the supervisor's gRPC connection is working.

Expected Result

The sandbox supervisor establishes an authenticated connection to the gateway, retrieves its startup configuration, completes configuration admission, and starts the sandbox successfully.

Actual Result

The supervisor repeatedly fails to connect to the OpenShell server, exits after five retries, and leaves the sandbox in the Error state.

Reproducibility

The failure has occurred during multiple sandbox creation attempts in this local environment. The exact root cause remains undetermined.

Suggested UX (if applicable)

No response

Environment

Operating System: macOS (exact version not yet confirmed)
Hardware: Apple Silicon Mac
Container Runtime: Docker Desktop, Engine 29.8.2
Docker Context: desktop-linux
OpenShell Version: 0.1.4
OpenShell Gateway: Local gateway named openshell
Gateway Endpoint: https://localhost:17670
Gateway Status: Healthy
TLS: Enabled, using OpenShell's local certificate authority
Compute Driver: Docker
Supervisor Extension: OpenShell 0.1.4
Sandbox Base Image: alpine:3.20
Sandbox Resources: 1 CPU, 512 MiB memory
Provider Configuration: No automatic providers (--no-auto-providers)
Docker Network Tested: Default bridge network
Prerequisite Check: openshell doctor check — all checks passed
Observed Failure: ControlSupervisorStartFailed during supervisor-to-gateway gRPC communication
Sandbox State: Error / ConfigurationPending

Logs