File Operations

Manage files within a hosted agent session. All file operations require an active session with a running sandbox.

Overview

Hosted agent sessions provide a persistent filesystem rooted at $HOME (/home/session). Files written to this path survive across requests within the same session. Use the session file tools to upload input data, download outputs, and manage the session filesystem externally.

⚠️ Warning: All file paths are relative to $HOME. For example, filePath: '/data/input.csv' maps to /home/session/data/input.csv inside the container.

MCP Tool Details

Upload File

Use session_file_upload to write a file into the session:

💡 Tip: For text files, encode the content to base64 before passing it. For binary files (images, PDFs), read the raw bytes and base64-encode them.

Download File

Use session_file_download to retrieve a file from the session:

Returns: File content as a base64-encoded string.

List Files

Use session_file_list to browse the session filesystem:

Returns: List of files and directories with metadata.

Delete File

Use session_file_delete to remove a file or directory:

⚠️ Warning: Non-recursive delete on a non-empty directory will fail. Use recursive: true for directories with contents.

Get File Metadata

Use session_file_stat to inspect a file or directory:

Returns: File name, size, whether it is a directory, and last modified time.

Create Directory

Use session_file_mkdir to create directories:

Common Patterns

Upload Input → Invoke → Download Output

1. session_create       → get sessionId
2. session_file_mkdir   → create /data/input/
3. session_file_upload  → upload input files to /data/input/
4. agent_invoke         → tell agent to process /data/input/
5. session_file_list    → check /data/output/ for results
6. session_file_download → retrieve output files
7. session_delete       → clean up when done

Check Agent-Generated Files

1. session_file_list    → browse $HOME to see what the agent created
2. session_file_stat    → check size/type of specific files
3. session_file_download → retrieve files of interest

Storage Limits

• Maximum $HOME size: 10 GiB per session
• Files outside $HOME (e.g., /tmp) are ephemeral and may be cleared between requests

Error Handling