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

> Expose web services running in OpenSandbox sandboxes with the Endpoint API. Map internal sandbox ports to public addresses for seamless access to containerized applications. Discover how now.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/api/schema.py) (lines 30-35).

### Docker Container Resolution

The Docker provider in [`server/src/services/docker.py`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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:

```python
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:

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

```

Response:

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

```

To enable server-side proxying:

```bash
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`](https://github.com/alibaba/OpenSandbox/blob/main/sdks/sandbox/javascript/src/services/sandboxes.ts) (lines 60-90) provides the `getSandboxEndpoint` method:

```javascript
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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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.