# What Is an ActorTemplate in Agent Substrate? The Complete CRD Guide

> Learn what an ActorTemplate is in Agent Substrate a Kubernetes CRD that blueprints runnable actors defining containers volumes sandbox runtimes and snapshot configurations

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

---

**An ActorTemplate is a Kubernetes Custom Resource Definition (CRD) that serves as an immutable blueprint for deploying runnable actors in Agent Substrate, defining containers, volumes, sandbox runtimes, and snapshot configurations.**

The agent-substrate/substrate repository implements a distributed actor runtime where the **ActorTemplate** acts as the declarative contract between users and the scheduler. This CRD encapsulates every immutable aspect of an actor's configuration, enabling the control plane to validate, schedule, and sandbox workloads consistently across worker pools.

## Core Concept and Architecture

In Agent Substrate, an **actor** represents the smallest unit of work that the substrate scheduler can place onto a worker pool. The **ActorTemplate** defines the immutable specification for these actors, ensuring that snapshots built from a template remain valid for the entire lifecycle of the actor.

According to the source definitions in [`pkg/api/v1alpha1/actortemplate_types.go`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/actortemplate_types.go), the `ActorTemplate` type combines a specification (`ActorTemplateSpec`) with a status subresource (`ActorTemplateStatus`). This structure follows standard Kubernetes patterns, allowing the **atecontroller** to watch for changes, reconcile desired state, and report current conditions.

## ActorTemplate Spec Structure

