Sandbox (prev Workbench)

The sandbox is a persistent Python environment where your agent writes and executes code. It has programmatic access to all Composio tools, plus helper functions for calling LLMs, uploading files, and making API requests. State persists across calls within a session. Your agent runs code in it through the COMPOSIO_REMOTE_WORKBENCH meta tool, and shell commands through COMPOSIO_REMOTE_BASH_TOOL.

Where it fits

Use the sandbox when a task is too complex for individual tool calls. Your agent starts with SEARCH_TOOLS to find the right tools, then uses MULTI_EXECUTE for straightforward calls. When the task involves bulk operations, data transformations, or multi-step logic, the agent reaches for COMPOSIO_REMOTE_WORKBENCH instead.

What the sandbox provides

Built-in helpers

These functions are pre-initialized in every sandbox, so your agent can call them without any setup:

Libraries

The sandbox ships with common packages pre-installed: pandas, numpy, matplotlib, Pillow, PyTorch, and reportlab. Beyond these, the sandbox maintains a list of supported packages and their dependencies. If the agent uses a package that isn't already installed, the sandbox installs it automatically.

Error correction

The sandbox corrects common mistakes in the code your agent generates. For example, if a script accesses result["apiKey"] but the actual field name is api_key, the sandbox resolves the mismatch instead of failing.

Persistent state

The sandbox runs as a persistent Jupyter notebook. Variables, imports, files, and in-memory state from one call are available in the next.

Compute tier

Sandboxes default to standard (1 vCPU, 1 GB RAM). For heavier workloads (large dataframes, ML preprocessing, or big bulk operations), pick a larger tier when creating the session via sandbox.sandboxSize (TypeScript) or sandbox.sandbox_size (Python).

Available tiers:

• standard (1 vCPU, 1 GB RAM)
• medium (2 vCPU, 2 GB)
• large (4 vCPU, 4 GB)
• xlarge (8 vCPU, 8 GB)

Larger tiers require @composio/core ≥ 0.8.1 or composio ≥ 0.12.1. See Configuring sessions → Sandbox compute tier for examples.

Files and mounts

The sandbox has a persistent file mount at /mnt/files/. Code running in the sandbox reads and writes files there, and the mount survives sandbox restarts: changing the compute tier recreates the sandbox and clears in-memory state, but /mnt/files/ persists.

Move files between your app and the mount with session.experimental.files. Upload an input file and the agent reads it at /mnt/files/<path>. When the agent writes a result, download it from your app.

session = composio.create("user_123")

# Upload a local file; the sandbox sees it at /mnt/files/sales.csv
uploaded = session.experimental.files.upload("./sales.csv")
print(uploaded.sandbox_mount_prefix, uploaded.mount_relative_path)
# /mnt/files sales.csv

# After the agent writes a result in the sandbox, download it
report = session.experimental.files.download("/report.pdf")
report.save("./report.pdf")

const session = await composio.create("user_123");

// Upload a local file; the sandbox sees it at /mnt/files/sales.csv
const uploaded = await session.experimental.files.upload("./sales.csv");
console.log(uploaded.sandboxMountPrefix, uploaded.mountRelativePath);
// /mnt/files sales.csv

// After the agent writes a result in the sandbox, download it
const report = await session.experimental.files.download("/report.pdf");
await report.save("./report.pdf");

The mount exposes four methods:

A RemoteFile carries the file's bytes and a presigned downloadUrl. Read it with text() or buffer(), or write it to disk with save(path). Its expiresAt is when that download link expires, not a TTL on the file: the mount itself has no expiry you set.

Every file lives on the session's default files mount, surfaced at /mnt/files/. Each method takes a mountId to address a mount by ID, but there's no SDK call to create custom mounts today, so you'll normally work with files.

Next