> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browser-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

You can upload multiple files at once:

<CodeGroup>
  ```python Python theme={null}
  await client.workspaces.upload(workspace.id, "data.csv", "config.json", "image.png")
  ```

  ```typescript TypeScript theme={null}
  await client.workspaces.upload(workspace.id, "data.csv", "config.json", "image.png");
  ```
</CodeGroup>

## Download files

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
  }
  ```
</CodeGroup>

## Manage workspaces

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

## Organize with prefixes

Use `prefix` to organize files into directories within a workspace:

<CodeGroup>
  ```python Python theme={null}
  # 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/")
  ```

  ```typescript TypeScript theme={null}
  // 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/" });
  ```
</CodeGroup>

## List and delete files

<CodeGroup>
  ```python Python theme={null}
  # 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.used_bytes} bytes")
  ```

  ```typescript TypeScript theme={null}
  // 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");

  // Check workspace storage usage
  const size = await client.workspaces.size(workspace.id);
  console.log(`Used: ${size.usedBytes} bytes`);
  ```
</CodeGroup>

## Cloud dashboard

You can also manage workspaces from [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=workspaces).

<Warning>
  Deleting a workspace permanently removes all its files. This cannot be undone.
</Warning>