Running Code in Sandboxes

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

Why Sandboxes?

Agents that reason about code need somewhere safe to execute it. Whether generating Python scripts, validating builds, or running user-provided code, you can't let arbitrary execution happen on your infrastructure.

The pattern keeps repeating: spin up a secure environment, run code, tear it down. Without proper isolation, a single bad script could access sensitive data, exhaust resources, or compromise your systems.

Agentuity sandboxes handle this automatically. Every execution runs in an isolated container with its own filesystem, configurable resource limits, and network controls. When execution completes, the environment is destroyed.

What this gives you:

• Security by default: Network disabled, filesystem isolated, resource limits enforced
• No infrastructure management: Containers spin up and tear down automatically
• Multi-language support: Run Python, Node.js, shell scripts, and more
• Consistent environments: Use snapshots to get the same setup every time, with dependencies pre-installed

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:

Testing Runtimes

Pre-configured testing runtimes:

Runtime Metadata

Each runtime includes metadata for identification and resource planning:

View runtime details with agentuity cloud sandbox runtime list --json.

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();
    }
  },
});

Background Jobs

Jobs let you run long-running commands in a sandbox without blocking. Unlike regular execution, jobs:

• Run in parallel: Multiple jobs can execute simultaneously
• Don't block: Control returns immediately after creation
• Persist: Jobs continue even after the creating request completes
• Capture output: Stdout/stderr are captured to streams for later retrieval

Creating Jobs

import { createAgent } from '@agentuity/runtime';
 
const agent = createAgent('BuildRunner', {
  handler: async (ctx, input) => {
    const sandbox = await ctx.sandbox.create({
      resources: { memory: '2Gi' },
      network: { enabled: true },
    });
 
    // Create a background job
    const job = await sandbox.jobCreate({
      command: ['npm', 'run', 'build'],
    });
 
    ctx.logger.info('Build started', { jobId: job.jobId });
 
    // Check status later
    const status = await sandbox.jobGet({ jobId: job.jobId });
    if (status.status === 'completed') {
      ctx.logger.info('Build succeeded', { exitCode: status.exitCode });
    }
 
    return { jobId: job.jobId };
  },
});

Job Lifecycle

Stopping Jobs

// Graceful stop (SIGTERM, then SIGKILL after grace period)
await sandbox.jobStop({ jobId: job.jobId });
 
// Force kill immediately
await sandbox.jobStop({ jobId: job.jobId, force: true });

Use Cases

SDK Access

The API is identical in both contexts.

Configuration Options

Sandbox Events

Every sandbox records lifecycle events as it transitions through states. Use sandboxEventList to retrieve these events for auditing or debugging.

import { sandboxEventList } from '@agentuity/server';
 
const { events } = await sandboxEventList(client, {
  sandboxId: 'sbx_abc123',
  limit: 50,            // optional, default 50
  direction: 'asc',    // optional: 'asc' (oldest first, default) or 'desc'
});

Each event includes:

From the CLI, use agentuity cloud sandbox events <sandbox-id> to list events. See CLI Commands for options.

Auto-Resume on Execute

When you call exec on a suspended sandbox, the sandbox automatically resumes before running the command. The response includes autoResumed: true so you can detect and log this behavior.

const execution = await sandbox.execute({ command: ['bun', 'run', 'test'] });
 
if (execution.autoResumed) {
  ctx.logger.info('Sandbox was resumed automatically before execution');
}

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