How OpenSandbox Implements Execd Injection in Sandbox Containers

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.

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 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), 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:

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. 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 script (bundled inside the execd image) performs two operations:

#!/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).

Secure Runtimes: For gVisor, Kata, and Firecracker, OSEP 0004 (lines 42-44 in 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:

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:

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:

#!/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
• Entrypoint Wrapping: The main container's entrypoint is replaced with 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) 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}