Bring Your Own Storage (BYOS)

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.

BYOS is available only on Enterprise plans. Contact our team to enable BYOS for your organization.

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

What Gets Stored

Browserbase generates and uses 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-images	Screenshots captured during sessions	Write only	Coming Soon
recording-videos	Video recordings of sessions	Write only	Coming Soon
logs	Console logs and CDP debug output	Write only	Coming Soon

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.

Setup Instructions

Step 1: Create S3 Buckets

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

# 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:

openssl rand -hex 32

Store the External ID securely. You’ll need it for both the IAM role configuration and when providing credentials to Browserbase.

Step 3: Create IAM Role

Create an IAM role that Browserbase will assume to access your buckets. Trust Policy (trust-policy.json):

{
  "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. The principal is Browserbase’s dedicated BYOS accessor role, which is used by all internal services that need to access your buckets.

Contact us via your account manager or [email protected] 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.

aws iam create-role \
  --role-name browserbase-byos-access \
  --assume-role-policy-document file://trust-policy.json

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.

Step 4: Configure S3 Permissions

Attach permissions to your IAM role for bucket access. Permissions Policy (permissions-policy.json):

{
  "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/*"
      ]
    }
  ]
}

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 cannot determine if a missing artifact is due to permissions or if it truly doesn’t exist.

aws iam put-role-policy \
  --role-name browserbase-byos-access \
  --policy-name browserbase-s3-access \
  --policy-document file://permissions-policy.json

Step 5: Submit Configuration

Send this information to your Browserbase account manager or [email protected]:

{
  "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)

{
  "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)

{
  "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

{
  "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

{
  "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

Access Denied Errors

Check:

Trust policy principal includes Browserbase’s AWS account ID
External ID in trust policy matches what you provided to Browserbase
Role has permissions for specific bucket ARNs
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)

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

Missing Artifacts

Check:

Artifact type is correctly configured
Bucket path structure: {artifactType}/{sessionId}/{key}
Write permissions (s3:PutObject) are granted
No bucket policies blocking access

FAQs

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.

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.

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.

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.

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 cannot write artifacts.

How are artifacts retained?

You control retention through S3 lifecycle policies on your buckets. Browserbase does not delete artifacts from your external buckets - you manage the full lifecycle.

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.

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:

aws s3api put-bucket-encryption \
  --bucket your-bucket \
  --server-side-encryption-configuration '{
    "Rules": [{
      "ApplyServerSideEncryptionByDefault": {
        "SSEAlgorithm": "AES256"
      }
    }]
  }'

Introduction

Fundamentals

Features

Use Cases

Guides

Integrations

What Gets Stored

Setup Instructions

Step 1: Create S3 Buckets

Step 2: Generate External ID

Step 3: Create IAM Role

Step 4: Configure S3 Permissions

Step 5: Submit Configuration

Configuration Examples

Minimal Setup (Downloads Only)

Complete Setup (All Available Artifact Types)

Multi-Region Setup

Single Bucket for All Types

Troubleshooting

FAQs

Introduction

Fundamentals

Features

Use Cases

Guides

Integrations

​What Gets Stored

​Setup Instructions

​Step 1: Create S3 Buckets

​Step 2: Generate External ID

​Step 3: Create IAM Role

​Step 4: Configure S3 Permissions

​Step 5: Submit Configuration

​Configuration Examples

​Minimal Setup (Downloads Only)

​Complete Setup (All Available Artifact Types)

​Multi-Region Setup

​Single Bucket for All Types

​Troubleshooting

​FAQs

What Gets Stored

Setup Instructions

Step 1: Create S3 Buckets

Step 2: Generate External ID

Step 3: Create IAM Role

Step 4: Configure S3 Permissions

Step 5: Submit Configuration

Configuration Examples

Minimal Setup (Downloads Only)

Complete Setup (All Available Artifact Types)

Multi-Region Setup

Single Bucket for All Types

Troubleshooting

FAQs