Agentuity Documentation

Skip slow dependency installation on every run by saving sandbox filesystem states as snapshots.

Manage snapshots via the Web App under Services > Sandbox > Snapshots, the SDK, or CLI.

Snapshots Are Not Executable

A snapshot captures the filesystem state of a sandbox at a point in time. You create new sandboxes from snapshots, not run them directly.

How Snapshots Work

Snapshots build on top of runtimes. When you create a snapshot:

Start with a runtime (e.g., bun:1) as the base layer
Add your dependencies (apt packages, npm modules, etc.)
Include your files (source code, config)
The snapshot captures everything: runtime + dependencies + files

When you create a sandbox from a snapshot, it starts with all of this pre-configured.

The Snapshot Workflow

Create a sandbox
Install dependencies and configure the environment
Save a snapshot (captures the filesystem state)
Later, create new sandboxes from that snapshot
New sandboxes start with everything pre-configured

Declarative Snapshots (Recommended)

Define snapshots in a YAML file for reproducible, version-controlled environments. This approach is ideal for CI/CD pipelines and team collaboration.

Quick Start

Generate a template with helpful comments explaining each field:

agentuity cloud sandbox snapshot generate > agentuity-snapshot.yaml

The generated file includes documentation for all options: runtime selection, apt dependencies, file patterns, environment variables, and metadata. Customize it for your needs, then build:

agentuity cloud sandbox snapshot build .

Build File Example

version: 1
runtime: bun:1  # Base runtime - snapshot layers on top of this
description: Node.js environment with common dependencies
 
dependencies:  # Apt packages to install
  - curl
  - jq
 
files:  # Files to include from your project
  - src/**
  - package.json
  - "!**/*.test.ts"    # Exclude test files
  - "!node_modules/**" # Exclude node_modules
 
env:
  NODE_ENV: production

Build Options

# Build with a custom tag
agentuity cloud sandbox snapshot build . --tag production
 
# Build with environment variable substitution
agentuity cloud sandbox snapshot build . --env API_KEY=secret
 
# Force rebuild even if content unchanged
agentuity cloud sandbox snapshot build . --force

When to Use Declarative vs Manual

Approach	Best For
Declarative	CI/CD pipelines, reproducible environments, team collaboration, version control
Manual	Quick experimentation, one-off debugging, exploring new configurations

Creating a Snapshot Manually

Create a sandbox, configure it, then save a snapshot:

# Create a sandbox with a runtime
agentuity cloud sandbox create --runtime bun:1 --memory 1Gi --network
# Returns: sbx_abc123
 
# Install dependencies
agentuity cloud sandbox exec sbx_abc123 -- npm init -y
agentuity cloud sandbox exec sbx_abc123 -- npm install typescript zod
 
# Create snapshot with a tag
agentuity cloud sandbox snapshot create sbx_abc123 --tag node-typescript
 
# Clean up the original sandbox
agentuity cloud sandbox delete sbx_abc123

Using Snapshots in Code

Create sandboxes from snapshots using the snapshot option:

import { createAgent } from '@agentuity/runtime';
 
const agent = createAgent('TypeScriptRunner', {
  handler: async (ctx, input) => {
    // Create sandbox from snapshot - dependencies already installed
    const sandbox = await ctx.sandbox.create({
      snapshot: 'node-typescript',  // Use tag or snapshot ID
      resources: { memory: '512Mi' },
    });
 
    try {
      // Write the user's code
      await sandbox.writeFiles([
        { path: 'index.ts', content: Buffer.from(input.code) },
      ]);
 
      // Run immediately - no npm install needed
      const result = await sandbox.execute({
        command: ['npx', 'tsx', 'index.ts'],
      });
 
      return { success: true, exitCode: result.exitCode };
    } catch (error) {
      ctx.logger.error('Sandbox execution failed', { error });
      return { success: false, exitCode: -1, error: String(error) };
    } finally {
      await sandbox.destroy();
    }
  },
});

CLI Commands

Create Snapshot

agentuity cloud sandbox snapshot create <sandbox-id> [--tag <name>]
 
