Sandbox

Imp runs Firecracker microVMs on Kubernetes. Its operator and node agent manage ImpVM, ImpNetwork, and ImpVMSnapshot resources with Cilium-first networking. Core Imp does not require sandbox.

imp-sandbox is an optional add-on. It adds isolation, network policy, and gateway controls for multi-tenant AI-agent workloads.

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 and NetworkPolicy isolation, a shared kernel scheduler, and gateway egress filtering. Use it for trusted tenants or soft multi-tenancy. Cilium is optional.
• hard: each sandbox runs in its own microVM. CiliumNetworkPolicy and CiliumExternalWorkload enforce isolation. The gateway checks a per-sandbox token. Cilium is required; 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

View standalone · dark · Click to enlarge.

The sandbox controller reconciles sandbox tenants into ImpVM resources. The gateway enforces data-plane policy (per-sandbox token, egress) and Cilium enforces hard-tenancy policy (CiliumNetworkPolicy, ExternalWorkload). Imp remains the VM runtime; sandbox does not bypass 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.