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

# Bring your own storage (BYOS)

> Configure your own AWS S3 buckets for storing Browserbase artifacts

Bring Your Own Storage (BYOS) allows enterprise customers to store Browserbase artifacts in their own AWS S3 buckets, providing complete control over data residency and compliance.

<Info>
  BYOS is available only on Enterprise plans. [Contact the Browserbase team](https://www.browserbase.com/contact) to enable BYOS for your organization.
</Info>

Artifacts without configured external storage automatically use Browserbase's internal storage.

***

## What gets stored

Browserbase generates several types of artifacts during sessions:

| Artifact Type        | Description                              | Permissions needed | Status      |
| -------------------- | ---------------------------------------- | ------------------ | ----------- |
| **downloads**        | Files downloaded during sessions         | Write only         | Available   |
| **extensions**       | Browser extensions loaded into sessions  | Read only          | Available   |
| **uploads**          | Files uploaded to sessions               | Read/Write         | Available   |
| **contexts**         | Session context files (cookies, storage) | Read/Write         | Available   |
| **recording-videos** | Video recordings of sessions             | Write only         | Coming Soon |
| **logs**             | Console logs and CDP debug output        | Write only         | Coming Soon |

<Note>
  You can configure some or all artifact types for external storage. Unconfigured types will use Browserbase's internal buckets.

  **Session logs** are currently stored in Browserbase's managed infrastructure. BYOS support for logs and recordings is planned for a future release.
</Note>

***

## Setup instructions

### Step 1: Create S3 buckets

Create S3 buckets in your AWS account for the artifact types you want to store externally.

```bash theme={null}
# Create buckets in your desired regions
aws s3 mb s3://company-browserbase-downloads --region us-east-1
aws s3 mb s3://company-browserbase-contexts --region us-west-2

# A single bucket can store multiple artifact types
# They'll be separated by path prefix (downloads/, contexts/, extensions/, uploads/)
aws s3 mb s3://company-browserbase-storage --region us-east-1
```

### Step 2: Generate external ID

Generate a cryptographically random external ID for secure role assumption:

```bash theme={null}
openssl rand -hex 32
```

<Warning>
  Store the External ID securely. You'll need it for both the IAM role configuration and when providing credentials to Browserbase.
</Warning>

### Step 3: Create IAM role

Create an IAM role that Browserbase will assume to access your buckets.

**Trust Policy** (`trust-policy.json`):

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::BROWSERBASE_ACCOUNT_ID:role/svc_byos_accessor"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID_FROM_STEP_2"
        }
      }
    }
  ]
}
```

This follows the [AWS third-party access pattern](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html). The principal is Browserbase's dedicated BYOS accessor role, which is used by all internal services that need to access your buckets.

<Note>
  Contact Browserbase via your account manager or [support@browserbase.com](mailto:support@browserbase.com) for Browserbase's AWS account ID.

  The role name `svc_byos_accessor` is fixed and should not be changed—this is Browserbase's internal service role that assumes your customer role.
</Note>

<CodeGroup>
  ```bash Create Role theme={null}
  aws iam create-role \
    --role-name browserbase-byos-access \
    --assume-role-policy-document file://trust-policy.json
  ```
</CodeGroup>

<Warning>
  **Role name must start with `browserbase-`**. For security, Browserbase can only assume roles matching the pattern `browserbase-*`. Examples: `browserbase-byos-access`, `browserbase-storage`, `browserbase-prod`.
</Warning>

### Step 4: Configure S3 permissions

Attach permissions to your IAM role for bucket access.

**Permissions Policy** (`permissions-policy.json`):

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BrowserbaseReadAccess",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::company-browserbase-extensions",
        "arn:aws:s3:::company-browserbase-extensions/*"
      ]
    },
    {
      "Sid": "BrowserbaseReadWriteUploads",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::company-browserbase-uploads",
        "arn:aws:s3:::company-browserbase-uploads/*"
      ]
    },
    {
      "Sid": "BrowserbaseWriteAccess",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::company-browserbase-downloads",
        "arn:aws:s3:::company-browserbase-downloads/*"
      ]
    },
    {
      "Sid": "BrowserbaseReadWriteAccess",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::company-browserbase-contexts",
        "arn:aws:s3:::company-browserbase-contexts/*"
      ]
    }
  ]
}
```

