Files

Overview

The Files tab gives you visibility into two distinct file systems:

1. Session Files — Live files inside the agent's running sandbox (ephemeral)
2. Stored Files — Persistent files in the agent's permanent storage (survive sleep cycles)

Understanding the difference is essential — session files disappear when the sandbox sleeps, while stored files are always available.

Two-Panel Layout

The Files tab is organized into two side-by-side panels:

Session Files (Left Panel)

These are the files inside the agent's running sandbox — the actual file system of the Linux desktop. They appear only when the sandbox is awake.

• Real-time view — Reflects the current state of the sandbox file system
• Ephemeral — Created during the session and lost when the sandbox sleeps (unless synced)
• Full access — The agent can read, write, move, and delete these files using terminal commands

Session files include everything the agent creates or downloads during its work: scripts, screenshots, downloaded files, temporary data, and output artifacts.

Stored Files (Right Panel)

These are files in the agent's persistent storage — a cloud-based file system that survives sandbox sleep/wake cycles.

• Always available — Accessible whether the sandbox is awake or not
• Persistent — Files remain until explicitly deleted
• Organized — Supports folders for organizing files

Stored files are where you upload resources the agent needs (documents, images, data files) and where important outputs are saved for long-term access.

Uploading Files

Click the Upload button in the Stored Files panel to add files:

1. Select one or more files from your computer
2. Choose a destination folder (or upload to root)
3. Files appear immediately in the stored files panel

Uploaded files are available to the agent via the read_file tool. You can also transfer them into the sandbox for processing.

File Transfer

Move files between the two systems:

Stored → Sandbox (Transfer to Sandbox)

Select a file in stored files and click Transfer to Sandbox to copy it into the running sandbox. The agent can then access it from the Linux file system — useful for processing documents, running scripts on data files, or loading resources.

The agent can also do this itself using the download_to_sandbox tool.

Sandbox → Stored (Sync)

Files in the sandbox can be synced to persistent storage to survive the sleep cycle:

• Manual sync — Click the sync button to copy sandbox files to stored files
• Auto-sync — Important files are synced automatically at key moments (before sleep, after runs)

Folder Management

Stored files support a folder hierarchy:

• Create folder — Click the new folder button to organize your files
• Move files — Drag files into folders
• Delete folder — Remove empty folders (or folders with contents, with confirmation)
• Nested folders — Create subfolders for complex file organizations

File Preview

Click any file to preview it directly — images, text, code, and PDFs are all supported. For other file types, you'll see metadata and a download button.

What Happens When the Agent Sleeps

When the sandbox shuts down:

• Session files → Lost (unless synced to stored files)
• Stored files → Remain untouched
• Skill files → Preserved (skills are stored separately)

When the agent wakes up again, it starts with a fresh sandbox. Stored files can be transferred back in as needed.

Tips & Best Practices

• Sync early and often — Don't wait until the end of a session to sync important files
• Use stored files for inputs — Upload documents, data files, and resources to stored files before the agent processes them
• Use session files for scratch work — Let the agent create temporary files in the sandbox without worrying about storage
• Organize with folders — Create folders by project, date, or file type to keep stored files manageable
• Check before sleeping — Always verify that important outputs have been synced before putting the agent to sleep

What's Next?

• Mail — Set up email communication for your agent
• Queue — Understand the task queue and processing
• Agent Settings — Configure resolution, timeout, and sandbox settings