Sandbox drivers

Choose where agent sessions run (gVisor, Kata microVMs, confidential VMs, kosa8 or E2B) and configure trust tiers and sandbox drivers so every substrate keeps gateway-only egress.

A sandbox is the isolated environment one session runs in. MAQPNA keeps governance (identity, policy, audit, budgets, approvals, the kill switch) in the MAQPNA gateway, and keeps where the agent runs separate. Two settings decide where it runs:

• In a cluster, the trust tier (TrustTier) names a Kubernetes RuntimeClass: gVisor, Kata with Firecracker, or a confidential VM. The operator creates an upstream agent-sandbox Sandbox on that RuntimeClass.
• On a laptop or a sandbox cloud, a sandbox driver (pkg/sandbox) creates the sandbox: kosa8 (microVMs on your machine), e2b (E2B's sandbox cloud) or agent-sandbox (a cluster, from outside it).

Every driver must prove one thing before MAQPNA uses it: the sandbox can reach the gateway and nothing else.

flowchart LR
    A["Agent / AgentSession<br/>spec.tier"] --> T["TrustTier<br/>runtimeClassName"]
    T --> O["operator"]
    O --> S["agent-sandbox Sandbox<br/>gVisor / Kata / CVM"]
    D["maqpna dev run / fork<br/>--sandbox"] --> R["sandbox driver<br/>kosa8, e2b, agent-sandbox"]
    R --> M["microVM or pod"]
    S -->|"egress: gateway only"| G["MAQPNA gateway"]
    M -->|"egress: gateway only"| G

When you need this page#

• You install MAQPNA in a cluster and must decide which trust tiers to enable for your nodes.
• You run agents on a laptop in kosa8 microVMs and want to fork, snapshot or attest them.
• You want the identity broker to check the sandbox itself before it issues a session token.

The trust tiers#

The Helm chart creates three RuntimeClasses and three sample TrustTier resources (runtimeClasses and trustTiers in values.yaml):

All three set egress: gateway-only. The dev profile (values-dev.yaml) enables only gvisor.

TrustTier fields#

TrustTier is cluster-scoped (maqpna.com/v1alpha1, short names tier, tt). Full schema: TrustTier reference.

Pick a tier#

Enable only the RuntimeClasses whose runtime is installed on your nodes. A tier whose RuntimeClass is missing or unschedulable cannot start sessions.

Step 1: Enable the runtimes in Helm#

1. Write a values file that enables the tiers your nodes support. This one enables gVisor and Kata, and pins Kata to labelled nodes:

   runtimeClasses:
     gvisor:
       enabled: true
     kataFc:
       enabled: true
       nodeSelector:
         katacontainers.io/kata-runtime: "true"
     kataQemuSnp:
       enabled: false
   

2. Check the cluster with the same values. maqpna preflight checks that each enabled RuntimeClass can be installed and scheduled, and that the agent-sandbox CRDs are installed:

   maqpna preflight -f tiers.yaml
   

3. Install or upgrade:

   maqpna install -f tiers.yaml --wait
   

Step 2: Add or change a tier#

The chart's tiers are samples. To change them, set trustTiers.items, or set trustTiers.create: false and apply your own:

apiVersion: maqpna.com/v1alpha1
kind: TrustTier
metadata:
  name: tier-1-eu
spec:
  runtimeClassName: kata-fc
  isolation: microvm
  egress: gateway-only
  jurisdiction: EU-DE
  allowedNodeLabels:
    topology.kubernetes.io/region: eu-central-1
  maxSessionTTL: 2h

maqpna apply -f tier-1-eu.yaml

Step 3: Run an agent on the tier#

Set spec.tier on the agent:

apiVersion: maqpna.com/v1alpha1
kind: Agent
metadata:
  name: coder
  namespace: team-a
spec:
  tier: tier-1-eu
  # image, tools, policy, budget ...

See the Agent reference for the other fields.

Step 4: Verify#

maqpna tier list
maqpna tier get tier-1-eu
maqpna doctor

maqpna doctor compares TrustTiers with the cluster's RuntimeClasses and reports a tier whose RuntimeClass does not exist. On a running session, check the pod's RuntimeClass with kubectl get pod -n team-a -o jsonpath='{.items[*].spec.runtimeClassName}'.

Sandbox drivers#

A driver implements the contract in pkg/sandbox: create, get, attach, exec, fork, snapshot, restore, kill, attest and egress check. Three drivers are registered:

agent-sandbox is the package default (sandbox.Open("")). The maqpna dev commands default to kosa8. The Kubernetes operator does not use the driver contract yet: it drives agent-sandbox itself, from the trust tier.

Every driver keeps three rules, checked by a conformance suite (pkg/sandbox/sandboxtest):

1. The token is a file. The session token is in the file named by MAQPNA_TOKEN_FILE, never in argv or the environment. MAQPNA_TOKEN is removed.
2. Egress is the gateway only. The driver reports the egress the substrate enforces now. A loopback gateway is refused, because no isolated sandbox can reach it.
3. A copy gets its own token. Fork and restore re-key the copy before they return, or remove it.

Use kosa8 with maqpna dev#

maqpna dev up --kosa8
maqpna dev run --kosa8-image alpine:3.20 --kosa8-keep -- sh -c 'sleep 600'
maqpna dev attest
maqpna dev fork
maqpna dev snapshot

The step-by-step guide is Run agents in kosa8 sandboxes. dev run always uses kosa8. The driver finds kosa8d through KOSA8_HOST and KOSA8_TOKEN, or the user's socket.

Use E2B#

maqpna dev fork, snapshot, restore and attest take --sandbox e2b. Set:

The sandbox image is an E2B template name. CPU and memory sizes are refused: E2B sizes a sandbox by its template.

Use agent-sandbox from outside the cluster#

--sandbox agent-sandbox uses $KUBECONFIG. maqpna dev asks for microvm isolation, so set a microVM RuntimeClass:

export MAQPNA_AGENT_SANDBOX_RUNTIME_CLASS=kata-fc
maqpna dev attest --sandbox agent-sandbox --session dev-1a2b3c4d

The isolation comes from the RuntimeClass handler: runsc or gvisor gives gvisor; kata*, Firecracker or Cloud Hypervisor gives microvm; SNP, TDX, CoCo or CCA gives cvm; runc, crun or none gives process.

Let the identity broker check the sandbox#

The identity broker can ask the substrate about a sandbox before it issues a session token. Add these flags to maqpna-identity (in Helm, identity.extraArgs):

identity:
  extraArgs:
    - -sandbox-check=agent-sandbox
    - -sandbox-check-gateway=http://maqpna-gateway.maqpna-system.svc:8080
    - -sandbox-check-min-isolation=gvisor

Limits#

• agent-sandbox: no fork or snapshot (agent-sandbox 1.0 has no clone or checkpoint API). Attestation never claims measured, even on a confidential RuntimeClass. Enforcement is the CNI declaration, not a proof.
• e2b: the gateway must be an IPv4 address; E2B has no per-port rules and no IPv6 rules. Whoever holds the E2B API key can change a running sandbox's network.
• Cloudflare Sandboxes and AWS AgentCore Runtime drivers: Planned.
• Drivers for wasm and device-enclave substrates: Planned. The isolation classes exist in the contract.

Troubleshooting#

Next steps#

• Run agents in kosa8 sandboxes
• Sovereignty and confidential tiers
• Identity checks
• TrustTier reference
• Network and egress