Skip to main content

Routing

SandboxMesh creates lightweight preview environments by sharing your baseline services and intelligently routing specific requests to your isolated sandboxes.

We achieve this without requiring you to change your code, thanks to standardized HTTP headers.

The Magic of Traffic Selection​

Every Sandbox you create is assigned a unique identifier (e.g., sbx-a1b2c3d4).

SandboxMesh configures your edge or mesh routing layer (like Gateway API or Istio) to intercept any traffic carrying that specific ID and send it straight to your sandboxed workload. If a request doesn't have an ID, or the ID doesn't match an active sandbox, the request simply falls back to your normal, baseline services.

Defaulting to the baggage Header​

By default, SandboxMesh looks for this identifier inside the standard W3C baggage header.

We default to baggage because it is an open standard widely supported by OpenTelemetry and modern tracing libraries. This means that if your application already propagates tracing context, it will automatically propagate your sandbox context down the stack without any extra work.

When making a request, simply pass your ID under the sandbox key:

bash
curl -H "baggage: sandbox=sbx-a1b2c3d4" https://api.example.com/checkout

Custom Selector Headers​

While baggage is the recommended default, we know every stack is different.

If your edge gateway or internal policies require a dedicated header, SandboxMesh fully supports custom selector headers (such as x-sandbox-id). You define this at the SandboxRoute level or in your SaaS Portal settings.

Supported Routing Providers​

SandboxMesh seamlessly integrates with the routing tools you already use in your cluster. We act as the control plane, dynamically writing the routing rules for:

  • Gateway API: We render native HTTPRoute objects, perfect for modern ingress controllers.
  • Istio: We render native VirtualService objects, ideal for comprehensive service meshes.
  • Built-in Proxy: For simpler setups, we provide a built-in proxy deployment to rewrite selectors on the fly.

Next Steps​

  • Want to see routing in action? Check out the Quickstart.
  • Need to route a single request through multiple different sandboxes? Read Combining Sandboxes.
  • Learn how to keep your sandbox context alive across queues and workers in Context Propagation.