docs: add E2B API and Templates architecture design proposals by MahaoAlex · Pull Request #260 · volcano-sh/agentcube

MahaoAlex · 2026-04-08T03:45:30Z

What type of PR is this?

What this PR does / why we need it:

This commit adds architecture design proposal for E2B API compatibility:

docs/design/e2b-api-architecture.md - E2B API Phase 1 architecture design

This document describes the architecture and design decisions for implementing E2B-compatible REST API and Templates management in AgentCube.

Which issue(s) this PR fixes:
Fixes #257

Special notes for your reviewer:

@hzxuzhonghu @kevin-wangzefeng @YaoZengzeng

Does this PR introduce a user-facing change?:

Add E2B API compatibility layer to AgentCube Router, making it compatible with E2B's REST API and SDKs.

volcano-sh-bot · 2026-04-08T03:45:38Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hzxuzhonghu for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

docs/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

gemini-code-assist

Code Review

This pull request introduces a comprehensive architecture design for an E2B API compatible layer within AgentCube, covering sandbox lifecycle management, authentication, and data mapping. The review feedback identifies several areas for improvement, including a typo in the document title, a broken link to the Templates API design, and inconsistent JSON tagging for internet access settings. Additionally, there are concerns regarding the performance of the API key validation logic and the use of an incorrect method for updating sandbox timeouts in the provided code examples.

Copilot

Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.

codecov-commenter · 2026-04-08T03:51:32Z

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 47.57%. Comparing base (57f6d84) to head (933dca3).
⚠️ Report is 70 commits behind head on main.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #260      +/-   ##
==========================================
+ Coverage   43.37%   47.57%   +4.19%     
==========================================
  Files          30       30              
  Lines        2610     2819     +209     
==========================================
+ Hits         1132     1341     +209     
+ Misses       1355     1338      -17     
- Partials      123      140      +17

Flag	Coverage Δ
unittests	`47.57% <ø> (+4.19%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

MahaoAlex · 2026-04-08T06:42:10Z

@hzxuzhonghu @YaoZengzeng @kevin-wangzefeng Please take a look, thanks!

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 9 comments.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

YaoZengzeng · 2026-04-15T02:23:01Z

+
+| E2B Concept    | AgentCube Concept                  | Notes                                                 |
+| -------------- | ---------------------------------- | ----------------------------------------------------- |
+| **Template**   | CodeInterpreter / AgentRuntime CRD | E2B template_id maps to AgentCube CRD name            |


When is a template mapped to a CodeInterpreter and when is a template mapped to a AgentRuntime?

YaoZengzeng · 2026-04-15T02:29:56Z

+
+**Template ID Format for Namespace Isolation:**
+
+The `template_id` field supports namespace scoping using the format `{namespace}/{name}`:


This naming hierarchy differs from the original E2B protocol and will need to be emphasized in future documentation.

YaoZengzeng · 2026-04-15T02:40:26Z

+  # Keys must be valid DNS subdomain names (matching [-._a-zA-Z0-9]+).
+  # Here we use sha256(api_key) in hex as the key (safe format).
+  # key: hex(sha256(api_key)) → value: base64(namespace:client_id)
+  "a1b2c3d4e5f6789...": "ZGVmYXVsdDpjbGllbnQx" # hash(api_key_123) → default:client1


For example, if a user has the api key map to "default:client1", then this user could do all the things to the sandboxes and templates in default ns?

Do we need to restrict client's permissions? Such as client1 only have read permissions and client2 have read and write permission to the sandbox and template resources. Also client1 could read and write resources created by client2?

acsoto · 2026-04-15T09:18:30Z

+
+#### 5.2.3 Mapping to AgentCube CRDs
+
+**E2B Template → CodeInterpreter/AgentRuntime CRD:**


seem to be only CodeInterpreterKind

hzxuzhonghu

I donot see which api is handling run a command request

hzxuzhonghu · 2026-04-16T07:48:46Z

+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           AgentCube Router                                  │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                    E2B Compatible API Layer                          │   │


I would suggest we separate this entry point by port from our default api listener

hzxuzhonghu · 2026-04-16T07:49:08Z

+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │   │
+│  │  │   Handlers  │  │   Models    │  │    Auth     │  │ Middleware │ │   │
+│  │  │             │  │             │  │             │  │            │ │   │
+│  │  │ • POST /sand│  │ • Sandbox   │  │ • API Key   │  │ • Logging  │ │   │


/sand not complete

hzxuzhonghu · 2026-04-16T07:50:59Z

+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              Kubernetes                                     │
+│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐                   │
+│  │   CodeInter-  │  │  AgentRuntime │  │  agent-sandbox│                   │
+│  │   preter CRD  │  │     CRD       │  │   (microVM)   │                   │
+│  └───────────────┘  └───────────────┘  └───────┬───────┘                   │
+└─────────────────────────────────────────────────┼───────────────────────────┘
+                                                  │
+                                                  ▼
+                                        ┌───────────────────┐
+                                        │      PicoD        │
+                                        │   (sandbox runtime)│
+                                        └───────────────────┘


This is confusing and noisy

hzxuzhonghu · 2026-04-16T07:52:46Z

+                                        └───────────────────┘
+```
+
+### 2.2 Request Flow


