IMP

Appearance

Architecture ​

IMP uses a split-control model:

  • Operator: cluster-scoped reconciliation, API-state orchestration
  • Agent: node-local runtime operations for Firecracker and VM networking

Core Resources ​

  • ImpVM: lifecycle of VM instances
  • ImpNetwork: NAT, DNS, and integration surface for CNI behavior
  • ImpVMSnapshot: save/restore VM state workflows
  • ImpVMMigration: orchestrate VM movement
  • ImpWarmPool: prewarmed instances from snapshot baselines
  • Runner + RunnerPool: execution pool primitives

Written Architecture Docs ​

Architecture Diagrams ​

Split-Control Overview ​

IMP split-control overview — operator and agentIMP split-control overview — operator and agent
Operator reconciles cluster-scoped state; Agent runs node-local Firecracker and networking. View standalone · dark · Click diagram to enlarge.

System Context (L1) ​

Imp L1 ContextImp L1 Context
View standalone · dark · Click to enlarge.

Containers (L2) ​

Imp L2 ContainerImp L2 Container
View standalone · dark · Click to enlarge.

Control Plane (L3) ​

Imp L3 Control PlaneImp L3 Control Plane
View standalone · dark · Click to enlarge.

Data Plane (L3) ​

Imp L3 Data PlaneImp L3 Data Plane
View standalone · dark · Click to enlarge.

Kubernetes E2E Sequence ​

Imp K8s E2E SequenceImp K8s E2E Sequence
5 lifelines, 12 messages, 1 ALT (Ready / Failed). View standalone · dark · Click to enlarge. Legacy: k8s-e2e-sequence.excalidraw.legacy.svg.

Data Flow Snapshot ​

  1. User applies CRD objects.
  2. Operator reconciles desired state and schedules operations.
  3. Agent executes host/runtime work and publishes status.
  4. Metrics and status fields expose platform health and timing.

Platform Positioning ​

Imp runs Firecracker microVMs on Kubernetes. An operator and node agent expose VM lifecycle as declarative resources. Core Imp has no sandbox dependency.

imp-sandbox is an optional add-on. It adds tenancy tiers, gateway controls, and per-sandbox tokens to ImpVM and ImpNetwork. Use it for isolated tenant sandboxes that run AI agents or untrusted code.

See Sandbox Overview for when to use base Imp vs. sandbox, and Sandbox Install for the separate chart.

Operational Notes ​

  • Cilium is the preferred networking path.
  • Fallback networking is available for non-Cilium environments.
  • Deployment pinning (image tags/Helm values) is recommended for repeatability.
  • imp-runtime DaemonSet uses updateStrategy: OnDelete. It never rolls automatically. See Manual: Day 0.
  • Practical runbooks and day-to-day guidance are in /manual.