fix(workspace): support e2b self-hosted gateway routing

[Posartor]

AgentScope Version

Current main branch.

Description

This PR fixes E2BWorkspace compatibility with self-hosted E2B deployments.

E2BWorkspace starts an AgentScope MCP gateway inside the E2B sandbox. The gateway listens on the workspace gateway port, which defaults to 5600, and all MCP services registered in the workspace are accessed through this gateway.

Before this change, the host-side GatewayClient always used E2B's default subdomain-based port routing:

base_url = f"https://{sandbox.get_host(gateway_port)}"

with:

X-Access-Token: <traffic_access_token>

This works for the default E2B cloud routing, but it does not work for self-hosted deployments where sandbox traffic is exposed through a shared client-proxy URL such as:

http://<host-ip>:3002
http://localhost:3002
https://sandbox.<domain>

For these deployments, the client-proxy needs the target sandbox and port to be provided through routing headers:

E2b-Sandbox-Id: <sandbox_id>
E2b-Sandbox-Port: <gateway_port>

This PR updates the E2B workspace routing logic to support that mode.

The updated behavior is:

• no sandbox_url: keep the existing default E2B cloud routing with sandbox.get_host(gateway_port) and X-Access-Token
• with sandbox_url: use the configured shared proxy URL and route the request with E2b-Sandbox-Id / E2b-Sandbox-Port

Changes include:

• Add api_url and sandbox_url parameters to E2BWorkspace
• Forward api_url and sandbox_url to E2B SDK calls
• Use sandbox_url as the host-side gateway base URL when configured
• Send E2b-Sandbox-Id and E2b-Sandbox-Port headers for self-hosted gateway routing
• Preserve the existing sandbox.get_host(port) + X-Access-Token behavior for default E2B cloud routing
• Add api_url and sandbox_url forwarding to E2BWorkspaceManager

Closes #1895

Root Cause

E2BWorkspace starts an in-sandbox MCP gateway on gateway_port, which defaults to 5600, and _wait_for_gateway() waits for it by probing:

GET {base_url}/health

Before this change, base_url was always resolved through:

base_url = f"https://{sandbox.get_host(gateway_port)}"

This assumes E2B subdomain-based port routing, where the target sandbox and port are encoded in the host name.

Self-hosted E2B deployments may expose sandbox traffic through a shared client-proxy URL instead. In that routing mode, the target sandbox and port must be sent through headers:

E2b-Sandbox-Id: <sandbox_id>
E2b-Sandbox-Port: <gateway_port>

The gateway was already started successfully inside the sandbox:

[gateway] connected 'server-everything'
[gateway] serving 1 MCPs on :5600

However, the previous host-side GatewayClient did not use the configured shared sandbox proxy URL or these routing headers, so the request was not routed to sandbox port 5600. As a result, the host-side health check timed out even though the gateway was already running inside the sandbox.

Test

Pre-commit

pre-commit run --all-files

Result: passed after normalizing line endings in src/agentscope/app/workspace_manager/_e2b_workspace_manager.py.

Compile check

python -m compileall -q src/agentscope/workspace/_e2b/_e2b_workspace.py src/agentscope/app/workspace_manager/_e2b_workspace_manager.py

Result: passed.

Self-hosted E2B validation

Verified with a self-hosted E2B deployment using separate API and sandbox proxy endpoints:

E2B_API_URL=http://<host-ip>:3000
E2B_SANDBOX_URL=http://<host-ip>:3002

Before the fix, initialization failed while waiting for the gateway health check:

RuntimeError: gateway did not become healthy within 30.0s. Tail of /home/user/.agentscope/gateway.log:
[gateway] connected 'server-everything'
[gateway] serving 1 MCPs on :5600

After the fix, the workspace initialized successfully and the MCP gateway was reachable through header-based sandbox routing.

[GatewayMCPClient(name='server-everything', is_stateful=True, mcp_config=StdioMCPConfig(type='stdio_mcp', command='npx', args=['@modelcontextprotocol/server-everything@latest'], env=None, cwd=None, encoding_error_handler='strict'), enable_tools=None, disable_tools=None, execution_timeout=None)]

Checklist

• An issue has been created for this PR
• I have read the CONTRIBUTING.md
• Docstrings are in Google style
• Related documentation has been updated, if needed
• Code is ready for review