can you also document the template creation procedure

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 14 comments.

+|               | `DELETE /sandboxes/{id}`       | Kill sandbox                              |
+|               | `POST /sandboxes/{id}/refresh` | Refresh sandbox TTL (mapped to refreshes) |
+|               | `POST /sandboxes/{id}/timeout` | Set sandbox timeout                       |
+| **Templates** | `POST /v3/templates`           | Crate Template API.                       |


+| **e2b_server.go** | E2B listener (`:8081`) setup, Platform API path routes, `engine.NoRoute` dispatch to `proxy.go` for Sandbox API. Receives shared `SessionManager`, `Store` and JWT manager via constructor injection from parent `pkg/router/`. |
+| **handlers.go**   | Platform API HTTP handlers (`/sandboxes`, `/templates`). Translates E2B requests via `mapper.go` + `resolver.go`, then delegates to the shared `SessionManager` (from `pkg/router/`) which performs the actual sandbox lifecycle operations. |
+| **proxy.go**      | Sandbox API proxy: Host parsing (`parseE2BHost`), Store lookup by `e2bSandboxID`, JWT signing. **Reuses `forwardToSandbox` / `configureProxyDirector` from `pkg/router/handlers.go`** for `req.Host` rewrite, `X-Forwarded-Host` propagation, and `Authorization: Bearer <JWT>` injection (see §2.3.3). |
+| **models.go**     | E2B wire-format structs (snake_case JSON)                                          |


+    AutoPause           bool                   `json:"autoPause,omitempty"`
+    AllowInternetAccess bool                   `json:"allow_internet_access,omitempty"`
+    Secure              bool                   `json:"secure,omitempty"`


