# How OpenSandbox Implements Execd Injection in Sandbox Containers > Discover how OpenSandbox implements execd injection in sandbox containers. Learn about the init container, shared volumes, and entrypoint overrides for seamless daemon integration. - Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox) - Tags: internals - Published: 2026-03-08 --- **OpenSandbox injects the `execd` daemon into sandbox containers using an init container that copies the binary and a bootstrap script into a shared `emptyDir` volume, then overrides the main container's entrypoint to launch the daemon alongside user workloads.** The **execd injection mechanism** enables the `alibaba/OpenSandbox` platform to provide a standardized execution API for code, commands, and file-system access without modifying user container images. This process works transparently across Docker, Kubernetes, and secure runtimes such as gVisor, Kata, and Firecracker. ## The Execd Injection Architecture OpenSandbox implements execd injection through a two-phase build process orchestrated by the `BatchSandboxProvider` class in [`server/src/services/k8s/batchsandbox_provider.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/batchsandbox_provider.py). The provider constructs two critical components: - **`_build_execd_init_container`** (lines 80-88): Creates an init container named `execd-installer` that copies the `execd` binary and [`bootstrap.sh`](https://github.com/alibaba/OpenSandbox/blob/main/bootstrap.sh) script from the execd image into a shared volume - **`_build_main_container`** (lines 96-105): Configures the main container to mount the shared volume at `/opt/opensandbox/bin`, injects the `EXECD` environment variable pointing to `/opt/opensandbox/bin/execd`, and replaces the user entrypoint with the bootstrap script According to the architecture documentation (lines 99-107 in [`docs/architecture.md`](https://github.com/alibaba/OpenSandbox/blob/main/docs/architecture.md)), the Docker runtime follows an analogous pattern: it pulls the execd image, extracts the binary, mounts it into the container filesystem, and rewrites the entrypoint to invoke the bootstrap wrapper. ## Step-by-Step Kubernetes Injection Flow The injection sequence follows five distinct steps that transform a standard pod specification into an OpenSandbox-enabled environment. ### 1. Init Container File Distribution The init container executes a shell command defined in `_build_execd_init_container` to populate the shared volume: ```bash cp ./execd /opt/opensandbox/bin/execd && \ cp ./bootstrap.sh /opt/opensandbox/bin/bootstrap.sh && \ chmod +x /opt/opensandbox/bin/execd /opt/opensandbox/bin/bootstrap.sh ``` This runs before the main container starts, ensuring the binaries exist in the `opensandbox-bin` volume. ### 2. Shared Volume Mounting The provider mounts the `emptyDir` volume named `opensandbox-bin` into both the init container and the main container at `/opt/opensandbox/bin`. This provides a read-only mount point for the execd binary inside the sandbox namespace. ### 3. Entrypoint Interception In `_build_main_container`, the provider replaces the container's original entrypoint with [`/opt/opensandbox/bin/bootstrap.sh`](https://github.com/alibaba/OpenSandbox/blob/main//opt/opensandbox/bin/bootstrap.sh). The original user command is passed as arguments to this wrapper, stored in a `wrapped_command` variable that preserves the intended workload. ### 4. Bootstrap Script Execution The [`bootstrap.sh`](https://github.com/alibaba/OpenSandbox/blob/main/bootstrap.sh) script (bundled inside the execd image) performs two operations: ```bash #!/bin/sh # Start execd in background /opt/opensandbox/bin/execd --jupyter-host="${JUPYTER_HOST}" --port=44772 & # Execute the user command passed as arguments exec "$@" ``` This launches the daemon on port 44772, then uses `exec` to replace the shell process with the user-defined entrypoint, ensuring PID 1 remains the user's application. ### 5. Environment Variable Injection The provider adds the `EXECD` environment variable set to `/opt/opensandbox/bin/execd`, allowing SDK-side code to address the daemon directly via the local filesystem path. ## Docker and Secure Runtime Support The injection mechanism adapts to different container runtimes while maintaining the same user experience. **Docker Runtime**: As documented in the architecture specification, the Docker provider pulls the `opensandbox/execd` image, extracts the binary to a temporary directory, and mounts it into the target container with a rewritten entrypoint (lines 99-107 in [`docs/architecture.md`](https://github.com/alibaba/OpenSandbox/blob/main/docs/architecture.md)). **Secure Runtimes**: For gVisor, Kata, and Firecracker, OSEP 0004 (lines 42-44 in [`oseps/0004-secure-container-runtime.md`](https://github.com/alibaba/OpenSandbox/blob/main/oseps/0004-secure-container-runtime.md)) mandates that the init container runs with the same `runtimeClassName` as the sandbox pod. This constraint guarantees that the binary copy and execution operations succeed within the confined environment's security boundaries, ensuring execd injection works under stricter isolation models. ## Security Design The injection implementation prioritizes container security through several mechanisms: - **No Host Privileges**: The process uses a regular sidecar init container without host-level privilege escalation - **Read-Only Binary**: The `execd` binary mounts from `emptyDir` with no additional capabilities granted - **Argument Sanitization**: The `_build_task_template` function uses `shlex.quote` to sanitize arguments passed through the bootstrap wrapper, preventing shell-injection attacks - **Runtime Isolation**: For secure runtimes, the init container shares the sandbox's runtime class, ensuring consistent isolation boundaries ## Implementation Examples ### Python SDK – Automatic Execd Injection When using the OpenSandbox Python SDK, execd injection occurs automatically during sandbox creation: ```python from opensandbox import Sandbox sandbox = await Sandbox.create( image="python:3.11", # any base image works entrypoint=["python", "-c", "print('hello')"], env={"MY_VAR": "value"}, # merged with EXECD env execd_image="opensandbox/execd:latest", # execd image reference ) print(await sandbox.execute("python -c \"print('inside')\"")) ``` The SDK transmits a `CreateSandboxRequest` to the server, which constructs the pod specification using `_build_execd_init_container` and `_build_main_container`, injects the daemon, and returns the sandbox ID. ### Generated Kubernetes Manifest The `BatchSandboxProvider` generates a manifest equivalent to this configuration: ```yaml apiVersion: sandbox.opensandbox.io/v1alpha1 kind: BatchSandbox metadata: name: demo-sandbox spec: replicas: 1 template: spec: initContainers: - name: execd-installer image: opensandbox/execd:latest command: ["/bin/sh", "-c"] args: - cp ./execd /opt/opensandbox/bin/execd && \ cp ./bootstrap.sh /opt/opensandbox/bin/bootstrap.sh && \ chmod +x /opt/opensandbox/bin/execd /opt/opensandbox/bin/bootstrap.sh volumeMounts: - name: opensandbox-bin mountPath: /opt/opensandbox/bin containers: - name: sandbox image: python:3.11 command: ["/opt/opensandbox/bin/bootstrap.sh", "python", "-c", "print('hello')"] env: - name: EXECD value: /opt/opensandbox/bin/execd - name: MY_VAR value: value volumeMounts: - name: opensandbox-bin mountPath: /opt/opensandbox/bin volumes: - name: opensandbox-bin emptyDir: {} ``` Apply this manifest directly with `kubectl` for debugging or custom deployments. ### Bootstrap Script Anatomy The bootstrap script shipped inside the execd image implements the entrypoint wrapper: ```bash #!/bin/sh # Start execd in background /opt/opensandbox/bin/execd --jupyter-host="${JUPYTER_HOST}" --port=44772 & # Execute the user command passed as arguments exec "$@" ``` This script ensures the daemon starts before user code executes while maintaining the original process hierarchy. ## Summary - **Init Container Distribution**: The `execd-installer` init container copies binaries into a shared `emptyDir` volume via `_build_execd_init_container` in [`server/src/services/k8s/batchsandbox_provider.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/batchsandbox_provider.py) - **Entrypoint Wrapping**: The main container's entrypoint is replaced with [`bootstrap.sh`](https://github.com/alibaba/OpenSandbox/blob/main/bootstrap.sh), which launches `execd` on port 44772 before executing user commands - **Runtime Agnostic**: The same injection logic works for Docker, standard Kubernetes, and secure runtimes (gVisor, Kata, Firecracker) as specified in OSEP 0004 - **Zero Image Changes**: Users can deploy any container image without modification; the platform injects the Execution Spec API ([`specs/execd-api.yaml`](https://github.com/alibaba/OpenSandbox/blob/main/specs/execd-api.yaml)) automatically - **Security Hardened**: The mechanism uses read-only volume mounts, argument sanitization with `shlex.quote`, and respects runtime-class isolation boundaries ## Frequently Asked Questions ### What is execd injection in OpenSandbox? **Execd injection** is the process by which OpenSandbox inserts a Go binary daemon called `execd` into running sandbox containers. This daemon implements the Execution Spec defined in [`specs/execd-api.yaml`](https://github.com/alibaba/OpenSandbox/blob/main/specs/execd-api.yaml), providing a standardized HTTP API for executing code and managing files inside the container, regardless of the base image used. ### How does execd injection work with secure runtimes like gVisor? For secure runtimes including gVisor, Kata, and Firecracker, OpenSandbox applies the same init container and volume mount strategy specified in OSEP 0004 (lines 42-44). The provider ensures the init container runs with the identical `runtimeClassName` as the sandbox pod, guaranteeing that the binary copy operation and subsequent execution succeed within the confined environment's security constraints. ### Do I need to modify my container image to use execd injection? No. The **zero-image-modification** design allows any container image (such as `python:3.11` or custom enterprise images) to work without changes. The platform handles all injection logic server-side through the `BatchSandboxProvider`, mounting the execd binary and bootstrap script via shared volumes and intercepting the entrypoint at runtime. ### Where is the execd binary stored inside the sandbox container? The `execd` binary is stored at `/opt/opensandbox/bin/execd` inside the container filesystem. This path is mounted from the `opensandbox-bin` `emptyDir` volume and referenced by the `EXECD` environment variable, allowing both the bootstrap script and SDK clients to locate the daemon consistently across all supported runtimes.