Workspaces

Persistent file storage across sessions. Upload input files, download results, and share data across tasks.

What are workspaces?

A workspace is a persistent storage container that lives across sessions. Use workspaces to share files between tasks — upload input data before a task starts, or retrieve output files after it completes.

Every project gets a default “My Files” workspace automatically.

Create a workspace

Python

from browser_use_sdk.v3 import AsyncBrowserUse

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

Manage workspaces

Python

# Get
workspace = await client.workspaces.get(workspace_id)

# Update
updated = await client.workspaces.update(workspace_id, name="renamed")

# List
workspaces = await client.workspaces.list()
for w in workspaces.items:
    print(w.id, w.name)

# Delete
await client.workspaces.delete(workspace_id)

Use a workspace with a task

Pass workspace_id when running a task. The agent can read and write files in the workspace during execution.

Python

from browser_use_sdk.v3 import AsyncBrowserUse

client = AsyncBrowserUse()

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

result = await client.run(
    'Create a file called HEARTBEAT.md with the text "say hello"',
    workspace_id=str(workspace.id),
)
print(result.output)

List and delete files

After a task completes, list files in the workspace or clean up individual files.

Python

# List files
files = await client.workspaces.files(workspace_id, include_urls=True)
for f in files.files:
    print(f.path, f.size)

# Delete a file
await client.workspaces.delete_file(workspace_id, path="HEARTBEAT.md")

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

Workspaces API Reference

Full endpoint reference.

Sessions Guide

Learn about sessions and profiles.