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

> Discover how Micro VM sandboxing in Agent Substrate provides VM-level security and container-like latency with minimal kernel images and on-demand boot.

- Repository: [Agent Substrate/substrate](https://github.com/agent-substrate/substrate)
- Tags: architecture
- Published: 2026-08-22

---

**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`](https://github.com/agent-substrate/substrate/blob/main/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.

```yaml

# 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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/internal/proto/ateompb/ateom.pb.go), ensuring structured serialization of sandbox metadata and health checks.

### Network Setup

The [`internal/ateomnet/net.go`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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:

```go
// 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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/cmd/ateom-microvm/run.go), which initializes the virtual machine and guest kernel. Network configuration is handled in [`internal/ateomnet/net.go`](https://github.com/agent-substrate/substrate/blob/main/internal/ateomnet/net.go), while protocol definitions in [`internal/proto/ateompb/ateom.pb.go`](https://github.com/agent-substrate/substrate/blob/main/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.