# Agent Substrate Sandbox Runtimes: gVisor and MicroVM Configuration Guide

> Explore Agent Substrate's gVisor and MicroVM sandbox runtimes for configurable isolation. Learn how to set up these secure environments for actor execution.

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

---

**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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/sandboxconfig_types.go) (lines 23-30):

```go
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`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/workerpool_types.go) exposes the `SandboxClass` field as a string:

```go
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:

```yaml
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`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/actortemplate_types.go) contains a matching `SandboxClass` field that must align with the hosting WorkerPool's configuration:

```go
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:

```yaml
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`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/sandboxconfig_types.go) allows detailed runtime customization:

```go
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:

```yaml
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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/sandboxconfig_types.go).