<Note>
  **Why ListBucket?** This permission on the bucket itself (without `/*`) is required for:

  * Paginating through large numbers of objects efficiently
  * Checking if objects exist before operations
  * Proper error handling when artifacts are missing

  Without it, Browserbase can't determine if a missing artifact is due to permissions or if it truly doesn't exist.
</Note>

<CodeGroup>
  ```bash Attach Policy theme={null}
  aws iam put-role-policy \
    --role-name browserbase-byos-access \
    --policy-name browserbase-s3-access \
    --policy-document file://permissions-policy.json
  ```
</CodeGroup>

### Step 5: Submit configuration

Send this information to your Browserbase account manager or [support@browserbase.com](mailto:support@browserbase.com):

```json theme={null}
{
  "role_arn": "arn:aws:iam::123456789012:role/browserbase-byos-access",
  "external_id": "a1b2c3d4e5f6...",
  "project_ids": ["proj_abc123", "proj_def456"],
  "buckets": [
    {
      "artifact_type": "downloads",
      "bucket_arn": "arn:aws:s3:::company-browserbase-downloads",
      "region": "us-east-1"
    },
    {
      "artifact_type": "contexts",
      "bucket_arn": "arn:aws:s3:::company-browserbase-contexts",
      "region": "us-west-2"
    },
    {
      "artifact_type": "uploads",
      "bucket_arn": "arn:aws:s3:::company-browserbase-uploads",
      "region": "us-east-1"
    },
    {
      "artifact_type": "extensions",
      "bucket_arn": "arn:aws:s3:::company-browserbase-extensions",
      "region": "us-east-1"
    }
  ]
}
```

**Required fields:**

* `role_arn`: The IAM role ARN from Step 3
* `external_id`: The external ID from Step 2
* `project_ids`: Array of project IDs that should use this BYOS configuration
* `buckets`: Array of bucket configurations with artifact\_type, bucket\_arn, and region

***

## Configuration examples

### Minimal setup (downloads only)

```json theme={null}
{
  "role_arn": "arn:aws:iam::123456789012:role/browserbase-byos-access",
  "external_id": "a1b2c3d4...",
  "project_ids": ["proj_abc123"],
  "buckets": [
    {
      "artifact_type": "downloads",
      "bucket_arn": "arn:aws:s3:::company-downloads",
      "region": "us-east-1"
    }
  ]
}
```

### Complete setup (all available artifact types)

```json theme={null}
{
  "role_arn": "arn:aws:iam::123456789012:role/browserbase-byos-access",
  "external_id": "a1b2c3d4...",
  "project_ids": ["proj_abc123", "proj_def456"],
  "buckets": [
    {
      "artifact_type": "downloads",
      "bucket_arn": "arn:aws:s3:::company-downloads",
      "region": "us-east-1"
    },
    {
      "artifact_type": "contexts",
      "bucket_arn": "arn:aws:s3:::company-contexts",
      "region": "us-east-1"
    },
    {
      "artifact_type": "extensions",
      "bucket_arn": "arn:aws:s3:::company-extensions",
      "region": "us-east-1"
    },
    {
      "artifact_type": "uploads",
      "bucket_arn": "arn:aws:s3:::company-uploads",
      "region": "us-east-1"
    }
  ]
}
```

### Multi-region setup

```json theme={null}
{
  "role_arn": "arn:aws:iam::123456789012:role/browserbase-byos-access",
  "external_id": "a1b2c3d4...",
  "project_ids": ["proj_abc123"],
  "buckets": [
    {
      "artifact_type": "downloads",
      "bucket_arn": "arn:aws:s3:::company-downloads-us",
      "region": "us-east-1"
    },
    {
      "artifact_type": "contexts",
      "bucket_arn": "arn:aws:s3:::company-contexts-eu",
      "region": "eu-central-1"
    },
    {
      "artifact_type": "uploads",
      "bucket_arn": "arn:aws:s3:::company-uploads-ap",
      "region": "ap-southeast-1"
    }
  ]
}
```

### Single bucket for all types

