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 | # Tool Router Session Files |
| 2 | |
| 3 | Tool Router sessions include a virtual filesystem mount that enables file storage and retrieval within a session. This is useful for agent workflows, document processing, and tools that need to read or write files. Access the files API via `session.experimental.files` on any Tool Router session. |
| 4 | |
| 5 | > **Related:** |
| 6 | > - [Tool Router](./tool-router.md) – Session creation, configuration, and `session.experimental.files` overview |
| 7 | > - [Auto Upload and Download](../advanced/auto-upload-download.md) – File handling during tool execution (different feature) |
| 8 | |
| 9 | ## Overview |
| 10 | |
| 11 | Each Tool Router session has a `files` property that provides: |
| 12 | |
| 13 | - **List** – Browse files and directories with cursor-based pagination |
| 14 | - **Upload** – Upload files from paths, URLs, native `File` objects, or raw buffers |
| 15 | - **Download** – Get presigned download URLs and `RemoteFile` instances |
| 16 | - **Delete** – Remove files or directories from the mount |
| 17 | |
| 18 | Files are stored in a virtual filesystem attached to the session. Tools executing in the session can access these files (e.g., at `/mnt/files/` inside the sandbox). The mount ID defaults to `"files"` and can be overridden when using custom mounts. |
| 19 | |
| 20 | ## Quick Start |
| 21 | |
| 22 | ```typescript |
| 23 | import { Composio } from '@composio/core'; |
| 24 | |
| 25 | const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY }); |
| 26 | const session = await composio.create('default'); |
| 27 | |
| 28 | // Upload a file |
| 29 | const file = await session.experimental.files.upload('/path/to/report.pdf'); |
| 30 | console.log('Uploaded:', file.mountRelativePath); |
| 31 | |
| 32 | // List files |
| 33 | const { items, nextCursor } = await session.experimental.files.list({ path: '/' }); |
| 34 | |
| 35 | // Download a file |
| 36 | const remoteFile = await session.experimental.files.download('report.pdf'); |
| 37 | const buffer = await remoteFile.buffer(); |
| 38 | await remoteFile.save('/tmp/report.pdf'); |
| 39 | ``` |
| 40 | |
| 41 | ## List Files |
| 42 | |
| 43 | List files and directories at a path on the session's file mount. Supports cursor-based pagination. |
| 44 | |
| 45 | ### Method Signature |
| 46 | |
| 47 | ```typescript |
| 48 | session.experimental.files.list(options?: ToolRouterSessionFilesMountListOptions): Promise<FileListResponse> |
| 49 | ``` |
| 50 | |
| 51 | ### Options |
| 52 | |
| 53 | | Option | Type | Default | Description | |
| 54 | | -------- | ------ | ------- | ---------------------------------------------------------- | |
| 55 | | `path` | string | - | Directory path to list. Use `"/"` for root. | |
| 56 | | `mountId`| string | `"files"` | The file mount ID. | |
| 57 | | `cursor` | string | - | Pagination cursor from the previous response's `nextCursor`. | |
| 58 | | `limit` | number | - | Max files per page (1–500). | |
| 59 | |
| 60 | ### Response |
| 61 | |
| 62 | ```typescript |
| 63 | interface FileListResponse { |
| 64 | items: Array<{ |
| 65 | lastModified: string; // ISO 8601 timestamp |
| 66 | mountRelativePath: string; // e.g. "report.pdf" |
| 67 | sandboxMountPrefix: string; // e.g. "/mnt/files" |
| 68 | size: number; // File size in bytes |
| 69 | }>; |
| 70 | nextCursor?: string; // Present when more pages exist |
| 71 | } |
| 72 | ``` |
| 73 | |
| 74 | ### Examples |
| 75 | |
| 76 | ```typescript |
| 77 | // List root directory |
| 78 | const { items } = await session.experimental.files.list({ path: '/' }); |
| 79 | |
| 80 | // List a subdirectory |
| 81 | const { items } = await session.experimental.files.list({ path: '/documents' }); |
| 82 | |
| 83 | // Paginated listing |
| 84 | let result = await session.experimental.files.list({ path: '/', limit: 10 }); |
| 85 | while (result.nextCursor) { |
| 86 | result = await session.experimental.files.list({ |
| 87 | path: '/', |
| 88 | cursor: result.nextCursor, |
| 89 | limit: 10, |
| 90 | }); |
| 91 | } |
| 92 | ``` |
| 93 | |
| 94 | ## Upload Files |
| 95 | |
| 96 | Upload files to the session's mount. Accepts multiple input types: file paths (local or URL), native `File` objects, or raw buffers (`ArrayBuffer` | `Uint8Array`). |
| 97 | |
| 98 | ### Method Signature |
| 99 | |
| 100 | ```typescript |
| 101 | session.experimental.files.upload( |
| 102 | input: string | File | ArrayBuffer | Uint8Array, |
| 103 | options?: ToolRouterSessionFilesMountUploadOptions |
| 104 | ): Promise<RemoteFile> |
| 105 | ``` |
| 106 | |
| 107 | ### Input Types |
| 108 | |
| 109 | | Input Type | Description | Example | |
| 110 | | ---------- | ----------- | ------- | |
| 111 | | `string` | Local path or HTTP(S) URL | `'/path/to/file.pdf'`, `'https://example.com/file.pdf'` | |
| 112 | | `File` | Native browser/Node `File` | `inputElement.files[0]` | |
| 113 | | `ArrayBuffer` | Raw binary buffer | `await file.arrayBuffer()` | |
| 114 | | `Uint8Array` | Typed array buffer | `new TextEncoder().encode('hello')` | |
| 115 | |
| 116 | ### Upload Options |
| 117 | |
| 118 | | Option | Type | Default | Description | |
| 119 | | --------- | ------ | ------- | ----------- | |
| 120 | | `remotePath` | string | - | Remote path/filename on the mount. Required when passing a buffer (provides filename; mimetype defaults to `application/octet-stream`). | |
| 121 | | `mountId` | string | `"files"` | The file mount ID. | |
| 122 | | `mimetype` | string | - | MIME type. Required when passing a buffer unless `remotePath` is provided. Ignored when passing `File` (uses `file.type`). | |
| 123 | |
| 124 | ### How It Works |
| 125 | |
| 126 | 1. **Path (string)** – If the path starts with `http://` or `https://`, the file is fetched from the URL. Otherwise it is read from the local filesystem. The filename is derived from the path or URL. |
| 127 | 2. **File** – Used directly. Filename comes from `file.name` unless `remotePath` is provided. |
| 128 | 3. **Buffer** – Wrapped in a `File` object. **Either `mimetype` or `remotePath` must be provided.** If only `remotePath` is given, mimetype defaults to `application/octet-stream`. If only `mimetype` is given, a filename is generated from the extension (`upload-{id}.{ext}`). |
| 129 | |
| 130 | ### Examples |
| 131 | |
| 132 | ```typescript |
| 133 | // From local path |
| 134 | const file = await session.experimental.files.upload('/path/to/report.pdf'); |
| 135 | |
| 136 | // From URL |
| 137 | const file = await session.experimental.files.upload('https://example.com/document.pdf'); |
| 138 | |
| 139 | // From native File (e.g. file input) |
| 140 | const file = await session.experimental.files.upload(fileInput.files[0]); |
| 141 | |
| 142 | // From buffer with explicit path and mimetype |
| 143 | const buffer = new TextEncoder().encode('{"key": "value"}'); |
| 144 | const file = await session.experimental.files.upload(buffer, { |
| 145 | remotePath: 'data.json', |
| 146 | mimetype: 'application/json', |
| 147 | }); |
| 148 | |
| 149 | // From buffer – mimetype or remotePath required |
| 150 | const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, ...]); |
| 151 | const file = await session.experimental.files.upload(pngBytes, { |
| 152 | remotePath: 'screenshot.png', |
| 153 | mimetype: 'image/png', |
| 154 | }); |
| 155 | ``` |
| 156 | |
| 157 | ## Download Files |
| 158 | |
| 159 | Get a `RemoteFile` for a file on the mount. The `RemoteFile` provides a presigned download URL and methods to fetch content. |
| 160 | |
| 161 | ### Method Signature |
| 162 | |
| 163 | ```typescript |
| 164 | session.experimental.files.download( |
| 165 | filePath: string, |
| 166 | options?: ToolRouterSessionFilesMountDownloadOptions |
| 167 | ): Promise<RemoteFile> |
| 168 | ``` |
| 169 | |
| 170 | ### Parameters |
| 171 | |
| 172 | - `filePath` – Path of the file on the mount (e.g. `"report.pdf"`, `"output/data.csv"`). |
| 173 | - `options.mountId` – Mount ID (default: `"files"`). |
| 174 | |
| 175 | ### RemoteFile |
| 176 | |
| 177 | The returned `RemoteFile` has: |
| 178 | |
| 179 | | Property | Type | Description | |
| 180 | | -------- | ---- | ----------- | |
| 181 | | `expiresAt` | string | ISO 8601 when the download URL expires | |
| 182 | | `mountRelativePath` | string | Path within the mount | |
| 183 | | `sandboxMountPrefix` | string | Absolute mount path (e.g. `/mnt/files`) | |
| 184 | | `downloadUrl` | string | Presigned URL for downloading | |
| 185 | | `filename` | string | Basename of the path | |
| 186 | |
| 187 | Methods: |
| 188 | |
| 189 | - `buffer()` – Fetch content as `Uint8Array` |
| 190 | - `text()` – Fetch content as UTF-8 string |
| 191 | - `blob()` – Fetch content as `Blob` |
| 192 | - `save(path?)` – Download and save to disk (Node.js only; path defaults to `~/.composio/files/`) |
| 193 | |
| 194 | ### Examples |
| 195 | |
| 196 | ```typescript |
| 197 | const remoteFile = await session.experimental.files.download('/output/report.pdf'); |
| 198 | |
| 199 | // Fetch content |
| 200 | const buffer = await remoteFile.buffer(); |
| 201 | const text = await remoteFile.text(); |
| 202 | |
| 203 | // Save to disk (Node.js) |
| 204 | await remoteFile.save('/tmp/report.pdf'); |
| 205 | await remoteFile.save(); // Uses ~/.composio/files/{filename} |
| 206 | ``` |
| 207 | |
| 208 | ## Delete Files |
| 209 | |
| 210 | Delete a file or directory from the mount. |
| 211 | |
| 212 | ### Method Signature |
| 213 | |
| 214 | ```typescript |
| 215 | session.experimental.files.delete( |
| 216 | remotePath: string, |
| 217 | options?: ToolRouterSessionFilesMountDeleteOptions |
| 218 | ): Promise<FileDeleteResponse> |
| 219 | ``` |
| 220 | |
| 221 | ### Examples |
| 222 | |
| 223 | ```typescript |
| 224 | await session.experimental.files.delete('/temp/cache.json'); |
| 225 | await session.experimental.files.delete('/old-backup', { mountId: 'custom-mount' }); |
| 226 | ``` |
| 227 | |
| 228 | ## Type Reference |
| 229 | |
| 230 | ### ToolRouterSessionFilesMountListOptions |
| 231 | |
| 232 | ```typescript |
| 233 | interface ToolRouterSessionFilesMountListOptions { |
| 234 | path?: string; |
| 235 | mountId?: string; // default: "files" |
| 236 | cursor?: string; |
| 237 | limit?: number; // 1-500 |
| 238 | } |
| 239 | ``` |
| 240 | |
| 241 | ### ToolRouterSessionFilesMountUploadOptions |
| 242 | |
| 243 | ```typescript |
| 244 | interface ToolRouterSessionFilesMountUploadOptions { |
| 245 | remotePath?: string; |
| 246 | mountId?: string; // default: "files" |
| 247 | mimetype?: string; |
| 248 | } |
| 249 | ``` |
| 250 | |
| 251 | ### FileListResponse |
| 252 | |
| 253 | ```typescript |
| 254 | interface FileListResponse { |
| 255 | items: Array<{ |
| 256 | lastModified: string; |
| 257 | mountRelativePath: string; |
| 258 | sandboxMountPrefix: string; |
| 259 | size: number; |
| 260 | }>; |
| 261 | nextCursor?: string; |
| 262 | } |
| 263 | ``` |
| 264 | |
| 265 | ### RemoteFile (from download/upload) |
| 266 | |
| 267 | ```typescript |
| 268 | interface RemoteFile { |
| 269 | readonly expiresAt: string; |
| 270 | readonly mountRelativePath: string; |
| 271 | readonly sandboxMountPrefix: string; |
| 272 | readonly downloadUrl: string; |
| 273 | readonly filename: string; |
| 274 | |
| 275 | buffer(): Promise<Uint8Array>; |
| 276 | text(): Promise<string>; |
| 277 | blob(): Promise<Blob>; |
| 278 | save(path?: string): Promise<string>; // Node.js only |
| 279 | } |
| 280 | ``` |
| 281 | |
| 282 | ## Exports |
| 283 | |
| 284 | The following are exported from `@composio/core`: |
| 285 | |
| 286 | - `FileListResponse` – List response type |
| 287 | - `ToolRouterSessionFilesMountListOptions` – List options type |
| 288 | - `RemoteFile` – File class with `buffer`, `text`, `blob`, `save` |
| 289 | - `getExtensionFromMimeType` – Map MIME type to file extension |
| 290 | |
| 291 | ## Platform Support |
| 292 | |
| 293 | - **Node.js** – Full support (paths, `save()`). |
| 294 | - **Bun** – Full support. |
| 295 | - **Browser** – Paths and `save()` are limited; use `File` or buffers. |
| 296 | - **Cloudflare Workers / Edge** – No filesystem; use `File` or buffers only. |