# Examples
agentuity cloud sandbox snapshot create sbx_abc123
agentuity cloud sandbox snapshot create sbx_abc123 --tag python-ml

List Snapshots

agentuity cloud sandbox snapshot list [--sandbox <id>] [--limit <n>]
 
# Examples
agentuity cloud sandbox snapshot list
agentuity cloud sandbox snapshot list --sandbox sbx_abc123

Get Snapshot Details

agentuity cloud sandbox snapshot get <snapshot-id>
 
# Shows file listing, size, and sandboxes using this snapshot

Tag a Snapshot

agentuity cloud sandbox snapshot tag <snapshot-id> <tag-name>
agentuity cloud sandbox snapshot tag <snapshot-id> --clear
 
# Examples
agentuity cloud sandbox snapshot tag snp_xyz789 v1.0
agentuity cloud sandbox snapshot tag snp_xyz789 latest
agentuity cloud sandbox snapshot tag snp_xyz789 --clear  # Remove tag

Delete Snapshot

agentuity cloud sandbox snapshot delete <snapshot-id> [--confirm]
 
# Example
agentuity cloud sandbox snapshot delete snp_xyz789 --confirm

Create Sandbox from Snapshot

agentuity cloud sandbox create --snapshot <id-or-tag> [options]
 
# Examples
agentuity cloud sandbox create --snapshot node-typescript
agentuity cloud sandbox create --snapshot snp_xyz789 --memory 1Gi

Use Cases

Pre-configured Language Environments

Create snapshots for each language you support:

# Python with common packages
agentuity cloud sandbox create --runtime base:latest --network
agentuity cloud sandbox exec sbx_... -- apt-get update
agentuity cloud sandbox exec sbx_... -- apt-get install -y python3 python3-pip
agentuity cloud sandbox exec sbx_... -- pip install numpy pandas requests
agentuity cloud sandbox snapshot create sbx_... --tag python-data
 
# Node.js with TypeScript
agentuity cloud sandbox create --runtime bun:1 --network
agentuity cloud sandbox exec sbx_... -- npm install -g typescript tsx
agentuity cloud sandbox snapshot create sbx_... --tag node-typescript

Then use in your agent:

const languageSnapshots: Record<string, string> = {
  python: 'python-data',
  typescript: 'node-typescript',
  javascript: 'node-typescript',
};
 
const sandbox = await ctx.sandbox.create({
  snapshot: languageSnapshots[input.language],
});

Version-controlled Environments

Use tags for versioning:

# Create v1.0
agentuity cloud sandbox snapshot create sbx_... --tag project-env-v1.0
 
# Later, create v2.0 with updated dependencies
agentuity cloud sandbox snapshot create sbx_... --tag project-env-v2.0
 
# Keep "latest" pointing to current version
agentuity cloud sandbox snapshot tag snp_newid latest

Faster Cold Starts

Without snapshots, every sandbox creation requires dependency installation:

// Slow: Install dependencies every time
const sandbox = await ctx.sandbox.create({ network: { enabled: true } });
await sandbox.execute({ command: ['npm', 'install'] });  // 30+ seconds
await sandbox.execute({ command: ['npm', 'run', 'build'] });

With snapshots:

// Fast: Dependencies already installed
const sandbox = await ctx.sandbox.create({ snapshot: 'project-deps' });
await sandbox.execute({ command: ['npm', 'run', 'build'] });  // Immediate

Snapshot Data

When you create a snapshot, it captures:

All files in the sandbox workspace
Installed packages and dependencies
File permissions and structure

Snapshots don't include:

Running processes
Network connections
Environment variables (set these when creating the sandbox)

Best Practices

Tag important snapshots: Use descriptive tags like python-ml-v2 instead of relying on IDs
Keep snapshots lean: Only include necessary dependencies to minimize size
Version your snapshots: Use semantic versioning tags for reproducibility
Clean up unused snapshots: Delete snapshots you no longer need

Next Steps

SDK Usage: File I/O, streaming, and advanced configuration options
CLI Commands: Debug sandboxes and manage snapshots from the terminal