Sandbox

Imp is a Firecracker-on-Kubernetes platform — a cluster operator + node agent that orchestrates microVMs (ImpVM, ImpNetwork, ImpVMSnapshot, etc.) on Firecracker with Cilium-first networking. It is complete and production-usable on its own.

imp-sandbox is an optional add-on. It does not replace Imp. It extends Imp for multi-tenant AI-agent sandbox workloads where each sandbox needs isolation, network policy, and data-plane controls beyond what base ImpVM provides.

Positioning

Layer	What it is	When you need it
Imp (core)	Firecracker-on-K8s VM orchestration	VM lifecycle, networking, snapshots, migrations, warm pools, runner pools
imp-sandbox (optional)	Tenant isolation add-on on top of Imp	Untrusted code execution, per-tenant network boundaries, gateway-enforced egress

Install Imp first. Add sandbox only if your use case requires tenant isolation. Core ImpVM operation never requires sandbox.

Tenancy Tiers

imp-sandbox defines two tenancy tiers:

• standard — namespace + NetworkPolicy isolation, shared kernel scheduler, gateway egress filtering. Suitable for trusted tenants or soft multi-tenancy where Cilium is optional.
• hard — strict isolation: dedicated microVM boundaries, Cilium network policies enforced, per-sandbox token auth at the gateway, and no shared data-plane bypass. Requires Cilium (CiliumExternalWorkload + CiliumNetworkPolicy). Non-Cilium clusters cannot use hard.

Tenancy is set per sandbox resource; mixing tiers in one cluster is supported.

When to Use Sandbox vs. Base ImpVM

Use base ImpVM when:

• You orchestrate VMs for CI runners, batch jobs, or platform-owned services.
• Network isolation is namespace-level or Cilium NetworkPolicy on the VM network is sufficient.
• You do not need per-tenant tokens or gateway data-plane.

Use imp-sandbox when:

• You run untrusted or AI-generated code that must not see other tenants.
• You need per-sandbox auth tokens and gateway-enforced egress/host allowlists.
• You need hard tenancy guarantees and already run Cilium.

Architecture

User → Sandbox CR → imp-sandbox controller → ImpVM/ImpNetwork (Imp core)
                        │
                        └→ Gateway data-plane (per-sandbox token, egress policy)
                        └→ Cilium (hard tenancy: CiliumNetworkPolicy, ExternalWorkload)

The sandbox controller reconciles sandbox tenants into ImpVM primitives; the gateway enforces data-plane policy. Imp remains the VM runtime — sandbox never bypasses it.

Next

• Install — OCI chart, namespaces, tokens, Cilium requirement
• Tenancy — tier details and policy matrix
• Gateway — data-plane and token flow
• Troubleshooting — common failure classes

For base VM workflows, see Quickstart and Manual.