Volume templates for AI agents: how to start every sandbox from a known-good state

Your coding agent picks up a task. Before writing code, it downloads an embedding model for repository search. Then it installs the model's ML dependency tree. It also clones the reference repository and builds a local code index.

That setup delays useful work, and the cost compounds across parallel sandboxes. Volume templates remove it from the sandbox lifecycle: every new sandbox finds the prepared weights, packages, repository, and index waiting at the mount path.

Teams without versioning often create one monolithic "current" template that nobody dares update. On Blaxel, volume templates are in private preview. Commands and field names below follow current docs, not a stable API.

TL;DR

• Volume templates capture a pre-populated storage state: Assemble weights, packages, and repositories once and deploy them as a template. Every volume created from it starts with that content. Initialization then drops to the time required to mount a volume.
• Templates are versioned and attach through volumes: Each bl deploy creates an auto-incremented revision. Pin production sandboxes to a revision and roll forward deliberately. Create a volume from that revision, then attach it when creating the sandbox. Batch Jobs currently support ephemeral volumes only.
• One template seeds many independent volumes: Each volume starts identically and then diverges independently. The template remains the baseline. For concurrent shared access across sandboxes or sessions, use Agent Drive instead.

Why per-sandbox initialization costs compound across a fleet

Fleet economics

Idle setup hours add up in batch and interactive fleets. That setup window is tolerable for one sandbox and expensive for a fleet. Applying the same setup to every parallel sandbox consumes substantial compute time without useful work. Larger fleets increase those idle setup costs proportionally. Setup time costs the same per second as the work it delays.

Real-time agent workloads pay differently. A coding assistant that initializes during every session makes the user wait each time. Users will not keep a tab open through repeated initialization. The fix must move setup out of the per-session path entirely. A pre-populated volume does exactly that.

Batch workloads experience the same underlying problem at a different scale. Each sandbox repeats identical downloads, installations, clones, and indexing work. That repetition consumes compute while delaying the first useful command. Building the shared baseline once makes setup a template-level task. New sandboxes can then begin from the prepared state.

Why agent workloads start heavier

Agent workloads have heavier initialization than web services. Web services amortize initialization across a warm server pool. One server boots and then handles many requests. Blaxel Sandboxes run each agent inside an isolated microVM using the same technology as AWS Lambda. Every sandbox initializes independently.

That isolation matters when the executed code is AI-generated. That isolation also removes the shared pool that makes web startup cheaper. Agent payloads are also larger. Meta-Llama-3-8B weighs about 16 GB in BF16. A 70B model needs roughly 140 GB for weights alone. That footprint makes repeated downloads and copies impractical across a fleet.

The Linux x86_64 torch wheel is 528.9 MiB before its runtime dependencies. That size makes repeated installation a meaningful startup cost. Typical web packages may be much smaller. An embedding model or code-search index can be substantially heavier. Volume templates give isolated microVMs identical starting data without sharing writable state. This restores warm-pool economics without requiring a shared kernel.

What is a sandbox volume template and how does it work?

A volume template is a versioned bundle of files. Blaxel copies those files into each new volume created from the template. The template exists in your workspace as a named object with auto-incremented revisions. A volume references one revision at creation and receives its contents. It then operates independently. The template holds the files, while each resulting volume holds a copy. Templates improve copy performance by up to 90% compared with cp -r. This improvement reduces the cost of reproducing large baselines. Reference a template as template-name:revision or template-name:latest. Deleting the template later does not affect volumes already created from it. The pattern resembles restoring an EBS volume from a snapshot. It also resembles a Docker container's writable layer over a shared image. The template stores the common baseline. Each sandbox writes changes into its own volume. Those writes cannot provide a concurrent shared filesystem for sibling sandboxes. This independence makes templates safe for fleets. An agent can corrupt its dependency tree or overwrite an index. It can also fill its own volume. The next sandbox still starts from a clean baseline. Sibling sandboxes remain unaffected because each receives an independent volume.

