Eric Curtin
b332ffdf7d
Move default_sandbox_image() and SUPERVISOR_IMAGE_BINARY_PATH into openshell-core so all compute drivers share a single authoritative definition. Eliminates four identical copies of default_sandbox_image() and two identical copies of SUPERVISOR_IMAGE_BINARY_PATH. Implement ProviderPlugin for ProviderDiscoverySpec to remove the repeated three-method delegation boilerplate from eight simple provider modules. Each now declares only a SPEC constant; the blanket impl handles id(), discover_existing(), and credential_env_vars().
openshell-driver-docker
Docker-backed compute driver for local OpenShell gateways.
The driver manages sandbox containers through the local Docker daemon with the
bollard client. It is intended for developer environments where Docker is
already available and running Kubernetes would be unnecessary.
Runtime Model
The gateway runs as a host process. The Docker driver creates one container per
sandbox and starts the openshell-sandbox supervisor inside that container. The
supervisor then creates the nested sandbox namespace for the agent process.
Docker containers currently use host networking. This lets a supervisor reach a
gateway bound to 127.0.0.1 without requiring a separate bridge listener, NAT
rule, or userland proxy. The container also receives
host.openshell.internal -> 127.0.0.1 so local host services have a stable
OpenShell-owned name.
Container Contract
The driver-controlled container settings are part of the sandbox security contract:
| Setting | Purpose |
|---|---|
user = "0" |
The supervisor needs root inside the container to prepare namespaces, mounts, Landlock, and seccomp. |
network_mode = "host" |
Lets the supervisor call back to loopback gateway endpoints. |
cap_add |
Grants supervisor-only capabilities required for namespace setup and process inspection. |
apparmor=unconfined |
Avoids Docker's default profile blocking required mount operations. |
restart_policy = unless-stopped |
Keeps managed sandboxes resumable across daemon or gateway restarts. |
| CDI GPU request | Uses the sandbox gpu_device value when set; otherwise requests all NVIDIA GPUs when the sandbox spec asks for GPU support and daemon CDI support is detected. |
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:
supervisor_binin[openshell.drivers.docker].- A sibling
openshell-sandboxnext to the runningopenshell-gatewaybinary. - A local Linux cargo target build for the Docker daemon architecture.
supervisor_imagein[openshell.drivers.docker], or the release-matched default supervisor image, extracting/openshell-sandbox.
Release and Docker-image gateway builds bake the matching supervisor image tag
into the binary at compile time. The default Docker supervisor image is not
:latest unless a custom build explicitly sets that tag.
Callback and TLS
OPENSHELL_ENDPOINT is injected from the gateway's configured gRPC endpoint
without rewriting. Because the container uses host networking, loopback
endpoints such as http://127.0.0.1:8080 resolve to the host gateway.
For HTTPS endpoints, the server certificate must include the endpoint host as a subject alternative name. Docker sandboxes also need the client TLS bundle mounted into the container and exposed with:
OPENSHELL_TLS_CAOPENSHELL_TLS_CERTOPENSHELL_TLS_KEY
HTTP endpoints reject TLS material because the supervisor would not use it.
Environment Ownership
The driver merges template environment and sandbox spec environment first, then overwrites security-critical keys:
OPENSHELL_ENDPOINTOPENSHELL_SANDBOX_IDOPENSHELL_SANDBOXOPENSHELL_SSH_SOCKET_PATHOPENSHELL_SANDBOX_COMMAND- TLS path variables when HTTPS is enabled
Do not allow sandbox images or templates to override these values.