opensandbox-group--opensandbox/docs/reference/execd-path-migration.md

title, description

title	description
Execd Path Migration	Migration guide for the execd install path change from /opt/opensandbox/bin/ to /opt/opensandbox/.

Execd Path Migration Guide

PR: #1014

Background

OpenSandbox previously installed execd and bootstrap.sh to /opt/opensandbox/bin/, creating unnecessary nesting. The execd image already places these artifacts at the root:

/execd
/bootstrap.sh

While bootstrap.sh defaults to EXECD=/opt/opensandbox/execd (no bin/), the Kubernetes provider and Pool CR templates historically injected files into a bin/ subdirectory. This PR flattens the layout:

Before	After
/opt/opensandbox/bin/execd	/opt/opensandbox/execd
/opt/opensandbox/bin/bootstrap.sh	/opt/opensandbox/bootstrap.sh
/opt/opensandbox/bin/task-executor	/opt/opensandbox/task-executor

Additionally, the Docker runtime now uses the full bootstrap.sh from the execd image instead of a minimal 15-line inline-generated shim. This gives Docker sandboxes the same capabilities as Kubernetes: MITM CA trust setup, SIGTERM forwarding, pre-script sourcing, and chained commands.

Who is affected

User profile	Impact
code-interpreter image <=v1.0.2	Must upgrade to v1.1.0 — emptyDir at /opt/opensandbox shadows old scripts under /opt/opensandbox/
Pool CR with custom templates	Must update execd init container paths and volume mount
Custom execd images	Must now include /bootstrap.sh alongside /execd
Docker runtime users (default)	No manual action — bootstrap.sh is auto-installed

Migration steps

1. code-interpreter image

Must upgrade the image from v1.0.2 to v1.1.0.

In code-interpreter v1.0.2, the entrypoint scripts (code-interpreter.sh, code-interpreter-env.sh) live directly under /opt/opensandbox/. Before this PR, the emptyDir volume was mounted at /opt/opensandbox/bin/, shadowing only that subdirectory. Now the emptyDir mounts at /opt/opensandbox/, shadowing the entire directory — including those scripts. The pod starts but cannot find its own entrypoint.

PR #1012 moved all code-interpreter scripts from /opt/opensandbox/ to /opt/code-interpreter/, avoiding the conflict. Version v1.1.0 is the first image with that change.

# In your Pool CR or sandbox creation request:
image: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.1.0

The Python SDK (opensandbox-code-interpreter) does not require an upgrade — it communicates with execd over the network and does not reference filesystem paths.

2. Pool CR template

If you maintain a custom Pool CR that defines the execd init container, update it:

# Before
initContainers:
  - name: execd-installer
    image: opensandbox/execd:latest
    args:
      - |
        cp ./execd /opt/opensandbox/bin/execd &&
        cp ./bootstrap.sh /opt/opensandbox/bin/bootstrap.sh &&
        chmod +x /opt/opensandbox/bin/execd &&
        chmod +x /opt/opensandbox/bin/bootstrap.sh
    volumeMounts:
      - name: opensandbox-bin
        mountPath: /opt/opensandbox/bin

# After
initContainers:
  - name: execd-installer
    image: opensandbox/execd:latest
    args:
      - |
        cp ./execd /opt/opensandbox/execd &&
        cp ./bootstrap.sh /opt/opensandbox/bootstrap.sh &&
        chmod +x /opt/opensandbox/execd &&
        chmod +x /opt/opensandbox/bootstrap.sh
    volumeMounts:
      - name: opensandbox-bin
        mountPath: /opt/opensandbox

The same update applies to the task-executor init container if used:

# Before
cp /workspace/server /opt/opensandbox/bin/task-executor && chmod +x /opt/opensandbox/bin/task-executor
# After
cp /workspace/server /opt/opensandbox/task-executor && chmod +x /opt/opensandbox/task-executor

And the main container's env vars and volume mount:

# Before
- name: EXECD
  value: /opt/opensandbox/bin/execd
volumeMounts:
  - name: opensandbox-bin
    mountPath: /opt/opensandbox/bin

# After
- name: EXECD
  value: /opt/opensandbox/execd
volumeMounts:
  - name: opensandbox-bin
    mountPath: /opt/opensandbox

3. Custom execd images (Docker)

If you override [runtime].execd_image with a custom image, that image must now contain /bootstrap.sh in addition to /execd. Previously only /execd was required because the Docker runtime generated a minimal inline bootstrap script.

If your custom execd image is built from a Dockerfile that only copies the execd binary, add bootstrap.sh:

COPY bootstrap.sh /bootstrap.sh

The official opensandbox/execd image already includes both files and requires no change.

4. Custom entrypoint scripts

If you hardcode /opt/opensandbox/bin/execd or /opt/opensandbox/bin/bootstrap.sh in entrypoint scripts or build pipelines, update those references to /opt/opensandbox/.

Compatibility

Old paths are not available

After this change, the paths /opt/opensandbox/bin/execd and /opt/opensandbox/bin/bootstrap.sh no longer exist. Any script, tool, or template referencing them will fail with "file not found".

How failures manifest

Scenario	Failure mode
Old code-interpreter image (<=v1.0.2)	emptyDir at /opt/opensandbox shadows code-interpreter.sh; pod starts but entrypoint not found
Old Pool CR template	execd init container succeeds (it copies to its own mount), but main container cannot find /opt/opensandbox/bin/bootstrap.sh
Old custom execd image (no bootstrap.sh)	Docker sandbox creation fails with "bootstrap.sh not found in execd image cache"

Verification

After migration, confirm the sandbox starts successfully:

# In a running sandbox:
ls /opt/opensandbox/execd /opt/opensandbox/bootstrap.sh
# Both should exist. Verify /opt/opensandbox/bin/ does NOT exist:
test -d /opt/opensandbox/bin && echo "STALE PATH EXISTS" || echo "OK"

Release notes

For release note authors: include a summary that links to this document.

### Breaking: execd install path flattened

execd and bootstrap.sh are now installed to `/opt/opensandbox/` instead of
`/opt/opensandbox/bin/`. code-interpreter image users must upgrade to `>=v1.1.0`.
Custom Pool CR templates and custom execd images require updates.

See [execd Path Migration Guide](/reference/execd-path-migration) for full details.