Skip to main content
Templates define the base environment for new sandboxes. Use them when setup should not run on every sandbox create: language runtimes, package managers, browser stacks, agent tools, desktop dependencies, or services that should start automatically.
Template build and logging are microVM-runtime beta surfaces.

​
When To Build A Template

NeedTemplate Strategy
Faster sandbox startupMove repeated package installs into a template.
Consistent runtime dependenciesPin apt, pip, npm, files, and env defaults in the builder.
A service should be ready after createUse start commands and readiness checks.
You already have an image or DockerfileBuild from an image, Dockerfile, or standard base.
You need traceable versionsBuild with names and tags, then launch by canonical ref.

​
Quick Example

from nullspace import Sandbox, Template, default_build_logger

builder = (
    Template()
    .from_python_image("3.12")
    .apt_install(["git", "curl"])
    .pip_install(["fastapi", "uvicorn"])
    .set_runtime_envs({"APP_ENV": "demo"})
)

build = Template.build(
    builder,
    name="fastapi-agent",
    tags=["stable"],
    on_log_entry=default_build_logger(),
)

with Sandbox.create(template=build.canonical_ref) as sandbox:
    print(sandbox.commands.run("python3 --version", shell=True).stdout)

​
Build Model

ConceptMeaning
BuilderThe SDK object or Dockerfile/image source that describes the environment.
BuildThe operation that turns the builder into a reusable template artifact.
Template refThe name, tag, or canonical ref used by Sandbox.create(template=...).
Runtime envsEnvironment defaults present when sandboxes start from the template.
Build envs and secretsValues available only while the template is built.

​
Template Tasks

Quickstart

Build and launch your first reusable sandbox template.

How it works

Understand how template builds turn setup steps into sandbox snapshots.

Base image

Start from standard images, existing templates, custom images, or Dockerfiles.

Defining template

Install packages, copy files, clone repos, run commands, and set envs.

Start and ready commands

Start services automatically and wait for ports, URLs, files, or commands.

Warm pools

Keep ready capacity for a template and choose fallback behavior at create time.

Build

Build, wait, tune resources, and control cache behavior.

Logging

Stream build logs, reconnect, and inspect cache events.