IMP

Appearance

Quickstart ​

Imp installs as a Kubernetes operator + node agent stack and exposes VM workflows through CRDs. This quickstart uses the versioned OCI chart for v0.9.0.

Prerequisites ​

  • Kubernetes cluster (Kind supported for e2e)
  • kubectl, helm, and cluster-admin context
  • Nodes with /dev/kvm and capabilities for Firecracker runtime operations
  • At least one Ready, schedulable node labeled imp/enabled=true

Label the target node pool (Talos/Omni: via machine config patch, not kubectl label ad-hoc):

bash
kubectl label node <node-name> imp/enabled=true --overwrite
kubectl get nodes -l imp/enabled=true

Install ​

Imp's node agent mounts /dev/kvm and narrow host paths for Firecracker and the guest kernel. It requires a dedicated privileged namespace. Do not relax Pod Security Admission for application namespaces.

bash
kubectl create namespace imp-system --dry-run=client -o yaml | kubectl apply -f -
kubectl label namespace imp-system pod-security.kubernetes.io/enforce=privileged --overwrite
helm upgrade --install imp oci://ghcr.io/syscode-labs/charts/imp --version 0.9.0 -n imp-system --create-namespace
kubectl -n imp-system get pods

Alternative (pull then install from local archive):

bash
helm pull oci://ghcr.io/syscode-labs/charts/imp --version 0.9.0
helm upgrade --install imp ./imp-0.9.0.tgz -n imp-system --create-namespace

The chart defaults agent.nodeSelector and kvm.preflight.nodeSelector to imp/enabled=true. Keep that required selector when adding placement constraints.

Pin images by digest in production values (agent.image.digest, operator.image.digest). Verify digests before promotion.

Tiny Profile (Constrained Nodes) ​

For nodes with 1 vCPU / 1 GiB RAM, disable webhooks and cert-manager:

bash
helm upgrade --install imp oci://ghcr.io/syscode-labs/charts/imp --version 0.9.0 -n imp-system \
  --set webhook.enabled=false \
  --set certManager.enabled=false \
  --set serviceMonitor.enabled=false

Tiny profile is for smoke validation only — one VM at a time. Expect swap pressure and slower reconcile.

Recommended baseline for stable operation: >= 2 vCPU, >= 4 GiB RAM.

Create a Network and VM ​

Every ImpVM requires an ImpVMClass and a classRef.

bash
kubectl apply -f quickstart.yaml
yaml
apiVersion: imp.dev/v1alpha1
kind: ImpVMClass
metadata:
  name: tiny
  namespace: default
spec:
  cpu: 1
  memoryMiB: 512
---
apiVersion: imp.dev/v1alpha1
kind: ImpNetwork
metadata:
  name: quick-net
  namespace: default
spec:
  subnet: 192.168.100.0/24
  nat:
    enabled: true
  dns:
    enabled: true
---
apiVersion: imp.dev/v1alpha1
kind: ImpVM
metadata:
  name: quick-vm
  namespace: default
spec:
  image: ghcr.io/syscode-labs/imp-guestbook:latest
  classRef:
    name: tiny
  networkRef:
    name: quick-net

First VM with expireAfter ​

Imp can auto-delete a VM after a fixed window anchored to status.runningAt. 0 or unset means disabled; minimum enabled value is 60s.

yaml
apiVersion: imp.dev/v1alpha1
kind: ImpVM
metadata:
  name: quick-vm-ephemeral
  namespace: default
spec:
  image: ghcr.io/syscode-labs/imp-guestbook:latest
  classRef:
    name: tiny
  networkRef:
    name: quick-net
  expireAfter: 1h

Resolution precedence: ImpVM.spec.expireAfter → creator pool (ImpVMRunnerPool / ImpWarmPool) → ImpVMTemplate.spec.expireAfter → disabled.

Verify ​

Replace default with your namespace if different.

bash
kubectl get impvm -A
kubectl describe impvm quick-vm -n default
kubectl get impnetwork quick-net -n default -o yaml

A successful deployment shows quick-vm in Running phase.

Optional: Sandbox ​

Imp is complete without it. For isolated AI-agent sandbox tenants, extend with the optional imp-sandbox add-on:

Optional: imp-sandbox → /sandbox/ — multi-tenant isolation with standard/hard tenancy, gateway data-plane, and per-sandbox tokens. Install: oci://ghcr.io/syscode-labs/charts/imp-sandbox:0.9.0.

See Sandbox Overview and Sandbox Install — or continue to base Imp.

Next ​