alibaba / alibaba/ROCK

feat: add E2B sandbox control-plane API compatibility

Open
#1,293 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
485
Forks
81
Avg merge
16h 12m
Merged PRs (30d)
8

Description

## Background

ROCK needs a compatibility entrypoint for the E2B sandbox control-plane protocol so E2B lifecycle clients can call existing ROCK sandbox capabilities without changing the existing ROCK API contract.

## Scope

Add an isolated E2B-compatible FastAPI entrypoint for the `/sandboxes` control plane:

- `POST /sandboxes`
- `GET /sandboxes`
- `GET /v2/sandboxes`
- `GET /sandboxes/{sandboxID}`
- `DELETE /sandboxes/{sandboxID}`
- `POST /sandboxes/{sandboxID}/connect`
- `POST /sandboxes/{sandboxID}/timeout`
- `POST /sandboxes/{sandboxID}/refreshes`

Responses must use E2B field names, response bodies, error shape (`{code, message}`), and HTTP status codes rather than the ROCK `RockResponse` envelope.

## Compatibility rules

- Reuse existing ROCK `SandboxManager` and metadata/timeout capabilities.
- Register the E2B router separately and keep all existing `/apis/envs/sandbox/v1/*` paths, request/response models, and behavior unchanged.
- Treat unsupported or non-equivalent behavior as fail-closed; do not silently approximate pause, memory snapshots, fork, network policy, MCP, volumes, or envd.
- Only return E2B success statuses when the corresponding ROCK lifecycle result is confirmed.
- Preserve E2B metadata and template identity needed for get/list responses.

## Non-goals

- E2B envd process/filesystem/PTY/Connect RPC compatibility.
- Commands and file operations through the official E2B SDK.
- Template build APIs.
- Semantic emulation of pause/resume via ROCK stop/restart.

## Acceptance criteria

- Contract tests cover E2B request aliases, required response fields, status codes, authentication header handling, and `{code, message}` errors.
- Unsupported fields and operations return explicit E2B-style errors.
- Existing ROCK API route and unit tests remain unchanged and pass.
- Research and design documentation records the E2B protocol baseline and intentional compatibility limits.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by mapping the existing SandboxManager and ROCK sandbox API entry points, then compare their lifecycle and metadata behavior with the listed E2B /sandboxes routes. Add an isolated FastAPI router, contract tests for aliases, fields, statuses, authentication, and {code, message} errors, and documentation of the protocol baseline and compatibility limits. Confirm existing ROCK route and unit tests remain unchanged and pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
fastapi, python
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.