The `ActorTemplateSpec` struct defined at lines 129-165 of [`actortemplate_types.go`](https://github.com/agent-substrate/substrate/blob/main/actortemplate_types.go) contains the complete declarative configuration for actor instantiation.

### Containers and Workloads

The **containers** field defines the executable workloads that run inside the sandbox. Each container specification includes the container image (which must use a pinned digest format containing `@`), command arguments, environment variables, and capability grants. The configuration also supports **readiness probes** to signal when the actor is prepared to accept work.

### Volume Mounts and Storage

Volumes provide durable and ephemeral storage options. The template supports:

- **Durable directories** that survive actor pauses and resumes
- **External CSI volumes** for persistent data
- **Read-only OCI image mounts** for distributing static assets
- **System-info volumes** that expose actor identity and trust bundles to the running workload

Each volume is defined in the `volumes` array and mounted via the `volumeMounts` field within container specifications.

### Snapshot Configuration

The **snapshotsConfig** field controls how actor state is captured and restored. Key parameters include:

- **location**: Storage URI (e.g., `s3://bucket/path`) for snapshot data
- **onPause**: Capture mode when pausing (`Full` captures complete state, `Data` captures only data volumes)
- **onCommit**: Capture mode when committing changes

This configuration enables fast resume capabilities and golden-state reuse across actor instances.

### Sandbox Runtime Selection

The **sandboxClass** field determines the isolation technology used to host the actor. Agent Substrate supports two runtime classes:

- **gvisor**: Userspace kernel isolation suitable for general workloads
- **microvm**: Lightweight virtual machine isolation for enhanced security boundaries

This selection directly impacts the security model and performance characteristics of the running actor.

### Resource Limits and Worker Selection

The template specifies **CPU and memory limits** that size the sandbox environment. Unlike typical Kubernetes resources, Agent Substrate omits requests and claims, focusing strictly on hard limits to prevent resource exhaustion.

The **worker selector** field accepts a label selector that restricts which worker pools may run the actor, enabling topology-aware scheduling and hardware-specific placement.

## Lifecycle Tracking via Status

The `ActorTemplateStatus` struct (lines 92-105) tracks the operational state of the template through its **status** subresource. Key fields include:

- **Phase**: Current lifecycle state such as `Ready`, `Failed`, or `ResumeGoldenActor`
- **Golden snapshot identifier**: Reference to the canonical snapshot used for new actor instantiation
- **Conditions**: Observed state transitions and reconciliation results

The controller in [`cmd/atecontroller/internal/controllers/actortemplate_controller.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/atecontroller/internal/controllers/actortemplate_controller.go) continuously updates these fields as it reconciles the desired specification against the current state of the worker pool.

## Creating an ActorTemplate: YAML Example

Below is a minimal manifest that creates an ActorTemplate named `hello-world`. It launches a single container, mounts a durable directory, and configures S3-based snapshots:

```yaml
apiVersion: api.ate.dev/v1alpha1
kind: ActorTemplate
metadata:
  name: hello-world
spec:
  sandboxClass: gvisor                # run the actor in a gVisor sandbox

  containers:
    - name: app
      image: "busybox@sha256:12345"   # pinned image (must contain '@')

      command: ["sh", "-c"]
      args: ["while true; do echo hello; sleep 5; done"]
      volumeMounts:
        - name: data
          mountPath: /data
  volumes:
    - name: data
      durableDir: {}                  # durable directory that survives resumes

  snapshotsConfig:
    location: "s3://my-substrate-snapshots/hello-world"
    onPause: Full
    onCommit: Data

```

This manifest can be applied directly to a cluster running the Agent Substrate control plane. The generated installer manifest at [`manifests/ate-install/generated/ate.dev_actortemplates.yaml`](https://github.com/agent-substrate/substrate/blob/main/manifests/ate-install/generated/ate.dev_actortemplates.yaml) provides additional default templates and validation schemas.

## Controller Implementation and Validation

The **atecontroller** component watches ActorTemplate objects and reconciles them onto compatible worker pools. In [`cmd/atecontroller/internal/controllers/actortemplate_controller.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/atecontroller/internal/controllers/actortemplate_controller.go), the controller:

1. Validates the template using `kubebuilder` X-validation markers embedded in the Go types
2. Schedules the actor onto workers matching the selector criteria
3. Instantiates the specified sandbox runtime (gVisor or micro-VM) with the requested resource limits
4. Manages snapshot lifecycle operations for pause, resume, and commit events

Because the specification is immutable after creation, the controller can guarantee that snapshots remain compatible with the original template configuration, preventing state corruption during restore operations.

## Summary

- **ActorTemplate** is a Kubernetes CRD in Agent Substrate that defines the immutable configuration for runnable actors.
- The spec includes containers, volumes, snapshot configurations, sandbox runtime selection, resource limits, and worker selectors.
- Source definitions reside in [`pkg/api/v1alpha1/actortemplate_types.go`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/actortemplate_types.go), with the `ActorTemplate`, `ActorTemplateSpec`, and `ActorTemplateStatus` types.
- The controller at [`cmd/atecontroller/internal/controllers/actortemplate_controller.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/atecontroller/internal/controllers/actortemplate_controller.go) reconciles these resources against worker pools.
- Templates support gVisor and microvm sandboxes, with configurable snapshotting to S3-compatible storage for fast resume and golden-state management.

## Frequently Asked Questions

### What is the difference between an Actor and an ActorTemplate in Agent Substrate?

An **ActorTemplate** is the immutable blueprint that defines how an actor should be constructed, including its containers, volumes, and runtime configuration. An **actor** is the actual running instance created from that template, representing the smallest unit of work that the substrate scheduler places onto a worker pool. While the template remains static, actors are dynamic entities that can be paused, resumed, and snapshotted during their lifecycle.

### Can I update an ActorTemplate after creation?

No, the **ActorTemplate** specification is immutable after creation, as enforced by the API design in [`pkg/api/v1alpha1/actortemplate_types.go`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/actortemplate_types.go). This immutability guarantees that snapshots captured from running actors remain valid and compatible with the original configuration. To modify an actor's configuration, you must create a new ActorTemplate with the desired changes and instantiate fresh actors from that new template.

### Which sandbox runtimes does Agent Substrate support?

Agent Substrate supports two sandbox runtimes specified via the `sandboxClass` field: **gvisor** (userspace kernel isolation) and **microvm** (lightweight virtual machine isolation). The choice between these depends on your security requirements and performance needs, with microvm providing stronger isolation boundaries at the cost of slightly higher overhead compared to gVisor.

### How does snapshotting work with ActorTemplates?

The **snapshotsConfig** field in an ActorTemplate defines where snapshots are stored (via the `location` URI) and what data is captured during lifecycle events. The `onPause` and `onCommit` fields support `Full` (complete state including memory) or `Data` (volumes only) capture modes. These snapshots enable rapid actor resumption and golden-state reuse, with the snapshot location typically pointing to S3-compatible object storage for durability.