Routing Mechanisms of the OpenSandbox Ingress Gateway: Wildcard, URI, and Header-Based Routing

The OpenSandbox Ingress Gateway supports three distinct routing mechanisms—wildcard subdomain, URI path, and HTTP header-based routing—to expose sandbox services externally when deploying on Kubernetes with ingress.mode set to gateway.

The alibaba/OpenSandbox project provides a flexible Ingress Gateway that routes external traffic to sandboxed services based on configuration defined in IngressConfig.gateway. When deploying on Kubernetes with ingress.mode configured as gateway, operators can select between wildcard subdomain routing, URI path routing, or custom header-based routing to match their existing DNS and load balancing infrastructure. Each mechanism is implemented in the format_ingress_endpoint function within server/src/services/helpers.py and validated through IngressConfig in server/src/config.py.

Overview of Ingress Gateway Configuration

The gateway configuration resides in the IngressConfig.gateway field and requires two critical components: an address field specifying the entry point, and a route.mode field defining the routing strategy. The system recognizes three route modes defined as constants: GATEWAY_ROUTE_MODE_WILDCARD, GATEWAY_ROUTE_MODE_URI, and GATEWAY_ROUTE_MODE_HEADER.

When route.mode is set to wildcard, the address must follow the *.domain.com pattern. For uri and header modes, the address must be a valid domain, IP address, or IP:port combination without wildcard characters.

Wildcard-Based Routing

Wildcard routing generates unique subdomains for each sandbox endpoint, enabling DNS-based traffic separation without requiring additional path or header configuration.

Configuration example:

[ingress]
mode = "gateway"

[ingress.gateway]
address = "*.example.com"
route = { mode = "wildcard" }

Implementation details from server/src/services/helpers.py (lines 74-77):

if route_mode == GATEWAY_ROUTE_MODE_WILDCARD:
    base = address[2:] if address.startswith("*.") else address
    return Endpoint(endpoint=f"{sandbox_id}-{port}.{base}")

The logic strips the leading *. from the configured address and constructs the endpoint as {sandbox_id}-{port}.{base_domain}. For example, a sandbox with ID sid exposing port 8080 receives the endpoint sid-8080.example.com.

URI-Based Routing

URI routing appends sandbox identifiers to the path component of a fixed base address, suitable for scenarios where subdomain management is impractical or when operating behind path-based reverse proxies.

Configuration example:

[ingress.gateway]
address = "gateway.example.com"
route = { mode = "uri" }

Implementation from server/src/services/helpers.py (lines 78-80):

if route_mode == GATEWAY_ROUTE_MODE_URI:
    return Endpoint(endpoint=f"{address}/{sandbox_id}/{port}")

This produces endpoints in the format gateway.example.com/{sandbox_id}/{port}. Unlike wildcard routing, this approach requires no DNS wildcard records but may necessitate path-aware load balancing or URL rewriting at the proxy layer.

Header-Based Routing

Header-based routing directs traffic through a fixed gateway address while using HTTP headers to identify the target sandbox, compatible with API gateways and reverse proxies that route based on header inspection rather than URL structure.

Configuration example:

[ingress.gateway]
address = "gateway.example.com"
route = { mode = "header" }

Implementation from server/src/services/helpers.py (lines 81-86):

if route_mode == GATEWAY_ROUTE_MODE_HEADER:
    header_value = f"{sandbox_id}-{port}"
    return Endpoint(
        endpoint=address,
        headers={OPEN_SANDBOX_INGRESS_HEADER: header_value},
    )

The OPEN_SANDBOX_INGRESS_HEADER constant is defined in server/src/services/constants.py (line 22) as OpenSandbox-Ingress-To. Clients must include this header with a value formatted as {sandbox_id}-{port} to reach the correct sandbox instance.

Configuration Validation

The IngressConfig class in server/src/config.py enforces strict validation through the validate_ingress_mode method (lines 131-158). This validation ensures:

• The gateway configuration block is mandatory when ingress.mode is set to gateway.
• Wildcard addresses must match the _WILDCARD_DOMAIN_RE regex pattern (e.g., *.example.com).
• Non-wildcard addresses must not contain asterisks and must conform to valid domain, IP, or IP:port formats.

Validation failures raise ValueError exceptions during configuration loading, preventing the server from starting with inconsistent gateway settings.

Summary

• OpenSandbox Ingress Gateway routing supports three distinct mechanisms: wildcard subdomain, URI path, and HTTP header-based routing.
• Wildcard routing generates unique subdomains ({sandbox_id}-{port}.{domain}) and requires DNS wildcard records configured in the address field.
• URI routing constructs paths ({address}/{sandbox_id}/{port}) on a fixed host, suitable for path-based load balancers.
• Header-based routing uses a fixed address with the OpenSandbox-Ingress-To HTTP header to identify targets, implemented in format_ingress_endpoint within server/src/services/helpers.py.
• Configuration validation in server/src/config.py ensures address formats match the selected routing mode before server startup.

Frequently Asked Questions

What is the default routing mode for the OpenSandbox Ingress Gateway?

OpenSandbox does not provide a default routing mode; operators must explicitly set ingress.gateway.route.mode to wildcard, uri, or header. The configuration validator in server/src/config.py will reject any undefined or missing route mode when ingress.mode is set to gateway.

How does wildcard routing handle ports in the sandbox ID?

Wildcard routing automatically appends the port number to the sandbox ID using a hyphen separator. According to the implementation in server/src/services/helpers.py, the endpoint format is {sandbox_id}-{port}.{base_domain}. For example, sandbox abc123 with port 8080 becomes abc123-8080.example.com.

Can I use header-based routing with a layer 4 load balancer?

No, header-based routing requires a layer 7 (HTTP) load balancer or reverse proxy capable of inspecting HTTP headers. The OpenSandbox-Ingress-To header must be read and acted upon by the gateway or proxy to route traffic to the correct sandbox backend. Layer 4 load balancers operate at the transport level and cannot inspect HTTP headers.

Where is the routing logic implemented in the OpenSandbox source code?

The core routing logic resides in server/src/services/helpers.py within the format_ingress_endpoint function (lines 55-88). This function handles all three routing modes—wildcard, URI, and header—by inspecting the route.mode configuration and constructing the appropriate endpoint URL or headers. Configuration validation occurs in server/src/config.py in the validate_ingress_mode method.

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