Sandbox - Agentbase Docs

Each agent session runs in its own isolated sandbox environment, providing security, resource isolation, and clean state management.

Overview

The Sandbox primitive is the foundation of Agentbase’s execution model. Every agent session operates within its own isolated sandbox - a lightweight, secure container that provides a clean execution environment. This isolation ensures that:

Security: Agent operations are contained and cannot affect other sessions or the host system
Resource Isolation: Each sandbox has dedicated CPU, memory, and disk resources
Clean State: Every new session starts with a fresh environment
Predictable Execution: Consistent runtime conditions across all sessions

Automatic Creation

Sandboxes are created automatically when you run an agent - no manual setup required

Session-Based

Each sandbox is tied to a session ID and can be reused across multiple requests

Resource Managed

Automatic resource allocation and cleanup based on workload requirements

Network Enabled

Full internet access for API calls, package downloads, and web interactions

How Sandboxes Work

When you make an agent request, Agentbase automatically:

Creates a new isolated sandbox environment (or resumes an existing one)
Provisions the sandbox with necessary runtime tools and capabilities
Executes your agent’s tasks within the isolated environment
Persists the sandbox state for future requests in the same session
Pauses the sandbox after 5 minutes of inactivity to save resources
Cleans up the sandbox automatically when no longer needed

Session Continuity: Use the same session ID to reuse a sandbox and maintain state across multiple agent requests.

Sandbox Architecture

Isolation Layers

Agentbase sandboxes use multiple layers of isolation:

Security Boundaries

Each sandbox provides:

Process Isolation: Separate process namespaces prevent cross-contamination
File System Isolation: Dedicated filesystem with controlled access
Network Isolation: Outbound internet access with security policies
Resource Limits: CPU, memory, and disk quotas to prevent resource exhaustion

Code Examples

Basic Sandbox Usage

import { Agentbase } from '@agentbase/sdk';

const agentbase = new Agentbase({
  apiKey: process.env.AGENTBASE_API_KEY
});

// Sandbox is created automatically
const result = await agentbase.runAgent({
  message: "Create a Python script to analyze data.csv"
});

console.log('Session ID:', result.session);
// Output: Session ID: agent_session_abc123...

from agentbase import Agentbase

agentbase = Agentbase(api_key=os.environ['AGENTBASE_API_KEY'])

# Sandbox is created automatically
result = agentbase.run_agent(
    message="Create a Python script to analyze data.csv"
)

print(f"Session ID: {result.session}")
# Output: Session ID: agent_session_abc123...

curl -X POST https://api.agentbase.sh \
  -H "Authorization: Bearer $AGENTBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a Python script to analyze data.csv"
  }'

# Response includes session ID for sandbox reuse

Reusing a Sandbox

Maintain state across multiple requests by reusing the same session:

// First request - creates sandbox
const result1 = await agentbase.runAgent({
  message: "Install pandas and create a sample CSV file"
});

// Second request - reuses the same sandbox
const result2 = await agentbase.runAgent({
  message: "Now read that CSV file and show the contents",
  session: result1.session
});

// The CSV file and pandas installation persist

# First request - creates sandbox
result1 = agentbase.run_agent(
    message="Install pandas and create a sample CSV file"
)

# Second request - reuses the same sandbox
result2 = agentbase.run_agent(
    message="Now read that CSV file and show the contents",
    session=result1.session
)

# The CSV file and pandas installation persist

Sandbox with Custom Modes

Different modes affect sandbox resource allocation:

// Flash mode - lightweight sandbox
const flash = await agentbase.runAgent({
  message: "Quick calculation: 123 * 456",
  mode: "flash"
});

// Base mode - standard sandbox (default)
const base = await agentbase.runAgent({
  message: "Analyze this data and create a chart",
  mode: "base"
});

// Max mode - enhanced sandbox resources
const max = await agentbase.runAgent({
  message: "Process large dataset and train ML model",
  mode: "max"
});

# Flash mode - lightweight sandbox
flash = agentbase.run_agent(
    message="Quick calculation: 123 * 456",
    mode="flash"
)

# Base mode - standard sandbox (default)
base = agentbase.run_agent(
    message="Analyze this data and create a chart",
    mode="base"
)

# Max mode - enhanced sandbox resources
max = agentbase.run_agent(
    message="Process large dataset and train ML model",
    mode="max"
)

Sandbox Lifecycle

Creation

Sandboxes are created automatically on the first request:

const result = await agentbase.runAgent({
  message: "Hello, create a file called test.txt"
});

// Sandbox created: agent_session_xyz789
// File test.txt exists in sandbox

Persistence

Sandboxes remain active and persist state:

// File from previous request still exists
const result2 = await agentbase.runAgent({
  message: "Read the contents of test.txt",
  session: result.session
});
// Successfully reads the file

