Running Code in Sandboxes

Execute code in isolated Linux containers with configurable resource limits, network controls, and execution timeouts.

Three Ways to Use Sandboxes

Key Concepts

These build on each other: Runtime → Sandbox → Snapshot. Here's an example of how to use all three:

1. Pick a runtime (e.g., bun:1 or node:latest)
2. Create a sandbox from that runtime
3. Optionally save a snapshot to reuse your configured environment

Runtimes

Runtimes are pre-configured base environments that Agentuity provides. Each includes an operating system, language toolchain, and common utilities.

Language Runtimes

Use these for general code execution:

Agent Runtimes

Pre-configured AI coding assistants:

Snapshots

A snapshot captures the filesystem state of a sandbox. You create new sandboxes from a snapshot rather than running it directly.

Snapshots build on top of runtimes. When you create a snapshot, it includes everything from the base runtime plus your installed dependencies and files.

Workflow:

1. Create a sandbox from a runtime
2. Install dependencies and configure the environment
3. Save a snapshot
4. Create new sandboxes from that snapshot (fast, no reinstallation needed)

See Creating and Using Snapshots for details.

Two Execution Modes

Choose based on your use case:

One-shot (sandbox.run())

Creates a sandbox, runs a single command, then destroys the sandbox. Best for stateless code execution.

import { createAgent } from '@agentuity/runtime';
 
const agent = createAgent('CodeRunner', {
  handler: async (ctx, input) => {
    const result = await ctx.sandbox.run({
      command: { exec: ['python3', '-c', 'print("Hello!")'] },
      resources: { memory: '256Mi', cpu: '500m' },
    });
 
    ctx.logger.info('Output', { stdout: result.stdout, exitCode: result.exitCode });
    return { output: result.stdout, exitCode: result.exitCode };
  },
});

Interactive (sandbox.create())

Creates a persistent sandbox for multiple commands. Best for stateful workflows like dependency installation.

import { createAgent } from '@agentuity/runtime';
 
const agent = createAgent('ProjectBuilder', {
  handler: async (ctx, input) => {
    const sandbox = await ctx.sandbox.create({
      resources: { memory: '1Gi' },
      network: { enabled: true },  // Required for package installation
    });
 
    try {
      await sandbox.execute({ command: ['npm', 'install'] });
      await sandbox.execute({ command: ['npm', 'run', 'build'] });
      return { success: true };
    } finally {
      await sandbox.destroy();
    }
  },
});

SDK Access

The API is identical in both contexts.

Configuration Options

When to Use Sandbox

Security

Sandboxes provide isolation through:

• Network disabled by default: Enable explicitly when needed
• Resource limits: Prevent resource exhaustion
• Execution timeouts: Prevent runaway processes
• Filesystem isolation: Each sandbox has its own workspace

Next Steps

• SDK Usage: Detailed API for file I/O, streaming, and advanced configuration
• Snapshots: Skip dependency installation with pre-configured environments
• CLI Commands: Debug sandboxes and create snapshots manually