Workspaces & files - Browser Use

Workspaces are the recommended way to handle all file operations — uploading input files and downloading results. Prefer workspaces over session-level file uploads. See your workspace IDs at cloud.browser-use.com/settings.

Upload a file

Upload a file to a workspace, then tell the agent to use it.

import httpx
from browser_use_sdk.v3 import AsyncBrowserUse

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

# Get a presigned upload URL
upload = await client.workspaces.upload_files(
    str(workspace.id),
    files=[{"name": "people.csv", "contentType": "text/csv", "size": 45}],
)

# Upload the file
with open("people.csv", "rb") as f:
    async with httpx.AsyncClient() as http:
        await http.put(
            upload.files[0].upload_url,
            content=f.read(),
            headers={"Content-Type": "text/csv", "Content-Length": "45"},
        )

# Tell the agent to use it
result = await client.run(
    "Read people.csv and tell me who works at Google",
    workspace_id=str(workspace.id),
)
print(result.output)

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

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

// Get a presigned upload URL
const upload = await client.workspaces.uploadFiles(workspace.id, {
  files: [{ name: "people.csv", contentType: "text/csv", size: 45 }],
});

// Upload the file
await fetch(upload.files[0].uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "text/csv", "Content-Length": "45" },
  body: readFileSync("people.csv"),
});

// Tell the agent to use it
const result = await client.run(
  "Read people.csv and tell me who works at Google",
  { workspaceId: workspace.id },
);
console.log(result.output);

Download files

Run a task that saves files to a workspace, then download them.

import httpx
from browser_use_sdk.v3 import AsyncBrowserUse

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

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

# List and download files
files = await client.workspaces.files(str(workspace.id), include_urls=True)
for f in files.files:
    print(f"{f.path} ({f.size} bytes)")

    async with httpx.AsyncClient() as http:
        resp = await http.get(f.url)
        with open(f.path, "wb") as out:
            out.write(resp.content)

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

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

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

// List and download files
const files = await client.workspaces.files(workspace.id, { includeUrls: true });
for (const f of files.files) {
  console.log(`${f.path} (${f.size} bytes)`);

  const resp = await fetch(f.url);
  writeFileSync(f.path, Buffer.from(await resp.arrayBuffer()));
}

Manage workspaces

workspace = await client.workspaces.get(workspace_id)
updated = await client.workspaces.update(workspace_id, name="renamed")
workspaces = await client.workspaces.list()
await client.workspaces.delete(workspace_id)

const workspace = await client.workspaces.get(workspaceId);
const updated = await client.workspaces.update(workspaceId, { name: "renamed" });
const workspaces = await client.workspaces.list();
await client.workspaces.delete(workspaceId);

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