COMPOSIO_REMOTE_WORKBENCH meta tool, and shell commands through COMPOSIO_REMOTE_BASH_TOOL.
Renamed from workbenchThis feature used to be called the workbench. The preferred session config key is now
sandbox, but workbench still works as a fully supported alias, in both SDKs and on the wire. It isn’t deprecated, so existing code keeps running unchanged. The COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL meta tools keep their names.Composio doesn’t run or replace your agentYour agent and its model stay entirely yours. Composio never proxies your LLM or runs an agent on your behalf. It discovers, authenticates, and executes tools. The one place Composio itself can call a model is inside the sandbox, when your code opts in through the
invoke_llm helper. That optional sandbox usage is the sole source of Composio-side LLM tokens. Standard sessions enable the sandbox by default, and you can disable it. Sandbox access alone does not use LLM tokens.Where it fits
Use the sandbox when a task is too complex for individual tool calls. Your agent starts withSEARCH_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 accessesresult["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 tostandard (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)
@composio/core ≥ 0.8.1 or composio ≥ 0.12.1. See Configuring sessions → Sandbox compute tier for examples.
Pricing: Sandboxes are not billed today. Composio plans to begin billing for sandbox usage soon (metered by tier and runtime).
Files and mounts
For a complete upload, analysis, and download workflow, build the CSV report agent. 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.
The files API ships under
session.experimental, so the surface may change in a future release.- Python
- TypeScript
- API
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.
save(path) writes exactly where you point it and overwrites whatever is there. Call save() with no path and the file goes to ~/.composio/files/ under its name on the mount — and an existing file there survives: the new copy gets a number before its extension, so a second report.pdf saves as report-1.pdf. The returned path tells you which name was used.
Mount paths come from the sandbox, so the SDK makes that default name safe to write before using it. Characters Windows reserves (:, ?, *, and control characters) become _, over-long names are truncated with their extension kept, and trailing dots and spaces are dropped. Any name these rules changed also carries a short digest of the original, so What is this?.png and What is this*.png don’t land on the same file. A name that can’t be written at all, one containing a NUL byte or with nothing usable left, such as .., raises an error instead of saving.
A RemoteFile download through buffer(), blob(), text(), or save() stops at 100 MiB, even when the server omits or misreports Content-Length. Connection failures and streamed-body failures raise RemoteFileDownloadError.
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.