For concurrent read-write access, use Agent Drive shared storage, currently in private preview. Agent Drive can mount to multiple sandboxes and sessions simultaneously. Use volumes for independent block storage and raw I/O performance. Use Agent Drive when agents must share files or cross-session context. Anything large, slow to produce, and identical across sandboxes belongs in the template. System packages and the runtime belong in the sandbox image. Blaxel sandbox images come from Dockerfiles. They must include the sandbox API binary. The image owns the OS layer, while the template owns data. Large-model inference runs on separate GPU infrastructure. Templates hold embedding models, indexes, and dependency trees used directly by the agent.

Common contents include model weights and checkpoints. Use the Hugging Face structure models----/snapshots//. This cache layout lets loaders find files without code changes. Templates can also contain pre-installed Python dependencies. Install torch and its dependents into a target directory inside the template. This avoids running pip install during sandbox creation. Other candidates include reference datasets, such as fixed evaluation sets or shared corpora. Templates can hold pre-built vector and search indexes. They can also contain cloned repositories at a pinned commit. A checked-out tree lets the agent begin editing immediately. Everything in this list is read at startup and changes infrequently between deployments. Put stable, heavy inputs in the template. Leave the agent's working output in the writable remainder of the volume.

How to create and use a volume template

Build the contents in a directory and deploy them as a revision, then create a volume from that revision and attach it when creating the sandbox. The template reference belongs on the volume, not the sandbox specification.

Assemble and deploy template contents

1. Create and populate the template contents. Start by scaffolding a template project with the CLI:```bash bl new volume-template mytemplate

The command generates a blaxel.toml; its volume-template configuration uses 2048 MB as the default capacity:toml type = "volume-template" directory = "." # "." includes everything; "app" includes only app/ subdirectory defaultSize = 2048 # Default size in MB Everything under directory becomes the template's contents. Run setup against that directory rather than against a sandbox. Point model downloads inside it using local_dir. Install packages there with pip install --target.Clone the repository and build the index in the same directory. Blaxel volumes are block storage accessible through an attached, running sandbox. They cannot mount directly on your machine. The local directory is the assembly point.Run assembly in CI rather than on a laptop. Pin the model revision and package versions. Pin the repository commit as well. A pipeline using those pins reproduces the same directory. That reproducibility makes template revisions meaningful.Set defaultSize above the final directory size. 2. Deploy the template as a revision. Deploy from the template directory:bash bl deploy ```Each deployment creates a new revision. Revisions auto-increment and remain available for rollback. Run bl deploy --dryrun first to inspect the planned upload.Confirm the result with bl get volumetemplates, which lists your templates. The API path is POST /volume_templates. Passing upload=true returns a presigned content URL through the create endpoint. The version query parameter names the version being created.A template name permits lowercase alphanumeric characters and hyphens. It supports at most 49 characters and becomes immutable after creation. The same create endpoint defines these constraints. Names remain fixed while revisions increment automatically.Put the content description in the name and let revisions carry the version. embedding-model-weights and ml-deps-torch-2-14 work. Dots are not allowed, so torch-2.14 fails validation. displayName supports a longer human-readable label. The same endpoint imposes a 63-character limit. That limit keeps labels concise while allowing more context than immutable names.

Create, attach, and validate the volume

3. Create a volume from the template and attach it at sandbox creation. Create the volume first. The volume specification accepts "mytemplate:1" or "mytemplate:latest" in its template field. The volume's region must match the sandbox's region.Size the volume above the template's content. Creation fails when the volume is smaller than the template data. Provision at least 20–30% extra space beyond the content size. This headroom accommodates subsequent writes without excessive overprovisioning.Then attach the volume. The sandbox volumes entry accepts name, mountPath, and readOnly. Blaxel allows one volume per sandbox. In TypeScript:```typescript import { VolumeInstance, SandboxInstance } from "@blaxel/core";

const volume = await VolumeInstance.createIfNotExists({ name: "myvolume", template: "mytemplate:1", region: "us-pdx-1", });

