Skip to main content
On this page

Persistent Volumes

Persistent volumes let you attach regional block storage to a sandbox so data survives process restarts and new connections. They are ideal for package caches, build artifacts, SQLite databases, or any workflow that needs a small amount of durable storage without promoting code to a full Deno Deploy app.

Note

Persistent volumes are currently in private beta. Contact support to request access to this feature

Provision storage with Client.volumes Jump to heading

Use the same Client class that manages Deploy apps.

import { Client } from "@deno/sandbox";

const client = new Client();

const volume = await client.volumes.create({
  slug: "training-cache",
  region: "ord", // ord (Chicago) or ams (Amsterdam)
  capacity: "2GB", // accepts bytes or "1GB"/"512MB" style strings
});

console.log(volume);
// {
//   id: "8a0f...",
//   slug: "training-cache",
//   region: "ord",
//   capacity: 2147483648,
//   used: 0
// }
Field Required Details
slug ✅ Unique per organization. Slugs become part of the mount metadata, so pick something descriptive.
region ✅ Must match an available sandbox region ("ord" or "ams" today). Only sandboxes in the same region can mount the volume.
capacity ✅ Between 300 MB and 20 GB. Pass a number of bytes or a string with GB/MB/KB (decimal) or GiB/MiB/KiB (binary) units.

Inspect and search volumes Jump to heading

client.volumes.list() returns paginated results plus a helper iterator, while client.volumes.get() fetches a single record by slug or UUID.

const page = await client.volumes.list({ search: "training" });
for (const info of page.items) {
  console.log(
    info.slug,
    formatBytes(info.used),
    "of",
    formatBytes(info.capacity),
  );
}

const latest = await client.volumes.get("training-cache");

The used field reports the most recent estimate the control plane received from the underlying cluster. It can lag a few minutes behind reality, so always size volumes with headroom.

Mount volumes inside a sandbox Jump to heading

Pass a volumes map when calling Sandbox.create(). Keys are mount paths and values are either the volume slug or ID. The sandbox and volume must live in the same region.

import { Client, Sandbox } from "@deno/sandbox";

const client = new Client();
const volume = await client.volumes.create({
  slug: "dataset",
  region: "ord",
  capacity: "1GB",
});

// First run writes a file to the volume
{
  await using sandbox = await Sandbox.create({
    region: "ord",
    volumes: {
      "/data/dataset": volume.slug,
    },
    labels: { job: "prepare" },
  });

  await sandbox.writeTextFile("/data/dataset/hello.txt", "Persist me!\n");
}

// A new sandbox—possibly started hours later—can read the same file
{
  await using sandbox = await Sandbox.create({
    region: "ord",
    volumes: {
      "/data/dataset": volume.id, // IDs work too
    },
  });

  const contents = await sandbox.readTextFile("/data/dataset/hello.txt");
  console.log(contents); // "Persist me!"
}

Mounts behave like regular directories. You can create subfolders, write binary files, or execute programs directly from the volume.

Delete volumes safely Jump to heading

await client.volumes.delete("training-cache");

Deletion is a two-step process:

  1. The API marks the volume as deleted immediately, which detaches it from new sandbox requests and frees the slug for future reuse.
  2. A background job waits 24 hours before removing the underlying block storage from the cluster. This grace period allows you to contact support if a volume was removed accidentally.

During the grace period you cannot mount or read the volume.

Did you find what you needed?

Edit this page
Privacy policy