Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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." /> |