Skip to main content
Every Asteroid agent has access to a real filesystem. During a run the agent can create files, update them, and execute scripts—just like a developer working on a local machine. This is what makes browser agents on Asteroid so capable: they don’t just click through pages, they can write code, run it, and build on it later. The agent interacts with the filesystem using standard tools — Read, Write, Edit, Glob, Grep, and Bash — with the working directory set to /home/agent.

​
Agents that improve over time

The filesystem has a persistent region called shared/ that survives between executions. Before each run, all previously saved shared files are restored into the sandbox. Anything the agent writes to shared/ during the run is synced back to durable storage when the execution finishes. That means an agent can:
  • Remember how a workflow works — save step-by-step procedures so future runs skip the trial-and-error phase.
  • Record site-specific gotchas — note that a portal requires a specific click order, or that a form silently drops data if submitted too fast.
  • Store and refine scripts — write Playwright scripts during one run, then reuse and improve them on the next (see Scripted mode).
  • Build up knowledge — accumulate extracted data, summaries, or reference files the model can read via file tools.
This is a frontier capability: instead of starting from scratch every time, each execution makes the agent a little smarter. Workflows compound in quality over repeated runs.

​
Directory layout

Each execution mounts a filesystem under /home/agent with four regions:
DirectoryScopeQuotaPurpose
shared/Persists across all executions50 MBDurable memory — scripts, notes, extracted data, learned procedures
workspace/Current execution only500 MBScratch space for in-progress work
downloads/Current execution only500 MBBrowser downloads land here (see Environments)
uploads/Current execution only200 MBFiles attached via API or staging
Rule of thumb: if the agent should remember it next time, put it in shared/. Everything else goes in workspace/.
The agent is automatically notified when new files appear in downloads/ or uploads/ (e.g. browser downloads or API uploads). Changes to shared/ and workspace/ don’t trigger notifications since the agent created those files itself.

Staging Files

Pre-upload files before starting an execution

File Downloads

Automatically download files from websites

File Reading

Read and process images, PDFs, CSVs, and other file types

File Uploads

Upload files to web forms and applications

API Access

Programmatically manage files through the Asteroid Odyssey SDK

​
Staging Files

Use staging files when you need to provide files to an execution before it starts. If your execution is already running, use Upload files to an execution instead.
Staging files is useful when you have files that the agent needs from the very start of execution.

​
How It Works

  1. Stage: Upload files via POST /temp-files/{organizationId} - this returns an array of temp file objects with id and name
  2. Execute: Pass the temp file array in the tempFiles parameter when calling POST /agents/{agentId}/execute
  3. When the execution starts, your staged files are automatically attached to the execution context
Staged files expire after 60 minutes. You must start an execution using the staged files within this time window, or the files will be automatically deleted.

​
Code Examples

import {
  AsteroidClient,
  AgentsV2SDK,
  executeAgent,
} from 'asteroid-odyssey';
import { readFileSync } from 'node:fs';

const client = AsteroidClient(process.env.ASTEROID_API_KEY!);

// Step 1: Stage files before execution
const fileContent = readFileSync('document.pdf');
const file = new File([fileContent], 'document.pdf', { type: 'application/pdf' });

const { data: staged } = await AgentsV2SDK.tempFilesStage({
  client: client.agentsV2Client,
  path: { organizationId: 'YOUR_ORGANIZATION_ID' },
  body: { files: [file] },
});
// staged.tempFiles = [{ id: "uuid", name: "document.pdf" }]

// Step 2: Execute agent with staged files
const executionId = await executeAgent(client, 'YOUR_AGENT_ID', {
  tempFiles: staged?.tempFiles,
  dynamicData: {
    // your variables
  },
});

console.log(`Execution ID: ${executionId}`);

​
File Downloads

Your agents can download files from websites during browser automation sessions. Files land under /home/agent/downloads and sync like other agent directories; use List Files and related tools rather than forcing download.saveAs() into custom paths.
Downloaded files appear in the Files area of the execution UI and in API/SDK file listings.

​
File Reading

Asteroid agents can read and process various file types.

​
Supported File Types

  • Images (PNG, JPEG)
  • PDFs
  • Text Files (TXT, MD)
  • CSVs

​
File Uploads

Agents can upload files to web applications using the Upload File tool, which supports:
  • Local file uploads
  • Previously downloaded files (using downloads/filename format)

​
API Access

File upload and downloads are also available programmatically through the Asteroid Odyssey SDK:

Stage Files Endpoint

Stage files before you start an execution.

Upload Files Endpoint

Upload files to an execution that is already running.

​
Upload Files

import { AsteroidClient, uploadExecutionFiles } from 'asteroid-odyssey';
import { readFileSync } from 'node:fs';

const client = AsteroidClient(process.env.ASTEROID_API_KEY!);

// Upload files to a running execution
const fileContent = readFileSync('document.pdf');
const file = new File([fileContent], 'document.pdf', { type: 'application/pdf' });

await uploadExecutionFiles(client, 'your-execution-id', [file]);

​
Download Files

import { AsteroidClient, getExecutionFiles, downloadExecutionFile } from 'asteroid-odyssey';

const client = AsteroidClient(process.env.ASTEROID_API_KEY!);

// Get list of execution files
const files = await getExecutionFiles(client, 'your-execution-id');

// Download specific files using the signed URL helper
for (const file of files) {
  await downloadExecutionFile(client, file, './downloads/');
  console.log(`Downloaded ${file.fileName} (${file.fileSize} bytes)`);
}