Creating and Using Snapshots

Save sandbox filesystem states and reuse them as bases for new sandboxes

Use snapshots when a sandbox needs the same dependencies or files on many runs. Create the environment once, save it, then start future sandboxes from that snapshot.

import { SandboxClient } from '@agentuity/sandbox';
import { logger } from '@agentuity/telemetry';
 
const client = new SandboxClient();
const sandbox = await client.create({
  runtime: 'bun:1',
  network: { enabled: true },
});
 
try {
  await sandbox.execute({ command: ['bun', 'init', '-y'] });
  await sandbox.execute({ command: ['bun', 'add', 'zod'] });
 
  const snapshot = await client.createSnapshot(sandbox.id, {
    name: 'bun-zod',
    tag: 'bun-zod',
    description: 'Bun project with Zod installed',
  });
 
  logger.info('snapshot created', { snapshotId: snapshot.snapshotId });
} finally {
  await sandbox.destroy();
}

How snapshots work

Snapshots build on top of runtimes. A snapshot captures the runtime layer plus the files and dependencies present in the sandbox workspace.

Create a new sandbox from a snapshot:

import { SandboxClient } from '@agentuity/sandbox';
import { logger } from '@agentuity/telemetry';
 
const client = new SandboxClient();
const sandbox = await client.create({
  snapshot: 'bun-zod',
  resources: { memory: '512Mi' },
});
 
try {
  const execution = await sandbox.execute({
    command: ['bun', 'run', 'index.ts'],
  });
 
  logger.info('snapshot sandbox execution finished', { exitCode: execution.exitCode });
} finally {
  await sandbox.destroy();
}

When snapshot is set, do not also set runtime or runtimeId. The snapshot already includes its base runtime.

Declarative Snapshots

Use a snapshot file when you want the environment definition in version control.

agentuity cloud sandbox snapshot generate > agentuity-snapshot.yaml

The generated file includes commented fields for the runtime, dependencies, packages, included files, environment variables, and metadata. A minimal file looks like this:

version: 1
runtime: bun:1
name: bun-zod
description: Bun project with Zod installed
 
packages:
  - zod
 
files:
  - src/**
  - package.json
  - "!**/*.test.ts"
  - "!node_modules/**"
 
env:
  NODE_ENV: test

Build it from the directory that contains the files you want to include:

agentuity cloud sandbox snapshot build . --tag bun-zod

Common build options:

agentuity cloud sandbox snapshot build ./project --file custom-build.yaml
agentuity cloud sandbox snapshot build . --tag staging
agentuity cloud sandbox snapshot build . --env API_KEY=secret
agentuity cloud sandbox snapshot build . --metadata VERSION=1.0.0
agentuity cloud sandbox snapshot build . --force
# validate the build file without uploading
agentuity cloud sandbox snapshot build . --dry-run

Use --dry-run to validate that the build file is well-formed and all referenced local files can be resolved, without creating a snapshot or uploading anything.

Use --public --confirm only when you intentionally want a public snapshot.

Manual Snapshots

Manual snapshots are useful while you are exploring an environment from the CLI.

agentuity cloud sandbox create --runtime bun:1 --memory 1Gi --network
# Returns: sbx_abc123
 
agentuity cloud sandbox exec sbx_abc123 -- bun init -y
agentuity cloud sandbox exec sbx_abc123 -- bun add zod
 
agentuity cloud sandbox snapshot create sbx_abc123 --name bun-zod --tag bun-zod
agentuity cloud sandbox delete sbx_abc123

You can do the same from code:

import { SandboxClient } from '@agentuity/sandbox';
import { logger } from '@agentuity/telemetry';
 
const client = new SandboxClient();
const sandbox = await client.create({
  runtime: 'bun:1',
  network: { enabled: true },
});
 
try {
  await sandbox.execute({ command: ['bun', 'init', '-y'] });
  await sandbox.execute({ command: ['bun', 'add', 'zod'] });
 
  const snapshot = await client.createSnapshot(sandbox.id, {
    name: 'bun-zod',
    tag: 'bun-zod',
  });
 
  logger.info('snapshot created', { snapshotId: snapshot.snapshotId });
} finally {
  await sandbox.destroy();
}

Managing Snapshots

List and inspect snapshots with SandboxClient:

import { SandboxClient } from '@agentuity/sandbox';
import { logger } from '@agentuity/telemetry';
 
const client = new SandboxClient();
const { snapshots, total } = await client.listSnapshots({
  limit: 20,
  offset: 0,
  sort: 'created',
  direction: 'desc',
});
 
logger.info('snapshot page', { total });
 
for (const snapshot of snapshots) {
  logger.info('snapshot', {
    snapshotId: snapshot.snapshotId,
    name: snapshot.name,
    tag: snapshot.tag ?? '',
  });
}
 
const snapshot = await client.getSnapshot('snp_xyz789');
logger.info('snapshot details', {
  name: snapshot.name,
  sizeBytes: snapshot.sizeBytes,
  fileCount: snapshot.fileCount,
});

Update or remove a tag:

await client.tagSnapshot('snp_xyz789', 'v1.0');
await client.tagSnapshot('snp_xyz789', null);

Delete a snapshot when no workflow depends on it:

await client.deleteSnapshot('snp_xyz789');

From the CLI:

agentuity cloud sandbox snapshot list
agentuity cloud sandbox snapshot list --sandbox sbx_abc123
agentuity cloud sandbox snapshot get snp_xyz789
agentuity cloud sandbox snapshot tag snp_xyz789 v1.0
agentuity cloud sandbox snapshot tag snp_xyz789 --clear
agentuity cloud sandbox snapshot delete snp_xyz789 --confirm

Versioned Environments

Use tags when callers should not need to know snapshot IDs.

agentuity cloud sandbox snapshot create sbx_abc123 --name project-env --tag project-env-v1
agentuity cloud sandbox snapshot create sbx_def456 --name project-env --tag project-env-v2
agentuity cloud sandbox snapshot tag snp_newid latest

Then choose the tag from code:

const sandbox = await client.create({
  snapshot: 'latest',
});

What snapshots include

Snapshots include:

  • files in the sandbox workspace
  • installed dependencies and packages
  • file permissions and directory structure
  • environment variables from a declarative snapshot build file

Snapshots do not include running processes or active network connections. For manual snapshots, pass environment variables again when you create or run the next sandbox.

Snapshots vs Checkpoints

Snapshots are reusable bases for new sandboxes. Checkpoints belong to one sandbox and let you restore that same sandbox to a previous filesystem state.

const checkpoint = await client.createDiskCheckpoint(sandbox.id, 'before-upgrade');
 
await sandbox.execute({ command: ['bun', 'add', 'typescript'] });
await checkpoint.restore();
await checkpoint.delete();

Best Practices

  • Use snapshots for dependencies that are expensive to install repeatedly.
  • Keep snapshot contents small. Include only files and packages needed by the run.
  • Tag snapshots that application code will reference, such as latest, v1.0, or python-data-v2.
  • Delete old snapshots once no active workflow depends on them.

Next Steps