Agent Substrate Sandbox Runtimes: gVisor and MicroVM Configuration Guide

Agent Substrate supports two distinct sandbox runtimes—gVisor and MicroVM—that provide configurable isolation levels for actor execution via the SandboxClass API.

Agent Substrate is an open-source platform for running isolated workloads in containerized environments. The system implements a pluggable sandboxing architecture through two officially supported runtime families, allowing operators to balance security guarantees against startup performance based on workload requirements.

Supported Sandbox Runtimes

Agent Substrate provides native support for two sandbox classes that represent different approaches to workload isolation.

gVisor Runtime

The gVisor runtime uses the runsc user-space kernel to intercept and filter system calls. This option provides the default sandbox for Agent Substrate deployments, offering strong isolation with minimal overhead by implementing a substantial portion of the Linux kernel surface in user space.

In the source code, this runtime is identified by the constant SandboxClassGvisor with the string value "gvisor". The Protocol Buffer definition in pkg/proto/ateapipb/ateapi.proto (lines 355-371) declares this as SANDBOX_CLASS_GVISOR = 1, while the generated Go code in pkg/proto/ateapipb/ateapi.pb.go (lines 214-222) maps this to the exported constant.

MicroVM Runtime

The MicroVM runtime executes actors inside lightweight virtual machines using technologies such as Firecracker or Kata Containers. This approach delivers stronger isolation boundaries than gVisor by leveraging hardware virtualization, though it incurs slightly higher cold-start latency due to VM initialization overhead.

This runtime corresponds to SandboxClassMicroVM with the value "microvm" in the public API. The protobuf enum assigns this SANDBOX_CLASS_MICROVM = 2, as defined in the generated Go bindings at lines 214-222 of pkg/proto/ateapipb/ateapi.pb.go.

Configuration Architecture

Sandbox selection in Agent Substrate spans multiple layers of the API, from low-level Protocol Buffer messages to high-level Kubernetes Custom Resources.

Protocol Buffer Definitions

The canonical definition of sandbox classes resides in pkg/proto/ateapipb/ateapi.proto. Lines 355-371 define the SandboxClass enumeration and its integration within the SandboxConfig message structure. These definitions govern the wire format for all sandbox-related API communications.

The generated Go bindings in pkg/proto/ateapipb/ateapi.pb.go expose these as typed constants:

• SANDBOX_CLASS_GVISOR SandboxClass = 1
• SANDBOX_CLASS_MICROVM SandboxClass = 2

Go API Types

The public Kubernetes API surface defines string-based constants in pkg/api/v1alpha1/sandboxconfig_types.go (lines 23-30):

const (
    SandboxClassGvisor  = "gvisor"
    SandboxClassMicroVM = "microvm"
)

These constants type the SandboxClass field used across WorkerPool, ActorTemplate, and SandboxConfig resources, ensuring compile-time validation of runtime selectors.

Implementing Sandbox Selection

Configuring sandbox runtimes requires specifying the SandboxClass field at multiple levels of the resource hierarchy.

WorkerPool Configuration

WorkerPools define the default sandbox runtime for all actors scheduled to that pool. The WorkerPoolSpec struct in pkg/api/v1alpha1/workerpool_types.go exposes the SandboxClass field as a string:

type WorkerPoolSpec struct {
    // SandboxClass selects the sandbox runtime family for this pool.
    // Valid values are "gvisor" or "microvm".
    SandboxClass string `json:"sandboxClass,omitempty"`
    // ... other fields ...
}

To deploy a gVisor-based worker pool:

apiVersion: ate.io/v1alpha1
kind: WorkerPool
metadata:
  name: gvisor-workers
spec:
  sandboxClass: gvisor

ActorTemplate Specification

Individual actors can specify sandbox requirements through the ActorTemplate resource. The ActorTemplateSpec in pkg/api/v1alpha1/actortemplate_types.go contains a matching SandboxClass field that must align with the hosting WorkerPool's configuration:

type ActorTemplateSpec struct {
    // SandboxClass selects the sandbox runtime family for this actor.
    // Must match the sandboxClass of the WorkerPool that will run it.
    SandboxClass SandboxClass `json:"sandboxClass,omitempty"`
}

Example MicroVM specification:

apiVersion: ate.io/v1alpha1
kind: ActorTemplate
metadata:
  name: high-isolation-actor
spec:
  sandboxClass: microvm

SandboxConfig Resources

For advanced use cases, the SandboxConfig type defined in pkg/api/v1alpha1/sandboxconfig_types.go allows detailed runtime customization:

type SandboxConfig struct {
    SandboxClass SandboxClass `json:"sandboxClass"`
    // The container image that provides the sandbox runtime binaries.
    // For gVisor this is the runsc image; for microvm this is the VM image.
    SandboxBinary string `json:"sandboxBinary,omitempty"`
    // Optional: a pause container image that forms the root "sandboxes"
    // container for the actor.
    PauseImage string `json:"pauseImage,omitempty"`
}

Example configuration with custom binaries:

apiVersion: ate.io/v1alpha1
kind: SandboxConfig
metadata:
  name: custom-gvisor-config
spec:
  sandboxClass: gvisor
  sandboxBinary: ghcr.io/google/gvisor/runsc:latest
  pauseImage: registry.k8s.io/pause:3.9

Example Manifests

Agent Substrate includes reference implementations demonstrating proper sandbox configuration. The repository provides complete YAML definitions in the manifests directory:

• manifests/ate-install/sandboxconfig-gvisor.yaml: Demonstrates standard gVisor deployment patterns
• manifests/ate-install/sandboxconfig-microvm.yaml.tmpl: Provides a template for MicroVM configuration with Firecracker integration

These files illustrate production-ready configurations including binary image references and pause container specifications.

Summary

• Agent Substrate supports two sandbox runtimes: gVisor (user-space kernel) and MicroVM (hardware virtualization).
• Runtime selection is controlled via the SandboxClass field, accepting string values "gvisor" or "microvm".
• Configuration occurs at multiple levels: WorkerPools define default runtimes, while ActorTemplates can specify specific isolation requirements.
• Source definitions reside in pkg/proto/ateapipb/ateapi.proto (protobuf) and pkg/api/v1alpha1/sandboxconfig_types.go (Go API).
• Example configurations are available in the manifests/ate-install/ directory for both runtime families.

Frequently Asked Questions

How do I choose between gVisor and MicroVM in Agent Substrate?

Select gVisor when you require strong isolation with minimal startup overhead and moderate syscall filtering is sufficient for your threat model. Choose MicroVM when you need hardware-level isolation boundaries or must run untrusted code that requires kernel-level protection, accepting the trade-off of slightly higher initialization latency.

Can I run different sandbox runtimes in the same Agent Substrate cluster?

Yes. Agent Substrate supports heterogeneous deployments where specific WorkerPools enforce distinct sandbox classes. Configure the sandboxClass field in each WorkerPool spec (defined in pkg/api/v1alpha1/workerpool_types.go) to assign different runtime families to separate node pools, then schedule ActorTemplates to matching pools based on their sandboxClass requirements.

What is the default sandbox runtime if I don't specify a sandboxClass?

The system defaults to gVisor ("gvisor") when no sandboxClass is explicitly declared. This default provides immediate security boundaries through user-space kernel interception without requiring additional VM infrastructure. Always verify the default behavior in your specific Agent Substrate version by checking the SandboxClassGvisor constant definition in pkg/api/v1alpha1/sandboxconfig_types.go.

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