Auto-Pause

After 5 minutes of inactivity, sandboxes automatically pause:

Files preserved: All files and data remain intact
Packages preserved: Installed packages stay installed
Resume on next request: Automatic resume when session is reused

Cleanup

Sandboxes are automatically cleaned up after extended inactivity or when explicitly terminated.

Use Cases

1. Development Workflows

Create and test code in an isolated environment:

const dev = await agentbase.runAgent({
  message: "Create a React component with TypeScript, install dependencies, and test it"
});

// Sandbox provides Node.js, npm, and isolated workspace

2. Data Processing

Process sensitive data in isolated environments:

const analysis = await agentbase.runAgent({
  message: "Download this CSV, analyze it, and create visualizations"
});

// Each analysis runs in its own sandbox - no data leakage

3. Multi-Step Tasks

Maintain state across multiple steps:

// Step 1: Setup
const setup = await agentbase.runAgent({
  message: "Install required packages for web scraping"
});

// Step 2: Execute (reuses sandbox)
const scrape = await agentbase.runAgent({
  message: "Now scrape data from these 5 websites",
  session: setup.session
});

// Step 3: Process (reuses sandbox)
const process = await agentbase.runAgent({
  message: "Process the scraped data and create a report",
  session: setup.session
});

4. Testing and Experimentation

Safe environment for testing code:

const test = await agentbase.runAgent({
  message: "Test this algorithm with different inputs and show results"
});

// Sandbox isolation prevents any side effects

Best Practices

Session Management

// Good: Reuse session for related work
const session = result1.session;
const result2 = await agentbase.runAgent({
  message: "Continue from previous step",
  session
});

// Avoid: Creating new sandbox for each step
const result2 = await agentbase.runAgent({
  message: "Continue from previous step"
  // No session ID - creates new sandbox
});

Use New Sessions for Unrelated Tasks

// Good: New session for independent task
const taskA = await agentbase.runAgent({
  message: "Process customer data"
});

const taskB = await agentbase.runAgent({
  message: "Generate marketing report"
  // Different task - don't reuse session
});

Store Session IDs for Long-Running Workflows

// Store session ID in database
await db.workflows.update({
  id: workflowId,
  sessionId: result.session
});

// Resume later
const workflow = await db.workflows.get(workflowId);
const continued = await agentbase.runAgent({
  message: "Continue the workflow",
  session: workflow.sessionId
});

Resource Optimization

Mode Selection: Use flash mode for simple tasks, base for standard workloads, and max only when you need advanced reasoning capabilities. This optimizes both cost and performance.

// Optimize by choosing the right mode
const modes = {
  simple: "flash",    // Quick calculations, simple queries
  standard: "base",   // Most development and analysis tasks
  complex: "max"      // Advanced reasoning, complex workflows
};

const result = await agentbase.runAgent({
  message: "Your task here",
  mode: modes.standard
});

Error Handling

Handle sandbox-related errors gracefully:

try {
  const result = await agentbase.runAgent({
    message: "Process this task",
    session: existingSessionId
  });
} catch (error) {
  if (error.code === 'SANDBOX_NOT_FOUND') {
    // Session expired, start fresh
    const result = await agentbase.runAgent({
      message: "Process this task"
      // Creates new sandbox
    });
  } else {
    throw error;
  }
}

Integration with Other Primitives

With File System

Sandboxes provide the execution environment for file operations:

const result = await agentbase.runAgent({
  message: "Create multiple files and organize them into folders"
});

// Sandbox provides the file system where files are created

Learn more: File System Primitive

With Computer

Sandboxes host the full Linux computer environment:

const result = await agentbase.runAgent({
  message: "Install packages and run shell commands"
});

// Sandbox contains the Linux environment

Learn more: Computer Primitive

With Browser

Browser automation runs within the sandbox:

const result = await agentbase.runAgent({
  message: "Navigate to website and extract data"
});

// Chrome browser runs inside the sandbox

Learn more: Browser Primitive

With Sessions

Sessions manage sandbox lifecycle and persistence:

// Session primitive controls sandbox reuse
const result = await agentbase.runAgent({
  message: "Start a task",
  session: previousSession  // Reuses sandbox
});

Learn more: Sessions Primitive

Performance Considerations

Startup Time

Cold Start: First request creates sandbox (~2-5 seconds overhead)
Warm Start: Subsequent requests in same session are instant
Resume from Pause: Paused sandboxes resume quickly (~1-2 seconds)

// First request - cold start
const start = Date.now();
const result1 = await agentbase.runAgent({
  message: "Hello"
});
console.log(`Cold start: ${Date.now() - start}ms`);

// Second request - warm start
const start2 = Date.now();
const result2 = await agentbase.runAgent({
  message: "Hello again",
  session: result1.session
});
console.log(`Warm start: ${Date.now() - start2}ms`);

