Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 160 lines 9.53 KB
Raw
1 ---
2 title: Remote sandbox
3 description: A persistent Python sandbox where your agent writes code, calls tools programmatically, and processes data
4 keywords: [sandbox, remote sandbox, workbench, remote execution, bulk operations, data processing]
5 ---
6
7 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](/docs/how-composio-works). Your agent runs code in it through the `COMPOSIO_REMOTE_WORKBENCH` meta tool, and shell commands through `COMPOSIO_REMOTE_BASH_TOOL`.
8
9 <Callout title="Renamed from workbench">
10 This 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.
11 </Callout>
12
13 <Callout title="Composio doesn't run or replace your agent">
14 Your 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`](#built-in-helpers) 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](/docs/configuring-sessions#disabling-the-sandbox). Sandbox access alone does not use LLM tokens.
15 </Callout>
16
17 ## Where it fits
18
19 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`](/docs/how-composio-works#meta-tools) for straightforward calls. When the task involves bulk operations, data transformations, or multi-step logic, the agent reaches for `COMPOSIO_REMOTE_WORKBENCH` instead.
20
21 <WorkbenchFlow />
22
23 ## What the sandbox provides
24
25 ### Built-in helpers
26
27 These functions are pre-initialized in every sandbox, so your agent can call them without any setup:
28
29 | Helper | What it does |
30 |--------|-------------|
31 | `run_composio_tool` | Execute any Composio tool (e.g., `GMAIL_SEND_EMAIL`, `SLACK_SEND_MESSAGE`) and get structured results |
32 | `invoke_llm` | Call an LLM for classification, summarization, content generation, or data extraction |
33 | `upload_local_file` | Upload generated files (reports, CSVs, images) to cloud storage and get a download URL |
34 | `proxy_execute` | Make direct API calls to connected services when no pre-built tool exists |
35 | `web_search` | Search the web and return results for research or data enrichment |
36 | `smart_file_extract` | Extract text from PDFs, images, and other file formats in the sandbox |
37
38 ### Libraries
39
40 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.
41
42 ### Error correction
43
44 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.
45
46 ### Persistent state
47
48 The sandbox runs as a persistent Jupyter notebook. Variables, imports, files, and in-memory state from one call are available in the next.
49
50 ### Compute tier
51
52 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).
53
54 Available tiers:
55
56 - `standard` (1 vCPU, 1 GB RAM)
57 - `medium` (2 vCPU, 2 GB)
58 - `large` (4 vCPU, 4 GB)
59 - `xlarge` (8 vCPU, 8 GB)
60
61 Larger tiers require `@composio/core` ≥ `0.8.1` or `composio` ≥ `0.12.1`. See [Configuring sessions → Sandbox compute tier](/docs/configuring-sessions#sandbox-compute-tier) for examples.
62
63 <Callout type="info">
64 **Pricing:** Sandboxes are not billed today. Composio plans to begin billing for sandbox usage soon (metered by tier and runtime).
65 </Callout>
66
67 ## Files and mounts
68
69 For a complete upload, analysis, and download workflow, build the [CSV report agent](/examples/csv-report-agent).
70
71 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](#compute-tier) recreates the sandbox and clears in-memory state, but `/mnt/files/` persists.
72
73 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.
74
75 <Callout>
76 The files API ships under `session.experimental`, so the surface may change in a future release.
77 </Callout>
78
79 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
80 <Tab value="Python">
81 ```python
82 session = composio.create(user_id="user_123")
83
84 # Upload a local file; the sandbox sees it at /mnt/files/sales.csv
85 uploaded = session.experimental.files.upload("./sales.csv")
86 print(uploaded.sandbox_mount_prefix, uploaded.mount_relative_path)
87 # /mnt/files sales.csv
88
89 # After the agent writes a result in the sandbox, download it
90 report = session.experimental.files.download("/report.pdf")
91 report.save("./report.pdf")
92 ```
93 </Tab>
94 <Tab value="TypeScript">
95 ```typescript
96 import { Composio } from '@composio/core';
97 const composio = new Composio({ apiKey: 'your_api_key' });
98 // ---cut---
99 const session = await composio.create("user_123");
100
101 // Upload a local file; the sandbox sees it at /mnt/files/sales.csv
102 const uploaded = await session.experimental.files.upload("./sales.csv");
103 console.log(uploaded.sandboxMountPrefix, uploaded.mountRelativePath);
104 // /mnt/files sales.csv
105
106 // After the agent writes a result in the sandbox, download it
107 const report = await session.experimental.files.download("/report.pdf");
108 await report.save("./report.pdf");
109 ```
110 </Tab>
111 <Tab value="API">
112 ```bash
113 SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
114 -H "x-api-key: $COMPOSIO_API_KEY" \
115 -H "Content-Type: application/json" \
116 -d '{"user_id": "user_123"}' | jq -r '.session_id')
117
118 # Upload a local file; the sandbox sees it at /mnt/files/sales.csv
119 UPLOAD_URL=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/mounts/files/upload_url \
120 -H "x-api-key: $COMPOSIO_API_KEY" \
121 -H "Content-Type: application/json" \
122 -d '{"mount_relative_path": "sales.csv", "mimetype": "application/octet-stream"}' | jq -r '.upload_url')
123 curl -X PUT "$UPLOAD_URL" \
124 -H "Content-Type: application/octet-stream" \
125 --data-binary @sales.csv
126
127 # After the agent writes a result in the sandbox, download it
128 DOWNLOAD_URL=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/mounts/files/download_url \
129 -H "x-api-key: $COMPOSIO_API_KEY" \
130 -H "Content-Type: application/json" \
131 -d '{"mount_relative_path": "/report.pdf"}' | jq -r '.download_url')
132 curl -X GET "$DOWNLOAD_URL" -o report.pdf
133 ```
134 </Tab>
135 </Tabs>
136
137 The mount exposes four methods:
138
139 | Method | What it does |
140 |---|---|
141 | `upload(input, options?)` | Upload from a local path, URL, `File`, or buffer. Returns a `RemoteFile`. |
142 | `list(options?)` | List files under `path` on the mount, with `cursor` and `limit` pagination. |
143 | `download(path, options?)` | Fetch a file from the mount as a `RemoteFile`. |
144 | `delete(path, options?)` | Remove a file or directory from the mount. |
145
146 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.
147
148 `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.
149
150 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.
151
152 A `RemoteFile` download through `buffer()`, `blob()`, `text()`, or `save()` stops at 100 MiB, even
153 when the server omits or misreports `Content-Length`. Connection failures and streamed-body failures
154 raise `RemoteFileDownloadError`.
155
156 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`.
157
158 ## Next
159
160 <Card icon={<Terminal />} title="Local sandbox" href="/docs/sandbox/local" description="Run the same tool calls in a sandbox you own, while Composio keeps managed auth and discovery." />