Skip to main content

Quickstart

Get your first SandboxMesh preview environment running in 5 minutes.

This guide walks you through connecting your cluster, cloning an existing workload, and routing traffic to your new, isolated sandbox.

Prerequisites​

  • A Kubernetes cluster
  • kubectl configured for your cluster
  • helm installed
  • Gateway API (or another supported routing layer) installed to intercept traffic

1. Connect your cluster​

Install the SandboxMesh runtime into your cluster. This lightweight operator manages the lifecycle of your sandboxes.

bash
helm upgrade --install sandbox-mesh-operator charts/sandbox-mesh-operator \
  --namespace sandbox-mesh-system \
  --create-namespace \
  --set agent.bootstrapToken="<YOUR_BOOTSTRAP_TOKEN>"

Generate your token from the SandboxMesh Portal to securely link your cluster to your workspace.

2. Clone a workload​

Instead of building from scratch, SandboxMesh snapshots an existing workload (like a Deployment or StatefulSet) and spins up a targeted clone.

Here is an example that snapshots a Deployment named checkout-api and creates an isolated sandbox copy:

sandboxgroup.yaml
apiVersion: sandbox.mesh.dev/v1alpha1
kind: SandboxGroup
metadata:
  name: checkout-preview
  namespace: default
spec:
  components:
    - name: api
      sourceRef:
        apiVersion: apps/v1
        kind: Deployment
        name: checkout-api
      overrides:
        replicas: 1
        containers:
          - name: app
            env:
              - name: MODE
                value: sandbox

Apply the configuration:

bash
kubectl apply -f sandboxgroup.yaml

Once running, SandboxMesh assigns a unique sandboxID to this group. This ID acts as your magic key for routing.

3. Attach traffic routing​

Now, tell SandboxMesh how to route traffic to your new sandbox. This example uses Gateway API to intercept requests heading to /checkout.

sandboxroute.yaml
apiVersion: routing.mesh.dev/v1alpha1
kind: SandboxRoute
metadata:
  name: checkout-preview-route
  namespace: default
spec:
  sandboxGroupRef:
    name: checkout-preview
  provider: gateway
  gateway:
    parentRefs:
      - name: public
        namespace: infra-gateway
    hostnames:
      - api.example.com
  rules:
    - name: checkout-api
      matches:
        - path:
            type: PathPrefix
            value: /checkout
      backends:
        - component:
            name: api
            port: 8080

Apply the route:

bash
kubectl apply -f sandboxroute.yaml

4. Test your sandbox​

By default, SandboxMesh inspects the standard W3C baggage header for your sandbox ID. Pass it along with your request to hit your preview environment while seamlessly falling back to baseline for everything else.

bash
# Get your generated sandbox ID
kubectl get sandboxgroup checkout-preview -n default -o jsonpath='{.status.sandboxID}'

# Make a request using your sandbox ID
curl \
  -H "baggage: sandbox=<sandbox-id>" \
  https://api.example.com/checkout

Next steps​

  • Explore our Architecture to see how the SaaS Portal and In-Cluster execution plane work together.
  • Need more complex routing? Learn how to Combine Sandboxes across multiple services.