Resource Limits

Each sandbox has resource quotas:

CPU: Shared allocation based on mode
Memory: 2GB for flash/base, 4GB for max mode
Disk: 10GB persistent storage per session
Network: Unlimited bandwidth with rate limiting

Optimization Tips

Batch Related Tasks

Group related operations in a single session to minimize sandbox creation overhead

Preload Dependencies

Install packages once and reuse the session for multiple tasks

Clean Up Files

Remove large temporary files to stay within disk limits

Monitor Session Time

Complete work within 5 minutes to avoid auto-pause overhead

Security Features

Isolation Guarantees

Sandboxes provide strong isolation:

No Cross-Session Access: Sandboxes cannot access files or processes from other sessions
Network Security: Outbound connections only, no inbound access
Process Isolation: Separate kernel namespaces for each sandbox
Resource Protection: Quotas prevent resource exhaustion attacks

Data Privacy

// Each user's data is isolated
const userA = await agentbase.runAgent({
  message: "Process confidential data"
});

const userB = await agentbase.runAgent({
  message: "Process different confidential data"
});

// userA and userB run in completely separate sandboxes

Security Best Practices

Sensitive Data: While sandboxes provide isolation, avoid storing long-term sensitive credentials in sandbox files. Use environment variables or secure parameter passing instead.

// Good: Pass credentials securely
const result = await agentbase.runAgent({
  message: "Connect to database using the provided credentials",
  system: `Database credentials: ${secureCredentials}`
});

// Avoid: Writing credentials to files
const result = await agentbase.runAgent({
  message: "Write these credentials to config.json: ..."
});

Troubleshooting

Common Issues

Session Not Found

Problem: Session expired or invalidSolution: Create a new session or verify session ID

// Check if session is valid
const result = await agentbase.runAgent({
  message: "test",
  session: maybeInvalidSession
}).catch(() => {
  // Session invalid, start fresh
  return agentbase.runAgent({
    message: "test"
  });
});

Disk Space Exceeded

Problem: Sandbox reached 10GB storage limitSolution: Clean up large files or start new session

const cleanup = await agentbase.runAgent({
  message: "Delete large temporary files and downloads",
  session: existingSession
});

Slow Performance

Problem: Sandbox running slowSolution: Check mode selection and resource usage

// Use appropriate mode for task complexity
const result = await agentbase.runAgent({
  message: "Simple task",
  mode: "flash"  // Don't use "max" for simple tasks
});

File System

Persistent storage within sandboxes

Computer

Full Linux environment inside sandboxes

Browser

Web automation within sandboxes

Sessions

Session management and persistence

Additional Resources

API Reference

Complete API documentation

Persistence Guide

Understanding state management

Best Practices

Production deployment patterns

Remember: Sandboxes are created automatically and managed transparently. Focus on your agent’s tasks, and Agentbase handles the infrastructure.

​Overview

Automatic Creation

Session-Based

Resource Managed

Network Enabled

​How Sandboxes Work

​Sandbox Architecture

​Isolation Layers

​Security Boundaries

​Code Examples

​Basic Sandbox Usage

​Reusing a Sandbox

​Sandbox with Custom Modes

​Sandbox Lifecycle

​Creation

​Persistence

​Auto-Pause

​Cleanup

​Use Cases

​1. Development Workflows

​2. Data Processing

​3. Multi-Step Tasks

​4. Testing and Experimentation

​Best Practices

​Session Management

​Resource Optimization

​Error Handling

​Integration with Other Primitives

​With File System

​With Computer

​With Browser

​With Sessions

​Performance Considerations

​Startup Time

​Resource Limits

​Optimization Tips

Batch Related Tasks

Preload Dependencies

Clean Up Files

Monitor Session Time

​Security Features

​Isolation Guarantees

​Data Privacy

​Security Best Practices

​Troubleshooting

​Common Issues

​Related Primitives

File System

Computer

Browser

Sessions

​Additional Resources

API Reference

Persistence Guide

Best Practices

Overview

How Sandboxes Work

Sandbox Architecture

Isolation Layers

Security Boundaries

Code Examples

Basic Sandbox Usage

Reusing a Sandbox

Sandbox with Custom Modes

Sandbox Lifecycle

Creation

Persistence

Auto-Pause

Cleanup

Use Cases

1. Development Workflows

2. Data Processing

3. Multi-Step Tasks

4. Testing and Experimentation

Best Practices

Session Management

Resource Optimization

Error Handling

Integration with Other Primitives

With File System

With Computer

With Browser

With Sessions

Performance Considerations

Startup Time

Resource Limits

Optimization Tips

Security Features

Isolation Guarantees

Data Privacy

Security Best Practices

Troubleshooting

Common Issues

Related Primitives

Additional Resources