Bring your own bucket for file system snapshots

This guide shows you how to store File System Snapshots (FSS) in an object storage bucket you own, instead of the CoreWeave-managed default.

CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, CoreWeave Support, or email support@coreweave.com.

By default, CoreWeave provisions and manages an FSS bucket for your organization automatically. You don’t have to do anything. Follow this guide only if you want your sandbox snapshots to land in a bucket you own and control. You set up three things, in order:

An OIDC provider (Workload Identity Federation config) in your CoreWeave organization, so the per-sandbox tokens CoreWeave mints can be exchanged for temporary credentials in your organization.
A bucket policy on your bucket that grants that federated identity the scoped access FSS needs.
The bucket registration with CoreWeave, through a single API call.

Before you start, create the bucket you want to use. This guide does not cover bucket creation. See Create buckets.

How FSS uses your bucket

You never hand CoreWeave a static access key. Instead, every time a sandbox takes or restores a snapshot:

CoreWeave mints a short-lived OIDC JWT for that sandbox. The token is issued by https://oidc.cwsandbox.com, has the audience cw-credential-vendor, and carries claims that identify the organization, the user, the bucket, and the exact object the sandbox is allowed to touch.
Inside the sandbox, the AWS SDK exchanges that token through Workload Identity Federation for temporary S3 credentials scoped to your bucket, and auto-rotates them.
Your bucket policy authorizes that federated identity. It pins access down to a per-user prefix and to your organization only.

The Workload Identity Federation config (Step 1) is what makes your organization trust the CoreWeave token issuer. The bucket policy (Step 2) is what those exchanged credentials are evaluated against. Both are required.

Values you need

Collect these before you begin. The values marked fixed are the same for every customer. The rest are specific to you.

Value	Description	Where it comes from
OIDC issuer	The CoreWeave token issuer URL.	Fixed: `https://oidc.cwsandbox.com`
Audience (`aud`)	The audience CoreWeave stamps on FSS tokens.	Fixed: `cw-credential-vendor`
`[BUCKET-NAME]`	The bucket you created for FSS.	You chose it. See Bucket name rules.
`[REGION]`	The CoreWeave Availability Zone your bucket lives in, used as the S3 region.	All Availability Zones, for example `US-EAST-01A`.
`[ORG-ID]`	Your CoreWeave organization ID, the 6-character ID for the organization that owns the bucket and runs your sandboxes.	Cloud console.
`[CW-TOKEN]`	A CoreWeave API access token for an organization admin. Needs the `SANDBOX_ADMIN` IAM action for Step 3.	Manage API access tokens.

Your organization ID is the same value everywhere it appears in the policy below: in the principal ARN, in each oidc:[ORG-ID]:... condition key, and as the value the org_id condition is matched against.

Step 1: Register the OIDC provider

In the CoreWeave Cloud Console, go to the Workload Identity Federation OIDC page:

https://console.coreweave.com/organization/iam/workload-federation/oidc

Add a new OIDC provider with the following values:

Field	Value
Issuer	`https://oidc.cwsandbox.com`
Audience	`cw-credential-vendor`

This tells your organization to trust the tokens CoreWeave mints for your sandboxes. Without it, the credential exchange described in How FSS uses your bucket fails before any bucket policy is evaluated. For background on how OIDC Workload Identity Federation and the Cloud Console configuration work, see Use Workload Identity Federation with OIDC.

Step 2: Attach the bucket policy

Attach the following policy to your bucket. It is the same policy CoreWeave applies to managed FSS buckets, parameterized with your organization ID. Replace the placeholders:

[BUCKET-NAME] with your bucket name.
[ORG-ID] with your 6-character organization ID, everywhere it appears.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OIDCFederatedScopedAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::[ORG-ID]:role/https://oidc.cwsandbox.com:*"
      },
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts",
        "s3:CreateMultipartUpload",
        "s3:UploadPart",
        "s3:CompleteMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::[BUCKET-NAME]/${oidc:[ORG-ID]:user_hash}/*",
      "Condition": {
        "StringEquals": {
          "oidc:[ORG-ID]:org_id": "[ORG-ID]",
          "oidc:[ORG-ID]:bucket_name": "[BUCKET-NAME]"
        }
      }
    },
    {
      "Sid": "OIDCFederatedRestoreObjectScope",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::[ORG-ID]:role/https://oidc.cwsandbox.com:*"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::[BUCKET-NAME]/${oidc:[ORG-ID]:restore_object_key}",
      "Condition": {
        "StringEquals": {
          "oidc:[ORG-ID]:org_id": "[ORG-ID]",
          "oidc:[ORG-ID]:bucket_name": "[BUCKET-NAME]"
        }
      }
    },
    {
      "Sid": "DenyCrossOrg",
      "Effect": "Deny",
      "Principal": {
        "AWS": "arn:aws:iam::[ORG-ID]:role/https://oidc.cwsandbox.com:*"
      },
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::[BUCKET-NAME]",
        "arn:aws:s3:::[BUCKET-NAME]/*"
      ],
      "Condition": {
        "StringNotEquals": {
          "oidc:[ORG-ID]:org_id": "[ORG-ID]"
        }
      }
    }
  ]
}

