Workspaces & files

Upload files for the agent, download files the agent creates.

Workspaces give your agent persistent file storage. Two patterns cover almost every use case:

1. You upload a file → agent reads it
2. Agent creates a file → you download it

Upload a file

Python

from browser_use_sdk.v3 import AsyncBrowserUse

client = AsyncBrowserUse()
workspace = await client.workspaces.create(name="my-workspace")

# Upload
await client.workspaces.upload(workspace.id, "people.csv")

# Agent can now read it
result = await client.run(
    "Read people.csv and tell me who works at Google",
    workspace_id=workspace.id,
)
print(result.output)

import { BrowserUse } from "browser-use-sdk/v3";

const client = new BrowserUse();
const workspace = await client.workspaces.create({ name: "my-workspace" });

// Upload
await client.workspaces.upload(workspace.id, "people.csv");

// Agent can now read it
const result = await client.run(
  "Read people.csv and tell me who works at Google",
  { workspaceId: workspace.id },
);
console.log(result.output);

You can upload multiple files at once:

Python

await client.workspaces.upload(workspace.id, "data.csv", "config.json", "image.png")

await client.workspaces.upload(workspace.id, "data.csv", "config.json", "image.png");

Download files

Python

from browser_use_sdk.v3 import AsyncBrowserUse

client = AsyncBrowserUse()
workspace = await client.workspaces.create(name="my-workspace")

# Agent creates a file
result = await client.run(
    "Go to Hacker News and save the top 3 posts as posts.json",
    workspace_id=workspace.id,
)

# Download a single file
await client.workspaces.download(workspace.id, "posts.json", to="./posts.json")

# Or download everything
paths = await client.workspaces.download_all(workspace.id, to="./output")
for p in paths:
    print(f"Downloaded: {p}")

import { BrowserUse } from "browser-use-sdk/v3";

const client = new BrowserUse();
const workspace = await client.workspaces.create({ name: "my-workspace" });

// Agent creates a file
const result = await client.run(
  "Go to Hacker News and save the top 3 posts as posts.json",
  { workspaceId: workspace.id },
);

// Download a single file
await client.workspaces.download(workspace.id, "posts.json", { to: "./posts.json" });

// Or download everything
const paths = await client.workspaces.downloadAll(workspace.id, { to: "./output" });
for (const p of paths) {
  console.log(`Downloaded: ${p}`);
}

Manage workspaces

Python

workspace = await client.workspaces.get(workspace_id)
updated = await client.workspaces.update(workspace_id, name="renamed")
response = await client.workspaces.list()
for w in response.items:
    print(w.id, w.name)
await client.workspaces.delete(workspace_id)

const workspace = await client.workspaces.get(workspaceId);
const updated = await client.workspaces.update(workspaceId, { name: "renamed" });
const response = await client.workspaces.list();
for (const w of response.items) {
  console.log(w.id, w.name);
}
await client.workspaces.delete(workspaceId);

Organize with prefixes

Use prefix to organize files into directories within a workspace:

Python

# Upload into a subdirectory
await client.workspaces.upload(workspace.id, "report.pdf", prefix="reports/")

# List files in a subdirectory
files = await client.workspaces.files(workspace.id, prefix="reports/")
for f in files.files:
    print(f.path, f.size)

# Download only files from a subdirectory
await client.workspaces.download_all(workspace.id, to="./output", prefix="reports/")

// Upload into a subdirectory
await client.workspaces.upload(workspace.id, "report.pdf", { prefix: "reports/" });

// List files in a subdirectory
const files = await client.workspaces.files(workspace.id, { prefix: "reports/" });
for (const f of files.files) {
  console.log(f.path, f.size);
}

// Download only files from a subdirectory
await client.workspaces.downloadAll(workspace.id, { to: "./output", prefix: "reports/" });

List and delete files

Python

# List all files
files = await client.workspaces.files(workspace.id)
for f in files.files:
    print(f.path, f.size)

# Delete a single file
await client.workspaces.delete_file(workspace.id, path="old-report.pdf")

# Check workspace storage usage
size = await client.workspaces.size(workspace.id)
print(f"Used: {size}")

// List all files
const files = await client.workspaces.files(workspace.id);
for (const f of files.files) {
  console.log(f.path, f.size);
}

// Delete a single file
await client.workspaces.deleteFile(workspace.id, "old-report.pdf");

Manage workspaces

You can also manage workspaces from cloud.browser-use.com/settings.

Deleting a workspace permanently removes all its files. This cannot be undone.