***

title: File Downloads
description: Handle file downloads from browser runtimes.
---------------------------------------------------------

Browser runtimes can download files triggered by page interactions. Downloaded files are saved to the runtime's workspace storage and can be retrieved via the storage client.

## Enabling downloads

### Playwright

Downloads are accepted by default. You can explicitly control this via context options:

```ts
const runtime = await workspace.runtimes.browser("main").playwright({
  mode: "ephemeral",
  driverOptions: {
    acceptDownloads: true,
  },
});
```

### Puppeteer

Configure download behavior on the browser context:

```ts
const runtime = await workspace.runtimes.browser("main").puppeteer({
  mode: "ephemeral",
  driverOptions: {
    downloadBehavior: {
      policy: "allow",
    },
  },
});
```

| Policy         | Description                                   |
| -------------- | --------------------------------------------- |
| `allow`        | Allow downloads, save to default location     |
| `allowAndName` | Allow downloads with a specific naming scheme |
| `deny`         | Block all downloads                           |
| `default`      | Use browser default behavior                  |

## Triggering a download

Click a download link or button as you normally would:

```ts
// Playwright
await runtime.page.locator("a[href$='.csv']").click();

// Puppeteer
await runtime.page.$eval("a[href$='.csv']", (el) => el.click());
```

Downloaded files are automatically captured and stored in the workspace's storage.

## Retrieving downloads

Use the storage client to access downloaded files:

```ts
const storage = bctrl.storage("my-workspace");

// List downloaded files
const objects = await storage.listObjects({ source: "download" });

// Download a specific file
const data = await storage.downloadObject(objects[0].id);

// Get a download URL
const url = await storage.getObjectDownloadUrl(objects[0].id);

// Download everything as a ZIP
const zip = await storage.getDownloadsZip();
```

## Example: export and retrieve a CSV

```ts
// Navigate to a report page
await runtime.page.goto("https://app.example.com/reports");

// Click the export button
await runtime.page.locator("#export-csv").click();

// Wait for the download to appear in storage
await new Promise((r) => setTimeout(r, 3000));

// Retrieve the file
const storage = bctrl.storage("my-workspace");
const objects = await storage.listObjects({ source: "download" });
const csv = await storage.downloadObject(objects[0].id);
```