```json theme={null}
{
  "role_arn": "arn:aws:iam::123456789012:role/browserbase-byos-access",
  "external_id": "a1b2c3d4...",
  "project_ids": ["proj_abc123", "proj_def456", "proj_ghi789"],
  "buckets": [
    {
      "artifact_type": "downloads",
      "bucket_arn": "arn:aws:s3:::company-browserbase-storage",
      "region": "us-east-1"
    },
    {
      "artifact_type": "contexts",
      "bucket_arn": "arn:aws:s3:::company-browserbase-storage",
      "region": "us-east-1"
    },
    {
      "artifact_type": "extensions",
      "bucket_arn": "arn:aws:s3:::company-browserbase-storage",
      "region": "us-east-1"
    },
    {
      "artifact_type": "uploads",
      "bucket_arn": "arn:aws:s3:::company-browserbase-storage",
      "region": "us-east-1"
    }
  ]
}
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Access denied errors">
    **Check:**

    1. Trust policy principal includes Browserbase's AWS account ID
    2. External ID in trust policy matches what you provided to Browserbase
    3. Role has permissions for specific bucket ARNs
    4. Both bucket-level and object-level permissions are granted

    **Common Fix:**
    Ensure your bucket policy or role policy includes both:

    ```
    arn:aws:s3:::bucket-name       (for ListBucket)
    arn:aws:s3:::bucket-name/*     (for GetObject/PutObject)
    ```
  </Accordion>

  <Accordion title="Wrong region errors">
    **Symptom:** `PermanentRedirect` or "bucket must be accessed via specific endpoint"

    **Fix:**

    * Verify the region in your configuration matches your bucket's actual region
    * S3 buckets are region-specific and must be accessed via the correct endpoint
  </Accordion>

  <Accordion title="Missing artifacts">
    **Check:**

    1. Artifact type is correctly configured
    2. Bucket path structure: `{artifactType}/{sessionId}/{key}`
    3. Write permissions (`s3:PutObject`) are granted
    4. No bucket policies blocking access
  </Accordion>
</AccordionGroup>

***

## FAQs

<AccordionGroup>
  <Accordion title="Can I use different buckets for different projects?">
    Yes, use the `project_ids` field to specify which projects should use a BYOS configuration. You can create multiple configurations with different `project_ids` arrays to route different projects to different buckets.
  </Accordion>

  <Accordion title="Can I use the same bucket for multiple artifact types?">
    Yes, Browserbase separates artifact types using path prefixes (e.g., `downloads/`, `contexts/`, `extensions/`, `uploads/`), so they won't conflict in a shared bucket.
  </Accordion>

  <Accordion title="What happens to existing artifacts when I enable BYOS?">
    Historical artifacts remain in Browserbase's internal storage. Only new artifacts created after BYOS is enabled will be stored in your buckets. Contact support if you need to migrate existing data.
  </Accordion>

  <Accordion title="Do I need to configure all artifact types?">
    No, configure only the types you want to store externally. Unconfigured types automatically use Browserbase's internal storage.
  </Accordion>

  <Accordion title="Can I revoke Browserbase's access?">
    Yes, delete the IAM role or modify the trust policy to remove Browserbase's principal. This immediately prevents access, but active sessions may fail if they can't write artifacts.
  </Accordion>

  <Accordion title="How are artifacts retained?">
    You control retention through S3 lifecycle policies on your buckets. Browserbase doesn't delete artifacts from your external buckets — you manage the full lifecycle.
  </Accordion>

  <Accordion title="What path structure does Browserbase use in my buckets?">
    Browserbase organizes artifacts with this path structure:

    ```
    {artifact_type}/{sessionId}/{key}
    ```

    **Examples:**

    * `downloads/session-abc123/document.pdf`
    * `contexts/session-abc123/cookies.json`
    * `extensions/session-abc123/extension.crx`
    * `uploads/session-abc123/input-file.csv`

    This structure allows you to use the same bucket for multiple artifact types, separated by path prefix.
  </Accordion>

  <Accordion title="What monitoring should I set up?">
    **CloudTrail Logging:**

    * Audit `AssumeRole` calls from Browserbase by AWS account ID
    * Track S3 operations (`GetObject`, `PutObject`)
    * Monitor failed access attempts for security

    **CloudWatch Alarms:**

    * Alert on failed `AssumeRole` attempts
    * Monitor `4xx` error rates on your buckets
    * Track storage growth

    **S3 Lifecycle Policies:**

    * Configure automatic archival to Glacier for cost savings
    * Set expiration rules based on compliance requirements

    **Encryption:**

    ```bash theme={null}
    aws s3api put-bucket-encryption \
      --bucket your-bucket \
      --server-side-encryption-configuration '{
        "Rules": [{
          "ApplyServerSideEncryptionByDefault": {
            "SSEAlgorithm": "AES256"
          }
        }]
      }'
    ```
  </Accordion>
</AccordionGroup>