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

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, 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 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 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:

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 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, 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, with the ActorTemplate, ActorTemplateSpec, and ActorTemplateStatus types.
• The controller at 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. 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.

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