How Micro-VM Sandboxing Works in Agent Substrate: Architecture and Implementation

Agent Substrate isolates each actor inside a dedicated Micro-VM using the ateom-microvm binary, combining VM-level security with container-like latency through minimal kernel images and on-demand boot processes.

Agent Substrate leverages Micro-VM sandboxing to provide strong isolation boundaries for lightweight workloads while maintaining minimal overhead. The open-source agent-substrate/substrate repository implements this architecture by spawning dedicated virtual machines via the ateom-microvm command-line tool, ensuring each actor operates within its own kernel instance rather than sharing the host OS.

Micro-VM Architecture Components

The sandboxing stack consists of three distinct layers working in concert. The control plane schedules actors onto worker nodes, the ateom-microvm binary (cmd/ateom-microvm/run.go) initializes the virtual hardware, and the atelet runtime executes inside the VM to manage the actor’s lifecycle.

Unlike standard containers that share the host kernel, each Micro-VM runs a minimal Linux kernel image—optionally using Firecracker or Kata Containers as the virtual machine monitor (VMM). This design ensures that a compromised actor cannot exploit kernel vulnerabilities to escape to the host or access other actors’ memory spaces.

Sandbox Configuration

Before booting, the system generates a SandboxConfig custom resource that defines the VM parameters. The template located at manifests/microvm/sandboxconfig-microvm.yaml.tmpl specifies the container image, resource limits, network policies, and security profiles required for the actor.

# Example sandbox config for a Micro-VM (templates/sandboxconfig-microvm.yaml.tmpl)

apiVersion: substrate.io/v1alpha1
kind: SandboxConfig
metadata:
  name: my-microvm
spec:
  image: ghcr.io/agent-substrate/atelet:latest
  sandbox: microvm
  resources:
    cpu: "0.5"
    memory: "256Mi"

The Micro-VM Boot Sequence

VM Initialization

In cmd/ateom-microvm/run.go, the main entry point creates the VM instance, attaches the root filesystem as a thin overlay, and configures the virtual CPU and memory. This file orchestrates the transition from YAML configuration to a running virtual machine, implementing the cold-boot logic that initializes the guest kernel.

Runtime Startup

Once the Micro-VM boots, it launches the atelet process inside the guest. This process registers the actor with the Substrate control plane and begins pulling workload definitions. Communication between the control plane and the VM uses protocol buffer definitions found in internal/proto/ateompb/ateom.pb.go, ensuring structured serialization of sandbox metadata and health checks.

Network Setup

The internal/ateomnet/net.go file manages the virtual network interface, creating isolated bridges and veth pairs that connect the VM to the cluster network. This setup ensures the actor operates within its own network namespace, preventing traffic sniffing or unauthorized connections to other tenants on the same physical host.

Security Isolation Mechanisms

Each Micro-VM enforces multi-layered isolation through the following mechanisms:

• Dedicated Kernel Instances: Each VM boots its own minimal Linux kernel, eliminating the attack surface shared by container runtimes.
• cgroups and seccomp: Resource limits and system call filtering are applied at the VM level, restricting the actor’s ability to consume excessive CPU or execute dangerous syscalls.
• Namespace Isolation: The VM maintains separate PID, mount, and network namespaces, ensuring filesystem and process visibility is constrained to the sandbox boundary.
• Optional gVisor Integration: When selected, gVisor provides an additional userspace kernel for syscall interception, adding defense-in-depth beyond the hardware virtualization layer.

Performance Characteristics

The Micro-VM implementation prioritizes startup latency through aggressive minimization. Cold boots complete in a few hundred milliseconds because the root filesystem contains only the binaries strictly necessary for the atelet runtime. Subsequent warm starts—reusing initialized VMs from a pool—are nearly instantaneous, allowing Substrate to achieve container-like scheduling speeds with VM-grade security boundaries.

For local development and testing of these sandboxes, refer to the detailed setup instructions in docs/dev/microvm-local.md, which covers building the ateom-microvm binary and configuring local VMM dependencies.

Implementation Example

The following Go code illustrates how the Substrate worker initializes a Micro-VM sandbox for an actor, mirroring the logic found in the production implementation:

// Launch a Micro-VM for an actor (simplified)
ctx := context.Background()
cfg := sandboxConfigFromYAML("manifests/microvm/sandboxconfig-microvm.yaml.tmpl")
vm, err := microvm.New(ctx, cfg)          // creates the VM (runsc/kata)
if err != nil { log.Fatalf("boot failed: %v", err) }

atelet := vm.StartAtelet(ctx)              // starts the Substrate runtime inside the VM
defer atelet.Close()

Summary

• Micro-VM sandboxing in Agent Substrate uses cmd/ateom-microvm/run.go to launch isolated VMs per actor, providing hardware-virtualized boundaries.
• Configuration templates in manifests/microvm/sandboxconfig-microvm.yaml.tmpl define VM parameters, images, and resource constraints.
• The atelet runtime executes inside each VM, handling actor logic while isolated by dedicated kernel instances.
• Networking isolation is managed through internal/ateomnet/net.go, creating separate network stacks for each sandbox.
• Cold boot latency remains low (hundreds of milliseconds) while delivering security guarantees superior to standard container runtimes.

Frequently Asked Questions

How does Micro-VM sandboxing differ from standard Docker containers in Agent Substrate?

Standard Docker containers share the host kernel, offering process-level isolation through namespaces. Agent Substrate Micro-VMs run dedicated kernel instances via ateom-microvm, providing hardware-virtualized boundaries that prevent kernel exploits from affecting the host or other actors, effectively eliminating the shared-kernel attack surface.

Which source files control the Micro-VM boot process?

The primary orchestration occurs in cmd/ateom-microvm/run.go, which initializes the virtual machine and guest kernel. Network configuration is handled in internal/ateomnet/net.go, while protocol definitions in internal/proto/ateompb/ateom.pb.go facilitate communication between the control plane and the VM-internal atelet process.

What is the typical boot time for a Micro-VM in this architecture?

According to the implementation in agent-substrate/substrate, cold boots complete in a few hundred milliseconds due to minimal kernel images and thin root filesystems. Warm reuses of initialized VMs are nearly instantaneous, matching container startup speeds while maintaining VM isolation.

Can gVisor be used with Agent Substrate Micro-VMs?

Yes, the architecture supports optional gVisor integration for additional syscall interception and filtering. When enabled, gVisor runs inside the Micro-VM to provide a secondary defense layer, sandboxing the actor’s syscalls before they reach the guest kernel.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}