How to Expose Web Services Running Inside OpenSandbox Sandboxes Through Accessible Endpoints

The OpenSandbox Endpoint API resolves internal sandbox ports to public addresses via GET /v1/sandboxes/{sandbox_id}/endpoints/{port}, returning a reachable URL that maps to services inside Docker containers or Kubernetes Pods.

OpenSandbox from Alibaba isolates user code in lightweight sandboxes using Docker containers or Kubernetes Pods. To expose web services running inside these isolated environments through accessible endpoints, you query the Sandbox Endpoint API, which translates internal container ports into externally reachable network addresses according to provider-specific logic in the server codebase.

How the Sandbox Endpoint API Works

The endpoint resolution flow follows a three-step dispatch pattern implemented in server/src/api/lifecycle.py (lines 70-90). When you request access to a service running inside a sandbox, the server resolves the public address by inspecting runtime-specific metadata and network configurations.

API Route and Request Structure

The FastAPI route in server/src/api/lifecycle.py handles GET /v1/sandboxes/{sandbox_id}/endpoints/{port}. The route accepts an optional use_server_proxy query parameter. When invoked, it forwards the request to sandbox_service.get_endpoint(...), which abstracts the underlying container runtime and returns an Endpoint model defined in server/src/api/schema.py (lines 30-35).

Docker Container Resolution

The Docker provider in server/src/services/docker.py inspects container labels created during sandbox initialization to determine accessibility. It specifically checks for:

• sandbox.opensandbox.io/embedding-proxy-port for execd proxy configurations
• sandbox.opensandbox.io/http-port for the default HTTP port (typically 8080)

The implementation distinguishes between network modes. For sandboxes created with --network=host, it returns host:port directly. For bridge mode, it constructs a proxy-aware URL using the format host:execd_port/proxy/<port>, enabling access through the OpenSandbox proxy layer.

Kubernetes Pod Resolution

For Kubernetes sandboxes, server/src/services/k8s/kubernetes_service.py (lines 21-41) retrieves the Pod or CRD workload. It extracts the Pod IP and port mappings defined by the sandbox.opensandbox.io/endpoints annotation. The returned endpoint follows the format PodIP:<port>, providing direct network access to the service container.

Server-Side Proxy Option

Appending ?use_server_proxy=true to the API request triggers URL rewriting to /sandboxes/{id}/proxy/{port}. The server then acts as a reverse proxy, returning an endpoint like example.com/v1/sandboxes/sbx-001/proxy/8080 rather than a raw host-port combination. This is essential when sandboxes run behind firewalls or when clients cannot reach the host network directly.

Practical Code Examples

You can retrieve endpoints using the official SDKs or direct HTTP calls. Both methods interact with the get_endpoint logic implemented in server/src/services/sandbox_service.py (lines 209-219).

Python SDK Implementation

The Python SDK in sdks/sandbox/python/src/opensandbox/sync/services/sandbox.py (lines 100-130) wraps the endpoint API. Use the get_endpoint method after creating a sandbox with exposed ports:

from opensandbox import SandboxService

sandbox = SandboxService()

sb = sandbox.create(
    image="python:3.11-slim",
    env={"SANDBOX_EXPOSE_PORTS": "8080"},
)

endpoint = sandbox.get_endpoint(sandbox_id=sb.sandbox_id, port=8080)
print("Public URL:", endpoint.endpoint)

# Output: 203.0.113.42:44772/proxy/8080

Direct HTTP Requests with cURL

For direct API access without an SDK, authenticate using a Bearer token and specify the sandbox ID and internal port:

curl -H "Authorization: Bearer $TOKEN" \
     "https://sandbox.example.com/v1/sandboxes/$SBX_ID/endpoints/8080"

Response:

{
  "endpoint": "203.0.113.42:44772/proxy/8080"
}

To enable server-side proxying:

curl "https://sandbox.example.com/v1/sandboxes/$SBX_ID/endpoints/8080?use_server_proxy=true"

JavaScript SDK Usage

The JavaScript SDK in sdks/sandbox/javascript/src/services/sandboxes.ts (lines 60-90) provides the getSandboxEndpoint method:

import { SandboxService } from '@opensandbox/sandbox';

const client = new SandboxService({ token: process.env.SANDBOX_TOKEN });

async function main() {
  const sb = await client.createSandbox({ 
    image: "node:20-alpine", 
    exposePorts: [3000] 
  });
  const ep = await client.getSandboxEndpoint(sb.sandbox_id, 3000);
  console.log('Reachable at', ep.endpoint);
}
main();

Network Mode and Port Mapping Details

Port mapping occurs during sandbox creation when the sandbox controller attaches metadata to containers. For Docker, labels store the mapping between host ports and internal container ports. For Kubernetes, annotations on the Pod or CRD define the sandbox.opensandbox.io/endpoints configuration. The abstract get_endpoint method in server/src/services/sandbox_service.py enforces a consistent interface across providers, ensuring both Docker and Kubernetes implementations return standardized Endpoint objects regardless of whether the underlying network uses bridge, host, or PodIP addressing.

Summary

• Query the Endpoint API: Use GET /v1/sandboxes/{id}/endpoints/{port} to resolve internal ports to public addresses via server/src/api/lifecycle.py.
• Docker Implementation: Checks labels sandbox.opensandbox.io/http-port and sandbox.opensandbox.io/embedding-proxy-port, handling both host and bridge network modes in server/src/services/docker.py.
• Kubernetes Implementation: Returns PodIP:<port> based on the sandbox.opensandbox.io/endpoints annotation processed in server/src/services/k8s/kubernetes_service.py.
• Server Proxy Option: Add use_server_proxy=true to route traffic through the OpenSandbox server instead of direct host access.
• SDK Support: Available in Python (opensandbox.sync.services.sandbox) and JavaScript (@opensandbox/sandbox) via get_endpoint and getSandboxEndpoint methods.

Frequently Asked Questions

What is the Sandbox Endpoint API in OpenSandbox?

The Sandbox Endpoint API is a REST interface exposed by the OpenSandbox server that translates internal container ports into externally reachable network addresses. Located in server/src/api/lifecycle.py, it provides the GET /v1/sandboxes/{sandbox_id}/endpoints/{port} route that returns an Endpoint model containing the public URL for accessing services inside sandboxes.

How does OpenSandbox handle port mapping for Docker sandboxes?

According to server/src/services/docker.py, the Docker provider inspects container labels created during sandbox initialization. It reads sandbox.opensandbox.io/http-port for standard HTTP services and sandbox.opensandbox.io/embedding-proxy-port for execd proxy configurations, then returns either a direct host:port for host network mode or a proxy URL for bridge mode.

Can I use a server-side proxy instead of direct host ports?

Yes. By appending ?use_server_proxy=true to the endpoint request, the API returns a URL formatted as /sandboxes/{id}/proxy/{port} rather than a raw host-port combination. The OpenSandbox server then acts as a reverse proxy, which is useful when sandboxes run behind firewalls or when clients cannot reach the host network directly.

What endpoint format does Kubernetes use in OpenSandbox?

The Kubernetes implementation in server/src/services/k8s/kubernetes_service.py returns endpoints in the format PodIP:<port>, derived from the Pod's internal IP address and the port mapping defined by the sandbox.opensandbox.io/endpoints annotation. This provides direct layer-3 access to services running inside Kubernetes Pods.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}