OpenSandbox as an Agent Sandbox provider — research, API mapping, config keys, test plan

Status: Research (read-mostly, input to the implementation phase) · Provider id: opensandbox · Plugin kind: exec (EPP/1) · Canonical plugin: awesome-providers/opensandbox (dependency-free Node provider.mjs). This repository keeps the host and the local-server harness (e2e/opensandbox/); it does not ship the plugin source. · Companion docs: providers-and-credentials.md (normative provider/EPP design), cli/docs/design/providers-and-credentials-cli.md

Chinese status page: zh. Section 9 records what was implemented and live-tested; sections 1 to 8 are the research that preceded it.

Evidence convention. Every behavioural claim below is tagged [spec] (read in an OpenAPI file), [code] (read in server/execd source) or [live] (observed against a real OpenSandbox server started locally; commands in §5). Anything tagged only [spec] or [code] and not [live] has not been exercised and the contract tests (§5.5) must pin it.

0. TL;DR

• OpenSandbox is a real, Apache-2.0, Alibaba-originated open-source sandbox platform (repo moved to opensandbox-group/OpenSandbox; alibaba/OpenSandbox 301-redirects to it). Two HTTP surfaces: a lifecycle server (FastAPI, API key header OPEN-SANDBOX-API-KEY, /v1/sandboxes…) and a per-sandbox execd daemon (Go/Gin, commands + files + code + PTY, optional X-EXECD-ACCESS-TOKEN), reached through an endpoint the lifecycle server resolves (GET /v1/sandboxes/{id}/endpoints/{port}).
• It is image-based, not template-based: template ⇒ container image URI. There is no template build/registry on the Docker runtime (/templates is the fsb microVM catalog and returns 501 on Docker).
• It can be run for real on a plain Linux dev box / CI runner, with no secrets and no Kubernetes: Docker (docker.io from apt) + pip install opensandbox-server==1.1.1. e2e/opensandbox/local-up.sh up does it in ~5 s once images are pulled; e2e/opensandbox/live_smoke.py then passes 35/35 checks (lifecycle, SSE exec, background commands, files, TTL renew, pause/resume, kill). Egress network policy also works live. There is no Docker-less runtime in the server (only docker and kubernetes), but the real execd binary runs stand-alone as a plain process, which gives a Docker-free "real data-plane" test tier (§5.3).
• Mapping: lifecycle, exec (sync + streaming), files, ports/URL, PTY, pause/resume are native; TTL change, remove, search/depth, user switching, stdin, process list/signal, capability probing are emulated; file watch, signed transfer URLs, templates (build/read), disk sizing, per-process stdin are unsupported (typed errors). Stateful code contexts are native only on images that ship the code-interpreter runtime (otherwise execd answers 500 for /code and hangs on /code/context).
• Recommended implementation: a single-file stdlib-only Python exec plugin that calls the REST APIs directly; do not wrap the official SDKs (pydantic-core native wheel, 15 MB/18 packages in Python; 8 MB/897 files in JS — both violate "installer never runs pip/npm; plugin ≤ 2000 files/50 MiB; no native code"). Reuse the SDKs/specs as references and as test oracles only.
• Four gaps in the EPP/1 draft found while mapping (§6): string process ids, a detached flag for exec.start, missing code.* methods, no per-sandbox capability probe.

1. What OpenSandbox is

1.1 Identity, licence, versions studied

Version skew that matters. The default runtime.execd_image shipped in the 1.1.1 server package is opensandbox/execd:v1.1.0 (built 2026-08-28), but the spec at 1.1.1 documents two execd behaviours that image does not have [live]: (a) argv in POST /command (v1.1.0 answers 400 … Field validation for 'Command' failed on the 'required' tag), (b) line-ending preservation in command output (v1.1.0 emits one stdout event per line with \n/\r stripped; newer builds keep them, commits 163af0a3, 380322ba). opensandbox/execd:latest (built 2026-10-11, includes both) is what opensandbox-local-up.sh configures. The plugin must handle both (§2.2 exec rows).