const sandbox = await SandboxInstance.createIfNotExists({ name: "my-sandbox", image: "blaxel/nextjs:latest", memory: 4096, region: "us-pdx-1", volumes: [{ name: "myvolume", mountPath: "/mnt/data", readOnly: false }], }); ```The Python SDK uses create_if_not_exists. It mirrors mountPath and readOnly as mount_path and read_only. Create one sandbox using this configuration. List the mount path before any initialization code runs. 4. Validate and benchmark initialization time. Measure from sandbox creation until the first useful command. Test once with a template-backed volume and once with a cold setup script. The difference is the removed setup work.Record the result for each template. This makes regressions visible when a revision grows. Then verify that the agent reads from the mount path. Hard-coded paths expecting ~/.cache can trigger re-downloads.For Hugging Face models, point HF_HUB_CACHE to the volume's cache directory. Set HF_HUB_OFFLINE=1 so no HTTP calls reach the Hub. TRANSFORMERS_CACHE is superseded, so do not rely on it. Pass local_files_only=True to from_pretrained as a second guard.For sentence-transformers, use cache_folder or SENTENCE_TRANSFORMERS_HOME. For PyTorch Hub checkpoints, point TORCH_HOME at the volume. Correct cache paths prevent hidden network setup and preserve the template's startup gains.

How to version and update volume templates

A template is a snapshot. It does not automatically acquire a new model release or patched package. Every update must be deliberate.

Pin revisions and coordinate releases

• Version templates like container images. Never modify a released revision in place. Ship every change as a new revision. Each bl deploy creates another auto-incremented revision. Pin revisions in production.Referencing mytemplate:latest can select an unexpected artifact. The target may change between deciding to deploy and completing deployment. Pinning mytemplate:3 is the closest analog to a digest reference.Refresh the template directory with new weights and package versions. Update the repository commit as needed. Run bl deploy and record the new revision. Change the pinned reference in the volume specification. The sandbox references only the volume by name.Old revisions remain available for rollback. Created volumes operate independently from their source template. Sandboxes already holding a volume retain their original contents.
• Coordinate template updates with agent code changes. Ship the template revision with the agent code that requires it. Release configuration files alongside their binaries because they are tightly bound. New model weights and code using a new model API have the same coupling.Independent deployment can leave either side incompatible. Store the pinned revision beside the sandbox configuration in the agent repository. A pull request changing the model should also update mytemplate:3 to mytemplate:4. Reviewers can inspect both changes together and reject mismatched pairs.Rollback follows the same path in reverse. Roll back first and diagnose afterward. With the revision pinned in the repository, rollback becomes a revert commit. New sandboxes then point to the prior revision. No template rebuild or fresh upload is required.

Prune retained revisions

• Prune old template versions to control storage costs. Every retained revision occupies storage. Blaxel bills volumes at $0.12 per GB-month based on provisioned size. Billing continues for as long as the volume exists. The charge applies regardless of the written data.Every volume outliving its sandbox continues billing at its full provisioned size. Delete volumes when their sandboxes are gone. Size volumes to their content plus headroom rather than an arbitrary round number.Define and enforce a retention policy for templates. Keep the current revision and a limited rollback set. Each version object reports its contentSize. The API supports per-version deletion at DELETE /volume_templates/{volumeTemplateName}/versions/{versionName}. Before deleting a revision, confirm that the current production specification points to a newer pinned revision and preserve the last known-good rollback target.Account tiers also limit volume template sizes and versions. Unpruned revisions therefore count against your tier. Keep the current revision and the last known-good revision. Archive older revisions to your own object storage before deleting them.

Eliminate per-sandbox initialization at the template layer

Volume templates are the right boundary for large, stable startup data that every sandbox needs. Start with the fleet's heaviest such input, usually model weights or a dependency tree.

After deployment, compare time to first useful command against cold setup and keep mutable output in each volume. This turns template adoption into a measurable rollout rather than a wholesale migration.

Blaxel, the perpetual sandbox platform, supports volume templates natively on Blaxel Volumes. Volume sizes can increase through PUT /volumes/{volumeName}, but they cannot decrease. Start building at app.blaxel.ai or contact the team at blaxel.ai/contact.