What each statement does

OIDCFederatedScopedAccess is the read and write grant for snapshot work. It is scoped to a per-user prefix, ${oidc:[ORG-ID]:user_hash}/*. A given user’s token only resolves to keys under their own hashed prefix, so users in your organization cannot write over each other’s snapshots. The bucket_name condition prevents a token minted for a different bucket from being used here.
OIDCFederatedRestoreObjectScope is a narrow GetObject grant for the exact object a restore is reading, ${oidc:[ORG-ID]:restore_object_key}. This lets one sandbox restore a snapshot another user in your organization created, while the per-user write scoping still holds.
DenyCrossOrg is defense in depth. It denies everything if the token’s org_id claim is not your organization, so even a leaked or misrouted token cannot touch your bucket.

The condition keys use the oidc:[ORG-ID]:[CLAIM] form that CoreWeave AI Object Storage evaluates. CoreWeave fills in the ${oidc:[ORG-ID]:user_hash} and ${oidc:[ORG-ID]:restore_object_key} variables from the sandbox’s token at request time. Do not substitute those. Leave them as written. Only the [ORG-ID] inside them is yours to fill in.

Step 3: Register the bucket with CoreWeave

Tell CoreWeave to use your bucket by setting your organization’s FSS bucket config. This is a single PUT that fully replaces the organization’s config.

curl -X PUT https://api.cwsandbox.com/v1beta2/file-system-snapshots/bucket-config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [CW-TOKEN]" \
  -d '{
    "bucketName": "[BUCKET-NAME]",
    "region": "[REGION]"
  }'

api.cwsandbox.com is the standard sandbox API host, the same one the data plane uses for other calls such as starting a sandbox.
This call requires the SANDBOX_ADMIN IAM action, granted on the Access Policies page. It is admin-gated because changing the bucket affects where every future snapshot lands. See Change or revert your bucket.
Both bucketName and region are required together. Sending one without the other is rejected with CWSANDBOX_INVALID_REQUEST.

A successful response confirms that bring-your-own-bucket mode is in effect:

Example output

{
  "bucketName": "my-fss-bucket",
  "region": "US-EAST-01A",
  "mode": "FILE_SYSTEM_SNAPSHOT_BUCKET_MODE_BRING_YOUR_OWN",
  "effectiveBucketName": "my-fss-bucket"
}

You can read the config back at any time. Any organization member can read it, with no admin role required:

curl https://api.cwsandbox.com/v1beta2/file-system-snapshots/bucket-config \
  -H "Authorization: Bearer [CW-TOKEN]"

Step 4: Verify

Run a snapshot and restore round trip against a real sandbox:

Start a sandbox with a fresh filesystem:

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
  -H "Authorization: Bearer [CW-TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{
    "containerImage": "ubuntu:22.04",
    "command": "sleep",
    "args": ["3600"],
    "fileSystem": { "mountPath": "/work", "size": "10Gi" }
  }'

Write a file under /work, then stop the sandbox and snapshot on stop. The response returns a fileSystemSnapshotId:

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/stop \
  -H "Authorization: Bearer [CW-TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{
    "sandboxId": "[SANDBOX-ID]",
    "fileSystemSnapshotOnStop": true,
    "waitForReady": true,
    "maxTimeoutSeconds": 600
  }'

Restore it into a new sandbox:

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
  -H "Authorization: Bearer [CW-TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{
    "containerImage": "ubuntu:22.04",
    "command": "sleep",
    "args": ["3600"],
    "fileSystem": {
      "mountPath": "/work",
      "size": "10Gi",
      "fileSystemSnapshot": { "fileSystemSnapshotId": "[SNAPSHOT-ID]" }
    }
  }'

If the file you wrote is present in the restored sandbox, your bucket is working. You can also confirm the snapshot landed in your bucket directly: each FileSystemSnapshot returned by GetFileSystemSnapshot and ListFileSystemSnapshots includes an objectBucket field showing which bucket the snapshot was stored in.

Change or revert your bucket

The PUT in Step 3 is a full replace, so it is also how you change or undo your config:

Switch back to CoreWeave-managed: PUT an empty body ({}). CoreWeave resumes managing a bucket for you automatically.
Move to a different bucket: PUT the new bucketName and region.

Read this before you change a bucket. Changing or clearing your FSS bucket abandons access to snapshots stored in the previous bucket. CoreWeave does not copy data between buckets.

Restoring a snapshot whose stored bucket is not your current bucket returns CWSANDBOX_FSS_BUCKET_MISMATCH, which reports the snapshot’s bucket and the current one. The stranded snapshots still appear in list and get calls. They are just not restorable while a different bucket is active.
This is reversible. Point the config back at the old bucket and those snapshots become restorable again.
In-flight sandboxes are unaffected. A running sandbox keeps snapshotting to the bucket it was bound to when it started. A bucket change only affects future sandboxes.

Troubleshooting

Symptom	Likely cause	Fix
`AccessDenied` on snapshot or restore	The bucket policy principal, `org_id` value, or `bucket_name` condition doesn’t match, or the Workload Identity Federation config (Step 1) is missing or has the wrong audience.	Verify the OIDC provider has issuer `https://oidc.cwsandbox.com` and audience `cw-credential-vendor`. Verify `[ORG-ID]` and `[BUCKET-NAME]` in the policy are correct.
`CWSANDBOX_FSS_BUCKET_MISMATCH` on restore	You changed the FSS bucket. The snapshot lives in a different bucket than the current one.	Revert the config to the bucket that holds the snapshot.
`CWSANDBOX_INVALID_REQUEST` on the `PUT`	Partial config (bucket without region or the reverse), or an invalid bucket name.	Send `bucketName` and `region` together. Check the Bucket name rules.
`PermissionDenied` on the `PUT`	The token’s user lacks the `SANDBOX_ADMIN` IAM action.	Grant `SANDBOX_ADMIN` on the Access Policies page.
`PathStyleRequestNotAllowed`	Path-style S3 addressing was used.	CoreWeave AI Object Storage requires virtual-hosted-style addressing.
`CWSANDBOX_FSS_AUTH_FAILED` on snapshot	Credential exchange or bucket authorization failed.	Re-check Step 1 (OIDC provider) and Step 2 (bucket policy). If it persists, contact CoreWeave Support.

If a sandbox runs on a profile with allowlist-only egress, make sure it can reach the CoreWeave credential endpoint (https://api.coreweave.com). Otherwise the credential fetch times out and the first S3 operation fails.

Reference

The following sections describe the bucket name rules, the S3 actions the policy grants, and the token claims the policy references.

Bucket name rules

When you register a bucket in Step 3, CoreWeave validates the name against the standard object storage rules.

Bucket naming rules

Bucket names must be globally unique and adhere to the following rules:

Length: 3 to 63 characters.
Characters: Only lowercase letters (a-z), numbers (0-9), and hyphens (-). No dots, uppercase letters, underscores, spaces, or other special characters.
Start and end: Must begin and end with a letter or number. Cannot start or end with a hyphen (-).
Prohibited patterns: Cannot start with xn--.
Reserved: Must not begin with cw-, vip-, or log-stitcher-ch-. Must not be the exact name int. CoreWeave reserves these for internal use.

The region is a CoreWeave Availability Zone, for example US-EAST-01A, and must match the zone your bucket lives in. For the full list of zones, see All Availability Zones.

S3 actions granted

The policy grants exactly the actions FSS needs and nothing more: s3:GetObject, s3:PutObject, s3:CreateMultipartUpload, s3:UploadPart, s3:CompleteMultipartUpload, s3:AbortMultipartUpload, and s3:ListMultipartUploadParts. Writes use multipart upload, and restore uses GetObject.

Token claims used by the policy

CoreWeave stamps these claims onto each per-sandbox token. The bucket policy conditions reference them as oidc:[ORG-ID]:[CLAIM].

Claim	Used for
`org_id`	Matched against your organization in every `Allow` and in the `DenyCrossOrg` guard.
`user_hash`	The per-user write prefix (`[USER-HASH]/...`).
`bucket_name`	Ties the token to this bucket.
`restore_object_key`	The exact object a restore may read.

File system snapshots: how snapshots, restore, and forking work.
Use Workload Identity Federation with OIDC: how OIDC federation and the Cloud Console configuration work.
Create buckets: create the bucket this guide assumes you already have.
All Availability Zones: the zones to use as your bucket’s region.
Manage API access tokens: create the token used in Step 3.
IAM Access Policies: grant the SANDBOX_ADMIN action required for Step 3.

​How FSS uses your bucket

​Values you need

​Step 1: Register the OIDC provider

​Step 2: Attach the bucket policy

​What each statement does

​Step 3: Register the bucket with CoreWeave

​Step 4: Verify

​Change or revert your bucket

​Troubleshooting

​Reference

​Bucket name rules

​S3 actions granted

​Token claims used by the policy

​Related resources

How FSS uses your bucket

Values you need

Step 1: Register the OIDC provider

Step 2: Attach the bucket policy

What each statement does

Step 3: Register the bucket with CoreWeave

Step 4: Verify

Change or revert your bucket

Troubleshooting

Reference

Bucket name rules

S3 actions granted

Token claims used by the policy

Related resources