aws s3 commands or Boto3 code against your buckets using credentials that expire on their own.
How it works
The sandbox gateway issues each sandbox a JSON Web Token (JWT) from the fixed CoreWeave issuerhttps://oidc.cwsandbox.com. AI Object Storage validates that token against a workload federation configuration in your organization, derives a role identity from the token’s iss and sub claims, and returns temporary credentials scoped by your access policies.
The following configuration must be consistent:
The derived role identity follows the format
role/https://oidc.cwsandbox.com:user:USER_ID, where USER_ID is the CoreWeave user ID of the caller whose API access token started the sandbox. Because the subject varies per user, access policies either list each user’s role or match the whole issuer with a trailing wildcard. See Grant permissions to the sandbox role.
Inside the sandbox, no credential-fetching process of your own is needed. The AWS SDK’s container credentials provider reads the mounted token, calls the CoreWeave credential endpoint, and refreshes the credentials before they expire. OIDC token renewal is a separate gateway operation, described in Token lifetimes.
The organization WIF configuration, sandbox request, and storage policies serve different purposes:
The request fields and token claims don’t replace storage policies. Configure those policies to enforce the S3 actions and resources you intend to allow.
Before you begin
The administrator steps require the following:- A CoreWeave organization with AI Object Storage enabled, and at least one bucket. To create one, see Create a bucket.
- Administrator privileges for your organization: the IAM Admin and Object Storage Admin roles, or equivalent legacy access.
- The
sandbox_adminaction in Identity and Access Management (IAM), which lets you set the sandbox WIF configuration. Grant it on the Access Policies page in the cloud console. - Your CoreWeave organization ID, shown on the Settings page in the cloud console.
- A CoreWeave API access token. Generate one on the Tokens page and copy the Token Secret value. For more information, see Manage API access tokens.
curl examples on this page can read it. Replace API_ACCESS_TOKEN with your CoreWeave API access token:
Step 1: Create an OIDC workload federation config
Register the sandbox issuer with your organization so that AI Object Storage accepts sandbox tokens.- In the cloud console, go to the Workload Federation page.
- Click Create OIDC configuration.
-
Provide the following values:
- Name: a name that identifies this configuration, such as
coreweave-sandboxes. - Issuer URL:
https://oidc.cwsandbox.com. - Client ID (Audience):
https://oidc.cwsandbox.com. - Description (Optional): a description of this configuration.
- Name: a name that identifies this configuration, such as
- Click Create.
Step 2: Grant permissions to the sandbox role
Organization access policies determine what a sandbox can do with the credentials it receives. Two grants are required, and they must be separate statements because the token exchange action is global while the S3 actions are scoped to buckets. The following policy grants the token exchange. Thecwobject:CreateAccessKeyOIDC action operates on all resources, so its statement uses "resources": ["*"]. Replace USER_ID with the CoreWeave user ID whose API access token starts sandboxes:
role/https://oidc.cwsandbox.com:*. Because the issuer portion still has to match exactly, this grant applies only to sandbox tokens, not to other identity providers you federate.
Next, grant the credentials permission to act on buckets. Replace BUCKET_NAME_VALUE with the bucket your sandboxes use:
arn:aws:iam::ORG_ID:role/https://oidc.cwsandbox.com:*. Forwarded OIDC attributes use condition keys named oidc:ORG_ID:CLAIM. See Token claims for the distinction between JWT claims and policy attributes.
Step 3: Configure WIF for your Sandboxes organization
Tell the sandbox gateway which workload federation configuration to mint tokens against, and set the ceiling on what any sandbox in your organization may request. Each organization has one configuration. The gateway’sSettingsService serves this organization configuration at api.cwsandbox.com. For the distinction from managed-runner administration, see Sandboxes architecture. The following v1 PATCH request creates or replaces the complete configuration because it omits updateMask.
Replace WIF_CONFIG_ID with the Config ID from Step 1 and BUCKET_NAME_VALUE with each bucket you want to allow:
Set the sandbox WIF configuration
The organization comes from the authenticated caller, so the request body has no organization field, and callers can only manage their own organization’s configuration.
Confirm the configuration was stored:
Get the sandbox WIF configuration
Delete the sandbox WIF configuration
Step 4: Request object storage access when you start a sandbox
Steps 1 through 3 are one-time administrator setup for the organization. The remaining steps are what a researcher does for each sandbox that needs object storage. Object storage access is opt-in per sandbox. Setspec.objectStorageAccess in the create request, naming the buckets the sandbox needs and the permission level it requires. This example uses serverless placement. For a runner in your own CoreWeave Kubernetes Service (CKS) cluster, use SANDBOX_MODE_CKS instead. Replace CONTAINER_IMAGE with the image to run in the sandbox:
Start a sandbox with object storage access
spec.objectStorageAccess:
A request that exceeds the organization limits is rejected, as is a request made while the organization has no active WIF configuration. These checks govern token issuance. The storage policies determine which S3 operations the resulting credentials can perform.
A sandbox that only reads training data should ask for
OBJECT_STORAGE_PERMISSION_READ even in an organization whose ceiling is read-write.
Optional: Limit access to an object prefix
Prefix-scoped access requires both a prefix in the sandbox request and a bucket policy that enforces it. Setspec.objectStorageAccess.objectPrefix to request a prefix in the sandbox’s OIDC token. The following excerpt shows the spec.objectStorageAccess portion of a create request. Replace BUCKET_NAME_VALUE with the bucket name and OBJECT_PREFIX_VALUE/ with the prefix, including its trailing slash:
- Start with an ASCII letter or number.
- Contain only ASCII letters, numbers, periods, underscores, forward slashes, and hyphens.
- End with
/. - Contain no
..or//sequences. - Be no more than 512 bytes.
object_prefix attribute. A longer prefix can pass sandbox creation but fail credential exchange. An empty or omitted prefix produces no object_prefix claim.
The caller supplies the prefix, but format validation doesn’t determine which prefix that caller is entitled to use. If your application assigns prefixes to users or tenants, derive the prefix from their authenticated identity before you create the sandbox. Don’t let an untrusted user choose another tenant’s prefix.
To enforce the prefix, keep the organization S3 permissions from Step 2. Add the following statements to the bucket’s access policy. Replace BUCKET_NAME_VALUE and ORG_ID with the bucket name and the organization that owns the sandbox identity. Preserve existing statements needed by administrators and other workloads. For instructions, see Set a bucket access policy.
Prefix-scoped read access
prefix starts with that prefix. Both statements require the expected org_id. Neither grants access when object_prefix is absent.
These statements don’t grant write operations. For read-write workloads, request OBJECT_STORAGE_PERMISSION_READ_WRITE and grant the required object actions in both policy layers.
Don’t add a broader Allow for the same sandbox role in the bucket policy: it can grant access outside the prefix. An explicit Deny overrides an Allow. The prefix claim alone doesn’t narrow an unrelated policy statement.
When you use these statements, list within the prefix instead of listing the bucket root. For example, after configuring the client as shown in Step 5, use aws s3 ls s3://BUCKET_NAME_VALUE/OBJECT_PREFIX_VALUE/. With Boto3, supply Prefix='OBJECT_PREFIX_VALUE/' in the list_objects_v2() call. A root listing has no matching prefix and isn’t allowed by these statements.
Step 5: Use the credentials inside the sandbox
When a sandbox starts withspec.objectStorageAccess, CoreWeave mounts its OIDC token and sets the environment variables that AWS SDKs use for container credentials:
The token itself is a read-only file at
/var/run/secrets/sandbox/storage-token/osa-token. You don’t need to read it, and you shouldn’t copy it out of the sandbox or pass it to another workload.
Your client library performs the exchange. Set the region for your buckets, then use any S3-compatible client. Replace AVAILABILITY_ZONE with the Availability Zone your buckets are in, such as US-EAST-04A:
List objects from inside a sandbox
PathStyleRequestNotAllowed.
Boto3 reads the same environment variables, so no explicit credentials are needed. The following example lists objects in a bucket, reading the endpoint and region from the sandbox environment:
list_objects.py
BUCKET_NAME set to the bucket you granted:
Example output
awscli 2.33.2 or later, or boto3 1.42.5 or later. Older versions fail with Unsupported host 'api.coreweave.com'. Build these versions into your sandbox container image.
Token lifetimes
The sandbox lifetime, its object storage OIDC token, and the temporary credentials obtained from that token are separate:- Sandbox lifetime:
maxLifetimeSecondssets the requested maximum runtime. Increasing it doesn’t extend the object storage OIDC token’s lifetime. - Sandbox object storage OIDC token: the sandbox gateway mints it when the sandbox starts. CoreWeave configures its lifetime independently of the sandbox lifetime.
- Temporary AI Object Storage credentials: minted on demand from the OIDC token. The exchange response carries an
Expirationtimestamp, and the AWS SDK refreshes the credentials before that time without any action from your code.
maxLifetimeSeconds doesn’t repair a failed renewal.
WIF configuration changes
The gateway stores the original sandbox grant and checks it against the current organization WIF configuration when it renews the OIDC token:
These changes affect token issuance and claims. They don’t rewrite storage policies or immediately revoke an existing token or temporary credential.
In particular, lowering
maxPermission doesn’t replace a storage policy change that removes write actions. To change which S3 operations are authorized, update the applicable organization and bucket policies. Stopping a sandbox stops its workload, but doesn’t itself revoke a token or credential copied elsewhere.
Token claims
Sandbox object storage tokens carry the following claims. IAM forwards an allowlisted subset of OIDC claims to AI Object Storage as policy attributes. The prefix policy in this guide uses the supportedoidc:ORG_ID:org_id and oidc:ORG_ID:object_prefix attributes. Don’t assume every claim in the JWT is available as a bucket-policy condition key.
Troubleshooting
The following sections describe the failures you are most likely to see when setting up or using sandbox object storage access, and what to check for each one.The start request is rejected
If a create request withspec.objectStorageAccess fails, check the following:
- The organization has a WIF configuration with
enabledset totrue. Retrieve it with the Get request in Step 3. - Every bucket in the request appears in
allowedBuckets, orallowedBucketsis empty. - The requested
permissiondoesn’t exceedmaxPermission. - The request includes at least one bucket and a supported permission value.
- Any
objectPrefixfollows the prefix validation rules. Invalid prefixes produce anInvalidArgumenterror forspec.object_storage_access.object_prefix.
Credential exchange returns permission denied
If the request to the/temporary-credentials/oidc endpoint returns a permission error, credential exchange was refused. Check that:
- An organization access policy grants
cwobject:CreateAccessKeyOIDCon"resources": ["*"]to the sandbox role, in its own statement. - The policy principal matches the derived role exactly, including the
user:prefix on the subject. The principal isrole/https://oidc.cwsandbox.com:user:USER_ID, notrole/https://oidc.cwsandbox.com:USER_ID. - The workload federation configuration in the cloud console is active and its issuer URL is
https://oidc.cwsandbox.com, with no hyphen. - The sandbox OIDC token file exists and its token hasn’t expired. If a running sandbox loses access despite an enabled WIF configuration and correct storage policies, restart it to obtain a new token. If the problem recurs, contact CoreWeave Support with the sandbox ID.
Credential exchange rejects a long prefix
A prefix longer than 128 bytes can pass the gateway’s 512-byte validation limit but fail AI Object Storage’s attribute-length validation. Use a shorterobjectPrefix and create a new sandbox.
Credential exchange succeeds but S3 operations return AccessDenied
If the SDK obtains temporary credentials but an S3 request returnsAccessDenied, check the bucket permissions for those credentials. Confirm that an organization access policy grants the needed s3: actions on the short-form bucket resources (BUCKET_NAME_VALUE and BUCKET_NAME_VALUE/*) to the sandbox role. If a bucket policy exists, it must also allow the operation. Check both policy layers for Deny statements, which override any Allow.
For the prefix policy in this guide, confirm that the object key or listing prefix is within objectPrefix. Listing the bucket root isn’t allowed by that policy.
The credential request times out
Sandboxes governed by a policy with allowlist-only egress must be able to reachhttps://api.coreweave.com. Without that route, the credential fetch times out and the first S3 operation fails. Declare an egress rule for that destination in the sandbox’s network configuration, and permit it in the policy’s allowedEgress envelope.
If the sandbox declares no egress and doesn’t set denyEgress, a matching classless inter-domain routing (CIDR) rule in the policy’s defaultEgress can provide the grant. Hostname rules (httpsHostname) belong in sandbox requests and allowedEgress, and aren’t supported in defaultEgress. An allowedEgress entry alone doesn’t grant connectivity. See Constrain network access.
The workload creates many access keys
Each exchange creates a short-lived access key. Let the SDK’s credential provider cache and refresh the credentials for the lifetime of your process instead of constructing a new client per work item. Minting keys per request generates large volumes of keys for no benefit.Related pages
For related guidance, see the following pages:- Workload Identity Federation for AI Object Storage: how WIF works across CoreWeave.
- Use Workload Identity Federation with OIDC: the general OIDC federation guide, for identity providers other than sandboxes.
- Organization access policies: the policy schema used in Step 2.
- Sandboxes architecture: where the gateway and runner sit in the sandbox request path.