Support a custom E2B-compatible endpoint for Core-managed sandboxes

[sam2tom]

Goal

Allow an operator to select an explicitly configured E2B-compatible service for Core-managed sandboxes. The existing official E2B cloud configuration remains the default. This is deployment configuration under /core/v1, not an application field under /v1 or a self-hosted executor setting.

Current boundary

At Core 3a82ccc7, the E2B deployment input contains only a write-only api_key and template. The pinned helper uses e2b==2.51.0, constructs ConnectionConfig without an endpoint/domain, and removes E2B_* from its environment. Therefore an operator cannot select a compatible service by changing current configuration or environment variables.

Core call surface to qualify

Core operation	E2B SDK/wire dependency	SandBase Sandbox at 1b314c363c
Select deployment	GET /templates/{templateID} with exact ready build UUID, CPU/memory	Route and managed-template response exist; exact SDK parse and build semantics need integration proof
Allocate/reconcile	POST /v2/sandboxes, GET /v2/sandboxes with metadata/state pagination, GET /sandboxes/{id}	Routes exist; Core sends an explicit lifecycle setting, while the gateway create allowlist omits lifecycle; the exact SDK wire and behavior must be resolved before calling this compatible
Renew/cleanup	POST /sandboxes/{id}/timeout, DELETE /sandboxes/{id}	Routes exist; Core lifecycle semantics unverified
Observe	GET /sandboxes/metrics plus running-sandbox list	Route exists; Core batch response parsing and missing-data behavior unverified
Bootstrap/inspect	SDK envd commands and files on 49983-{id}.{domain}; command output/stream, stdin, file read/write	Data-plane proxy exists and has local SDK/mock coverage; public full-chain TLS and Core bootstrap unverified

Core uses Sandbox.create(template="templateID:buildUUID"), get_info, list, set_timeout, kill, commands and files. Its create call passes lifecycle={on_timeout: kill, auto_resume: false}; the gateway's Create rejects fields outside an allowlist that currently omits lifecycle. Check the pinned SDK's emitted body, then provide equivalent accepted semantics or report a concrete incompatibility. This is the minimum Core path; gateway support for pause/resume, webhooks or ports alone does not qualify Core.

Requirements

1. Add an explicit operator-owned HTTPS control endpoint and data-plane domain to the E2B deployment configuration. Define the exact SDK 2.51.0 routing mapping and reject unsafe/malformed values. Keep the default official cloud behavior when these fields are omitted. Do not use ambient E2B_* routing overrides.
2. Propagate the selected endpoint/domain consistently through template validation, create/list/get/renew/kill, observations, SDK envd commands/files and receipt-based recovery. Persist a stable provider endpoint identity with the selection and allocations so a later configuration change cannot reinterpret old sandbox IDs against another service.
3. Keep the API key write-only/encrypted and Core-host only. Never expose it to Core Web's browser, /v1 responses, Runtime logs or error bodies. Keep the three API credential namespaces separate. Validate HTTPS, trusted host/domain relationship, redirects and data-plane targets before sending credentials or connecting.
4. Expose and document this option only through the existing /core/v1/sandbox/deployment administrator contract, Core client and operator setup flows. Specify whether endpoint changes require maintenance, current generation and cleanup of old allocations; preserve existing guarded provider-switch and uncertain-write behavior.
5. Qualify SandBase Sandbox with a local E2B 2.51.0 end-to-end Core integration: exact ready build lookup, selection, allocation, daemon bootstrap, command/file I/O, observation, timeout renewal, cleanup and interrupted-create reconciliation. Verify the expected templateID:buildUUID mapping, metadata/state pagination, error envelopes and TLS hostname behavior. A live public-service acceptance is separate and must report its exact deployment/revision and credential/network path; do not infer it from routes or mocks.
6. Update the relevant /core/v1 schema, generated contracts, API index, configuration/installer/operator docs and tests. Run make openapi after handler annotation changes and make check before completion.

Evidence and current limitation

• Core source: services/agents-api/internal/api/sandbox_deployment_setup.go, services/agents-api/tools/e2b-provider/{main.py,provider.py,sdk.py}, requirements.in.
• Gateway source: sandbase-sandbox/internal/controller/router.go, sandbase-sandbox/internal/service/sandbox/{lifecycle.go,template_catalog.go}, and the data-plane controller.
• Gateway's 2026-09-28 closeout records public control-plane checks but says full public SDK, template and Codex acceptance remain open; it also records an incomplete wildcard certificate chain. Do not mark SandBase compatible until those gates and the Core-specific path pass.

Acceptance of this issue is Core's configurable, secure endpoint plus demonstrated Core-managed lifecycle on a compatible service. It does not require changing the pinned public Agents API or making SandBase-specific behavior the default.