1.2 Architecture

 client (SDK / osb CLI / our plugin)
   │  ① lifecycle  HTTP  OPEN-SANDBOX-API-KEY            ② data plane  HTTP/SSE/WS  [X-EXECD-ACCESS-TOKEN]
   ▼                                                      ▲   address = GET /v1/sandboxes/{id}/endpoints/44772
┌──────────────────────────────┐   docker / k8s API       │   (docker bridge: "<host>:<hostport>/proxy/44772")
│ Lifecycle server (FastAPI)   │ ───────────────┐         │
│  server/opensandbox_server   │                ▼         │
│  auth middleware, validators │      ┌───────────────────┴──────────────── sandbox (container / pod / microVM) ──┐
│  sqlite|pg|redis metadata    │      │ user entrypoint (e.g. tail -f /dev/null, jupyter wrapper)                   │
│  runtimes: docker | k8s(+fsb)│      │ execd :44772  Go/Gin daemon, injected by bootstrap.sh; /command /files /code │
└──────────────────────────────┘      │               /pty /session /metrics /proxy/<port> (reverse proxy to ports) │
                                      │ [egress sidecar :18080  DNS / nft allow-deny policy, only when networkPolicy]│
                                      └─────────────────────────────────────────────────────────────────────────────┘

• Control plane server/opensandbox_server (FastAPI; routes api/lifecycle.py, api/proxy.py, api/network_policy.py, api/templates.py, api/devops.py; services services/docker/*, services/k8s/*, services/fast_sandbox/*). Runtimes: docker (single host) and kubernetes (BatchSandbox or kubernetes-sigs agent-sandbox workload providers, plus the fsb/fast-sandbox microVM template backend). services/factory.py registers only these two — there is no in-process/local runtime.
• Data plane components/execd (Go ≥1.25, Gin; pkg/web/router.go). Injected into the user container by bootstrap.sh (execd image is mounted/copied, started on port 44772). In Docker bridge mode execd also acts as the port gateway: pkg/web/proxy.go reverse-proxies /proxy/<port>/… (HTTP, SSE, WebSocket) to 127.0.0.1:<port> inside the sandbox, so GET …/endpoints/<any-port> returns <host>:<execd-hostport>/proxy/<port> (server/…/services/docker/networking.py:335) [code][live].
• Other components: components/egress (per-sandbox sidecar for networkPolicy), components/ingress (gateway for k8s), components/nodeagent, kubernetes/ (operator), server ↔ execd contract in specs/.
• Official docs on third-party implementations: docs/api/implementation-compatibility.md (the contracts are the interface; "pin the spec revision and SDK version you target").

1.3 Lifecycle API — specs/sandbox-lifecycle.yml (base http://host:8080/v1; routes also served without /v1)

Auth [spec][code][live]: header OPEN-SANDBOX-API-KEY: <key> on everything except /health, /version, /docs, /redoc, /openapi.json and …/proxy/… routes (middleware/auth.py:37-120). Missing → 401 {"code":"MISSING_API_KEY"…}, wrong → 401 {"code":"INVALID_API_KEY"…}. If the server has no api_key configured auth is skipped (startup then demands OPENSANDBOX_INSECURE_SERVER=YES or a TTY confirmation, configuration.md). SDK env names: OPEN_SANDBOX_API_KEY, OPEN_SANDBOX_DOMAIN (host[:port], default localhost:8080), OPEN_SANDBOX_PROTOCOL, OPEN_SANDBOX_USE_SERVER_PROXY, OPEN_SANDBOX_REQUEST_TIMEOUT (sdks/sandbox/python/src/opensandbox/config/connection.py:140-142, cli/src/opensandbox_cli/config.py:105-120).

Endpoints (every response carries X-Request-ID):

CreateSandboxRequest [spec lines ~1710-1930, live-verified fields marked ✓]:

States [spec]: Pending → Running ⇄ (Pausing → Paused → Resuming) → Stopping → Terminated, any → Failed; "clients must handle unknown values". On Docker only Running, Paused, Pending, Terminated, Failed are produced (services/docker/docker_service.py:529-557).

Errors: ErrorResponse{code,message} with namespaced codes (DOCKER::SANDBOX_NOT_FOUND, SANDBOX::INVALID_METADATA_LABEL, DOCKER::SANDBOX_IMAGE_PULL_FAILED, FSB::API_NOT_SUPPORTED, KUBERNETES::QUOTA_EXCEEDED, …) except FastAPI request-validation errors, which are 422 {"detail":[{type,loc,msg,input}]} [live]. The plugin's error mapper must accept both shapes (and execd's third shape {"error": "..."} for token failures, below).

1.4 execd API — specs/execd-api.yaml, router components/execd/pkg/web/router.go:49-149

Auth [spec][live]: header X-EXECD-ACCESS-TOKEN when execd is started with -access-token (or in k8s secure-access); wrong/missing → 401 {"error":"Unauthorized: invalid or missing header X-EXECD-ACCESS-TOKEN"}. On the Docker runtime the default is no token and Endpoint.headers is empty [live]; in gateway/secure-access modes Endpoint.headers carries the headers every data-plane request must send (including routing headers such as OpenSandbox-Ingress-To) — the plugin must replay Endpoint.headers verbatim on every execd request.

Streaming format [live; also sdks/sandbox/python/src/opensandbox/adapters/sse.py "legacy bare-JSON frames"]: Content-Type: text/event-stream, but frames are bare JSON objects separated by a blank line, with no data: prefix. A robust reader accepts both JSON\n\n and standard data: JSON\n\n. Event object ServerStreamEvent{type, text?, timestamp, execution_count?, execution_time?, results?{mime→value}, error?{ename,evalue,traceback[]}}, type ∈ init|status|error|stdout|stderr|result|execution_complete|execution_count|ping:

POST /command {"command":"echo out; echo err >&2; exit 3"}
{"type":"init","text":"<commandId>"}   ← first event: the command id
{"type":"ping","text":"pong"}
{"type":"stdout","text":"out\n"}  {"type":"stderr","text":"err\n"}
{"type":"error","error":{"ename":"CommandExecError","evalue":"3","traceback":["exit status 3"]}}   ← non-zero exit; no execution_complete follows
… success path ends with {"type":"execution_complete","execution_time":<ms>}
timeout       → error evalue "-1", traceback ["signal: killed"]   (indistinguishable from an external SIGKILL)
start failure → error evalue = message (e.g. capability error for uid/gid switch)

Endpoints:

Code-interpreter availability [live]. On an image without the code-interpreter runtime (python:3.12-slim): GET /code/contexts → 200 [] (misleading), POST /code → 500 {"code":"RUNTIME_ERROR","message":"error running codes language runtime server not configured, please check your image runtime"}, and POST /code/context never answers (client timeout after 10 s). On opensandbox/code-interpreter:v1.1.0 with entrypoint /opt/code-interpreter/code-interpreter.sh everything works after ~25 s of Jupyter warm-up.

1.5 Official SDKs and tools (reuse candidates, §7)

sdks/sandbox/{python,javascript,go,kotlin,csharp}, sdks/code-interpreter/{python,javascript,csharp}, sdks/mcp/sandbox, cli/ (osb). The Python SDK is generated-client + adapters (adapters/{sandboxes,command,filesystem,health,egress,…}_adapter.py, api/{lifecycle,execd,egress,diagnostic} generated from the specs, adapters/sse.py for the bare-JSON SSE quirk, adapters/endpoint_cache.py). I ran it unchanged against the local server (e2e/opensandbox/sdk_smoke.py: create → commands.run → get_info → get_endpoint(8000) ✓).

2. Operation-by-operation mapping

Legend — N native (1:1 call), E emulated (client-side logic or extra calls; described), U unsupported (typed error). EPP method names are from providers-and-credentials.md §7.4; base = [lifecycle] base URL (…/v1), execd = http(s):// + Endpoint.endpoint from GET /sandboxes/{id}/endpoints/44772, with Endpoint.headers replayed on every call.

2.1 Sandbox lifecycle (sandbox.lifecycle, sandbox.timeout, sandbox.pause)

2.2 Commands and processes (exec.run, exec.stream, process.manage, pty)

2.3 Files (files.rw; files.watch, files.transfer not offered)

2.4 Ports, capabilities, templates

2.5 Cross-cutting mappings

Status (SandboxRecord.status): Pending→creating, Running→running, Pausing→paused (execs would already fail), Paused→paused, Resuming→creating, Stopping→stopping, Terminated→stopped, Failed→error, unknown→error (+ raw state in data). Inverse for the list filter: running→Running, paused→Paused,Pausing, creating→Pending,Resuming, stopping→Stopping, stopped→Terminated, error→Failed.

Errors (EPP code ← OpenSandbox):

3. Credentials and configuration keys (proposal, naming style of the provider design doc)

Provider id opensandbox (matches ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, not reserved). Canonical env = ABX_OPENSANDBOX_<KEY> (design doc §2 principle 3); native env names are the names the OpenSandbox SDKs/osb CLI already use, so users with a working OpenSandbox environment need no new variables (none start with ABX_, E2B_, ALICLOUD_, as required by the manifest rules). The plugin consumes no core credential: [core] inherit = [] — it must never receive ABX_SANDBOX_API_KEY or the Alibaba Cloud access key (§4.6 isolation).

Shared core tuning keys are honoured unchanged (http_timeout, max_retries, …). [auth] any_of is omitted (see api_key). Per-create options (--opt / provider_options) are not stored: entrypoint, network_policy (JSON object matching NetworkPolicy), platform (linux/arm64), secure_access, image_auth.

Manifest sketch (only the OpenSandbox-specific parts):

manifest_version = 1
[provider]
id = "opensandbox"
name = "OpenSandbox"
name_zh = "OpenSandbox 开源沙箱"
license = "Apache-2.0"
homepage = "https://github.com/opensandbox-group/OpenSandbox"
[compat]
protocol = "epp/1"
[runtime]
kind = "exec"
command = ["python3", "provider.py"]
[features]
supported = ["sandbox.lifecycle", "sandbox.timeout", "sandbox.pause", "exec.run", "exec.stream",
             "process.manage", "files.rw", "ports.url"]   # + "pty", "code.interpret" once the EPP gaps of §6 are closed
[security]
network = ["*"]                 # user-configured server URL
filesystem = ["data_dir"]
env_passthrough = []
spawns_processes = false
[core]
inherit = []

4. What cannot be done / honest limits

1. No disk sizing on Docker (ignored by the server) ⇒ disk refused.
2. No file watch, no signed transfer URLs, no per-process stdin, no real process table (shell emulation only, so ps must exist in the image).
3. TTL minimum is 60 s; Agent Sandbox allows 1 s.
4. Metadata must satisfy Kubernetes label syntax (≤ 63-char values).
5. execd output framing and argv depend on the execd image version (§1.1); abx should document a minimum (opensandbox/execd:latest or the first release after release-1.1.1) for byte-exact output.
6. Code contexts require a code-interpreter image; probing must avoid the hanging endpoint.
7. A foreground command is killed when the connection drops, so abx … process start must use background:true (needs the detached hint, §6).

5. Test plan

5.1 Can OpenSandbox run locally? — Yes, for real (Docker runtime), no secrets

Checked on a dev VM (Ubuntu 24.04, kernel 6.12, 4 vCPU, 16 GB, rootfs = overlayfs, non-root user with passwordless sudo, outbound internet to PyPI / Docker Hub):

Exact commands that worked ($WORKDIR = the script's OSB_WORKDIR, default ~/.cache/agent-sandbox/opensandbox-local; $ORIG_REPO = the checkout of the Agent Sandbox source tree used for the surface survey; all wrapped in python-sdk/e2e/opensandbox/local-up.sh, idempotent, ≈ 5 s warm, ≈ 70 s with cold image pulls):

# Docker
sudo apt-get update && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y docker.io iptables
sudo truncate -s 20G /var/lib/docker-loop.img && sudo mkfs.ext4 -q -F /var/lib/docker-loop.img
sudo mkdir -p /mnt/dockerdata /etc/docker && sudo mount -o loop /var/lib/docker-loop.img /mnt/dockerdata
echo '{"data-root":"/mnt/dockerdata","storage-driver":"overlay2","features":{"containerd-snapshotter":false}}' | sudo tee /etc/docker/daemon.json
(sudo nohup dockerd >"$WORKDIR/dockerd.log" 2>&1 &); sleep 8; sudo chmod 666 /var/run/docker.sock
docker run --rm alpine echo ok                      # sanity
# OpenSandbox server (PyPI, normal user)
pip install --user uv && export PATH=$HOME/.local/bin:$PATH
uv venv $WORKDIR/venv --python 3.12
uv pip install --python $WORKDIR/venv/bin/python opensandbox-server==1.1.1
docker pull opensandbox/execd:latest python:3.12-slim opensandbox/egress:v1.1.7     # + opensandbox/code-interpreter:v1.1.0 for run_code
cat >$WORKDIR/server.toml <<'EOF'
[server]
host = "127.0.0.1"
port = 8080
api_key = "local-dev-key"          # not a secret: a throw-away local key
max_sandbox_timeout_seconds = 86400
[runtime]
type = "docker"
execd_image = "opensandbox/execd:latest"
[store]
type = "sqlite"
path = "$WORKDIR/opensandbox.db"
[docker]
network_mode = "bridge"
[ingress]
mode = "direct"
[egress]
image = "opensandbox/egress:v1.1.7"
mode = "dns"
EOF
(nohup $WORKDIR/venv/bin/opensandbox-server --config $WORKDIR/server.toml >$WORKDIR/server.log 2>&1 &)
curl -s localhost:8080/health   # {"status":"healthy"}   curl -s localhost:8080/version  # {"version":"1.1.1"}

Then export OPENSANDBOX_BASE_URL=http://127.0.0.1:8080/v1 OPENSANDBOX_API_KEY=local-dev-key and python3 e2e/opensandbox/live_smoke.py (stdlib only; 35 checks, all passing, ~5 s) — it doubles as the executable specification of the §2 mapping (auth, create/get/list/endpoint, SSE exec + exit codes + timeout, background + logs cursor + interrupt, mkdir/upload/stat/list/search/mv/rm/rmdir, renew, pause/resume, kill + second-kill 404). Also verified live: server-proxied endpoints, egress policy (deny default + allow pypi.org blocks example.com, allows pypi.org; PATCH …/networkpolicy merge), snapshots (202 Creating), the official Python SDK end to end, execd access-token behaviour.

opensandbox-local-up.sh knobs: up|down|status|env, OSB_SERVER_VERSION, OSB_EXECD_IMAGE, OSB_PORT, OSB_API_KEY, OSB_WORKDIR, OSB_WITH_EGRESS, OSB_WITH_CODE_INTERPRETER. down stops the server and removes all sandbox-* containers. The local server harness stays in this repository (e2e/opensandbox/). The plugin source is awesome-providers/opensandbox.

5.2 Test pyramid for the plugin

CI policy: T0–T2 are required and offline; T3 optional-but-recommended; T4 must pass before a release and on a nightly schedule against opensandbox/execd:latest to catch upstream drift (version skew in §1.1 is a live example).

5.3 Docker-free real data plane (T3) — design

Start the real execd for each fake sandbox: execd --port <p> [-access-token <t>] with cwd = a per-sandbox temp dir (HOME and TMPDIR pointed inside; commands run as the test user, so /tmp/... absolute paths used by tests are rewritten under the sandbox root or avoided). The mock lifecycle returns endpoint: "127.0.0.1:<p>"; kill terminates the process group; TTL is enforced by a timer; pause = SIGSTOP of the process group (and SIGCONT on resume) — a faithful enough analogue of docker pause. This validates everything in §2.2/§2.3 except the code interpreter, PTY-under-Docker caveats and egress.

5.4 Faithful mock server (T1) — design, in case no execd binary / Docker is available

One stdlib http.server/ThreadingHTTPServer module (tests/mock_opensandbox.py, ≈ 600 lines), two virtual hosts on two ports (lifecycle, one execd per sandbox), in-memory state:

• Fidelity source = recorded fixtures, not imagination. Responses are replayed from fixtures captured by the live smoke run (scrubbed ids/times), covering the quirks that matter: 202 create with Running, 422 {"detail":…} shape, 404 DOCKER::SANDBOX_NOT_FOUND, second-delete 404, bare-JSON SSE with init/ping, error{CommandExecError,evalue} exit signalling, -1/signal: killed, files/info map keyed by path with octal-digits mode, DELETE /files on a directory 500, /files/mv overwrite 500, upload metadata file-part requirement and 400 "metadata file is missing", merged background logs with EXECD-COMMANDS-TAIL-CURSOR, 501 FSB::API_NOT_SUPPORTED, endpoint without scheme, Endpoint.headers, GET /code/contexts → 200 [], 500 … runtime server not configured, and the hang of POST /code/context (a configurable stall to test the client timeout).
• Behaviour = a tiny real model: sandbox table with states and TTL (expiresAt, expiry ⇒ removal), virtual filesystem rooted in a temp dir, commands executed with subprocess (sh -c/argv) streaming stdout/stderr events in the exact framing (selectable new vs v1.1.0 line-stripping mode, and argv accepted/rejected by flag), background registry, renew-expiration, pause/resume, metadata label validation, pageSize ≤ 200, API-key and X-EXECD-ACCESS-TOKEN enforcement, a "gateway mode" returning Endpoint.headers that the plugin must replay (the mock rejects requests without them).
• Spec conformance guard (offline): vendor specs/sandbox-lifecycle.yml + specs/execd-api.yaml at the pinned commit (a6a0135…, Apache-2.0 headers kept) and, in dev-only test dependencies, validate every request the plugin sends and every response the mock produces against the schemas (openapi-core or jsonschema on $ref-resolved component schemas). A separate test fails if the vendored spec hash differs from the commit recorded in tests/SPEC_PIN so spec upgrades are deliberate. Known spec-vs-reality divergences found here are encoded as explicit allow-list entries with a comment: 422 detail bodies, execd 401 {"error"}, files/mv auto-creating parents, /pty absent from the spec, /command argv unavailable in v1.1.0.
• Differential rule: every T1 test body also runs in T4; a mock behaviour change must come with a live re-recording (make record-fixtures, a script that replays the smoke flow against the live server and rewrites tests/fixtures/*.json).

5.5 Contract tests worth writing first

(1) exec exit-code matrix 0/3/127/timeout/start-failure; (2) both framing modes produce identical stdout for printf 'a\r\nb\n'; (3) upload→download byte-exactness incl. \x00\xff, empty file, 3 MB; (4) remove of file/dir/missing, move-onto-existing, search depth; (5) set_timeout → expiresAt within ±2 s of server time even with a skewed client clock; (6) idempotent kill; (7) metadata label rejection message names the key; (8) capability probe never calls the hanging endpoint without a timeout; (9) Endpoint.headers replayed on every execd call incl. SSE and uploads; (10) list pagination > 200 items; (11) exec.start stream ordering: all exec.output before the single exec.exit; (12) error-shape tolerance (ErrorResponse, {"detail":[…]}, {"error":…}, non-JSON 502 HTML).

6. Gaps in the EPP/1 draft that this provider exposes (for the provider-design owner)

1. Process ids are strings. execd command ids are 32-hex strings; Agent Sandbox's ProcessInfo.pid is an int. EPP should type process_id as string | int and let process.kill/signal accept either (this doc's mapping: numeric ⇒ OS pid via kill, hex ⇒ execd command id).
2. exec.start has no detached/background hint. A foreground OpenSandbox command is killed when the connection closes, so a process that must outlive the CLI invocation (abx sandbox process start, background commands.start) needs background:true plus log polling. Proposal: optional boolean detached in exec.start params (ignored by providers whose processes are always detached).
3. No code.* methods although code.interpret is a feature id: add code.run ({sandbox_id, code, language, context_id?, envs?, timeout} → streamed code.output notifications + final {results, error?}), code.context.create/list/remove/restart. Until then the plugin must not declare code.interpret; run_code still works through the SDK's shell fallback (api/code.py).
4. Large file bodies. files.read/write are base64-in-JSON with an 8 MiB line cap; OpenSandbox supports Range and 3 MB+ bodies natively. Options: chunked files.read{offset,length} / files.write{append}, or an optional "direct data plane" descriptor on SandboxRecord ({base_url, headers}) for providers whose data plane is plain HTTP (OpenSandbox's Endpoint is exactly that) — the doc's hybrid envd_url model is envd-protocol-specific.
5. Per-sandbox capabilities. Effective capabilities are template-derived today; for image-based providers they depend on the image (code only with the interpreter). Add optional sandbox.capabilities{sandbox_id} → {tokens:[…]} (else the host falls back to static features).
6. Minor: files.search, files.chmod are absent from the EPP table (native in OpenSandbox; the CLI emulates search with find); sandbox.list metadata filter semantics (label equality, AND) should be stated; SandboxRecord.expires_at must be optional (manual-cleanup sandboxes); error data.retryable is needed for 429/502.

7. Reusable pieces: wrap the official SDKs, or call REST directly?

Decision: call REST directly, stdlib-only, in one provider.py (≈ 700–900 lines). Use the SDKs (a) as readable references for edge cases (adapters/sse.py, adapters/command_adapter.py, adapters/filesystem_adapter.py, endpoint_cache.py) and (b) as test oracles in T4 (create with the SDK, operate with the plugin and vice versa; dev-only dependency, never shipped). Interpreter choice: Python stdlib (http.client, json, threading, base64, ssl), matching the reference local-process plugin and available wherever the Python SDK runs; a Node provider.mjs (global fetch, no deps) is the alternative if CLI-only machines without Python are a target — the EPP makes the two interchangeable and a second manifest can ship both. Keep the data-plane HTTP client persistent (keep-alive) within one plugin process; the plugin is one process per CLI invocation, so cache the resolved execd endpoint and the code-interpreter probe in memory only.

7.1 Suggested plugin layout and order of work

providers/opensandbox/
  abx-provider.toml           # §3
  provider.py                 # EPP loop, method table, config, error mapping   (~250)
  _osb_http.py                # request(), retry (idempotent only), SSE reader, multipart, endpoint cache, Date-skew
  tests/{unit,contract,live}/ # T0, T1/T2, T4
  tests/mock_opensandbox.py   # T1 (+ T3 shim)
  tests/fixtures/ specs/      # recorded responses, vendored specs + SPEC_PIN
  scripts/opensandbox-local-up.sh  scripts/opensandbox_live_smoke.py

Order: (1) initialize + lifecycle + ports.url against T4; (2) exec.run/exec.start with both framing modes; (3) files.*; (4) process.*, sandbox.timeout/pause; (5) T1 mock + fixtures recorded from T4; (6) pty (WebSocket) and, after EPP gap 3, code.*; (7) install with abx provider install alibaba-agent-sandbox/awesome-providers//opensandbox (or a local directory of that plugin). The shipped plugin is the Node tree in that catalog, not the Python sketch above.

8. Appendix — evidence and artifacts

9. Status after the 2026-10-13 live review

The mapping in section 2 was implemented as the opensandbox plugin and driven against a real server (opensandbox-server 1.1.1, Docker) through abx and Sandbox.create(provider="opensandbox"). Evidence: 2026-10-13-opensandbox-provider-e2e.