+// pkg/router/e2b_proxy.go
+
+func (s *Server) handleE2BSandboxProxy(c *gin.Context) {
+    port, e2bSandboxID, err := parseE2BHost(c.Request.Host)


+
+| Scenario                                      | Behavior                       |
+| --------------------------------------------- | ------------------------------ |
+| Missing port (e.g., `abc123.sb.e2b.app`)      | Default port `80`              |


+        envd.POST("/filesystem/move", s.EnvdMoveHandler)
+        envd.DELETE("/filesystem/remove", s.EnvdRemoveHandler)
+        envd.GET("/filesystem/stat", s.EnvdStatHandler)
+        envd.POST("/filesystem/compose", s.EnvdComposeHandler)


+| **handlers.go**   | Platform API HTTP handlers (`/sandboxes`, `/templates`). Translates E2B requests via `mapper.go` + `resolver.go`, then delegates to the shared `SessionManager` (from `pkg/router/`) which performs the actual sandbox lifecycle operations. |
+| **proxy.go**      | Sandbox API proxy: Host parsing (`parseE2BHost`), Store lookup by `e2bSandboxID`, JWT signing. **Reuses `forwardToSandbox` / `configureProxyDirector` from `pkg/router/handlers.go`** for `req.Host` rewrite, `X-Forwarded-Host` propagation, and `Authorization: Bearer <JWT>` injection (see §2.3.3). |
+| **models.go**     | E2B wire-format structs (snake_case JSON)                                          |
+| **auth.go**       | API Key validation backed by a `SharedInformerFactory` watching the `e2b-api-keys` Secret and `e2b-api-key-config` ConfigMap (). The informer is bootstrapped once in `e2b_server.go` and shared with all handlers. |


+        envd.POST("/process/input", s.EnvdProcessInputHandler)
+        envd.POST("/process/close-stdin", s.EnvdProcessCloseStdinHandler)
+        envd.POST("/process/signal", s.EnvdProcessSignalHandler)
+        envd.POST("/process/update", s.EnvdProcessUpdateHandler)


+
+        // Environment
+        envd.GET("/env", s.EnvdEnvHandler)
+        envd.GET("/stats", s.EnvdStatsHandler)


+| Category      | API Endpoint                   | Description                               |
+| ------------- | ------------------------------ | ----------------------------------------- |
+| **Sandboxes** | `POST /sandboxes`              | Create sandbox                            |
+|               | `GET /sandboxes`               | List running sandboxes                    |
+|               | `GET /sandboxes/{id}`          | Get sandbox details                       |
+|               | `GET /v2/sandboxes`            | List running sandboxes (v2)               |
+|               | `DELETE /sandboxes/{id}`       | Kill sandbox                              |
+|               | `POST /sandboxes/{id}/refresh` | Refresh sandbox TTL (mapped to refreshes) |
+|               | `POST /sandboxes/{id}/timeout` | Set sandbox timeout                       |
+| **Templates** | `POST /v3/templates`           | Crate Template API.                       |
+|               | `GET /templates`               | List current Templates                    |
+|               | `GET /templates/{id}`          | Get template details.                     |
+|               | `DELETE /templates/{id}`       | Delete specified template.                |
+|               | `PATCH /v2/templates/{id}`     | Update template.                          |


This commit adds architecture design proposal for E2B API compatibility: - docs/design/e2b-api-architecture.md - E2B API Phase 1 architecture design This document describes the architecture and design decisions for implementing E2B-compatible REST API and Templates management in AgentCube. Signed-off-by: MahaoAlex <alexmahao319@gmail.com>

hzxuzhonghu

maybe we can have a discussion to further move it forward

Not sure how all these apis can be compatable, need to mark unsupported if not. https://github.com/MahaoAlex/agentcube/blob/933dca382d8f89de32ee9c5682ac86dd97e669e6/docs/design/e2b-api-architecture.md#sandbox-api--envd-api-support-status-picod-layer

hzxuzhonghu · 2026-05-06T09:41:40Z

+
+| Listener   | Port    | Traffic                                                                      | Exposure                      |
+| ---------- | ------- | ---------------------------------------------------------------------------- | ----------------------------- |
+| **Native** | `:8080` | AgentCube Native API (`/v1/namespaces/...`, `/health`)                       | Internal (ClusterIP)          |


Internal (ClusterIP)

I think this is not an enforcement

Copilot AI review requested due to automatic review settings April 8, 2026 03:45

volcano-sh-bot requested review from acsoto and hzxuzhonghu April 8, 2026 03:45

volcano-sh-bot added the size/XXL label Apr 8, 2026

Copilot started reviewing on behalf of MahaoAlex April 8, 2026 03:45 View session

gemini-code-assist Bot reviewed Apr 8, 2026

View reviewed changes

Comment thread docs/design/e2b-api-architecture.md Outdated

Comment thread docs/design/e2b-api-architecture.md Outdated

Comment thread docs/design/e2b-api-architecture.md

Comment thread docs/design/e2b-api-architecture.md Outdated

Comment thread docs/design/e2b-api-architecture.md Outdated

Copilot AI reviewed Apr 8, 2026

View reviewed changes

MahaoAlex force-pushed the feature/e2b-api-rel branch from 518c341 to bce97ed Compare April 8, 2026 06:15

hzxuzhonghu requested a review from Copilot April 8, 2026 09:09

Copilot started reviewing on behalf of hzxuzhonghu April 8, 2026 09:09 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

MahaoAlex force-pushed the feature/e2b-api-rel branch from bce97ed to d0950b1 Compare April 9, 2026 12:58

MahaoAlex requested a review from Copilot April 9, 2026 13:48

Copilot started reviewing on behalf of MahaoAlex April 9, 2026 13:48 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

Comment thread docs/design/e2b-api-architecture.md Outdated

MahaoAlex force-pushed the feature/e2b-api-rel branch from d0950b1 to 17f530e Compare April 9, 2026 14:04

hzxuzhonghu assigned YaoZengzeng Apr 14, 2026

MahaoAlex mentioned this pull request Apr 14, 2026

feat: add E2B API compatibility layer and Templates API support #275

Open

YaoZengzeng reviewed Apr 15, 2026

View reviewed changes

acsoto reviewed Apr 15, 2026

View reviewed changes

hzxuzhonghu reviewed Apr 16, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings May 3, 2026 12:18

MahaoAlex force-pushed the feature/e2b-api-rel branch from 17f530e to e511b72 Compare May 3, 2026 12:18

Copilot started reviewing on behalf of MahaoAlex May 3, 2026 12:19 View session

Copilot AI reviewed May 3, 2026

View reviewed changes

MahaoAlex force-pushed the feature/e2b-api-rel branch from e511b72 to 933dca3 Compare May 6, 2026 02:32

hzxuzhonghu reviewed May 6, 2026

View reviewed changes


		Template ID Format for Namespace Isolation:

		The `template_id` field supports namespace scoping using the format `{namespace}/{name}`:


		#### 5.2.3 Mapping to AgentCube CRDs

		E2B Template → CodeInterpreter/AgentRuntime CRD:

Conversation

MahaoAlex commented Apr 8, 2026

Uh oh!

volcano-sh-bot commented Apr 8, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

MahaoAlex commented Apr 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hzxuzhonghu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

hzxuzhonghu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

codecov-commenter commented Apr 8, 2026 •

edited

Loading