Documentation
Getting started
On this page
j / k move between sections.
Docs / Bring your own storage
Bring your own storage
Connect an S3-compatible bucket or Azure Blob container for Cache and Artifacts. Runners use short-lived object URLs.
Connect your storage
Security boundary
During the trial and on Custom, Cache, Artifacts and Registry can use your own S3-compatible storage. Cache and Artifacts also support Azure Blob Storage. Create a workspace, choose a product, then configure a dedicated bucket or container in its Overview before uploading data. You can also use the product's Storage page. Saving the connection checks access; each product shows its verification status. After the trial, BYOC requires Custom. BoringCache encrypts the storage credential and gives runners short-lived object URLs; runners do not receive the bucket or account key.
Private Cache, Artifact and Registry operations use separate generated prefixes. BoringCache does not create BYOC buckets or containers, change their access policy, or manage provider lifecycle rules. Optional public-file publication uses the exact path you choose outside those private prefixes and requires a separately configured public origin.
Network access and storage allowances
BYOC keeps objects in your storage account; BoringCache still hosts metadata and access control. Both BoringCache servers and your runners need access to the storage endpoint. Servers verify permissions, check objects, complete uploads, and delete expired data. Standard Registry pushes also send image bytes through BoringCache servers.
Storage endpoints must use HTTPS and resolve to public IP addresses. Private-network-only endpoints and a customer-hosted BoringCache control plane are not supported. If your bucket restricts source IPs, contact us to review server and runner access before choosing BYOC.
BYOC Cache, Artifact, and Registry storage has no BoringCache capacity limit. These bytes do not count toward the shared managed allowance or workspace write caps. Data retained in managed storage still counts, even after you connect a BYOC bucket. Request policies, per-upload limits, and retention rules still apply. Your provider bills its storage and transfers.
Amazon S3: use an IAM role
The recommended AWS connection stores only your role ARN. Create an IAM role in your AWS account using the trust policy and external ID shown in workspace settings, attach the generated permissions policy, then paste the role ARN into BoringCache.
BoringCache assumes the role for one hour and uses the resulting temporary credentials to sign storage requests. Presigned runner URLs expire within 45 minutes. The external ID is unique to the workspace and prevents one BoringCache customer from asking the service to assume another customer's role.
Keep the generated policy attached to the role so you retain control of its maximum access. See AWS guidance for third-party access. If the bucket uses a customer-managed KMS key, also grant the role kms:GenerateDataKey and kms:Decrypt on that key.
Azure Blob Storage
Use CLI 1.32.0 or later for Azure block uploads. In Workspace storage settings, select Azure Blob Storage and enter the container, storage account name, and account key. This connection uses Azure's native Blob API.
Use a dedicated storage account with HTTPS required and public blob access disabled. The account key grants access to the full account, even when BoringCache uses only one container. Runners receive short-lived, object-specific SAS URLs. Microsoft Entra ID and user-delegation SAS authentication are not supported by this connection.
For rotation, switch BoringCache to the account's other key and verify access before regenerating the old key. Existing SAS URLs signed by the old key stop working when it is regenerated, so allow active transfers to finish. Follow Microsoft's account-key rotation instructions.
Other S3-compatible providers
Registry requires server-side object copy and SHA-256 checksum support. Its connection check verifies basic storage permissions; verify an image push and pull before using a provider for builds.
The portable connection uses the provider's S3 access ID and secret. Create a separate identity for BoringCache and scope it as narrowly as the provider allows.
| Provider | Recommended identity | Scope |
|---|---|---|
| Google Cloud Storage | Service-account HMAC key | Grant object read, create, list, and delete permissions on this bucket. |
| Cloudflare R2 | R2 API token | Choose Object Read & Write and apply it to this bucket only. |
| MinIO | Service account | Attach the generated S3 policy shown in workspace settings. |
| Wasabi | Dedicated sub-user key | Attach the generated S3 policy shown in workspace settings. |
| Backblaze B2 | Application key | Limit it to this bucket and workspace prefix with list, read, write, and delete capabilities. |
| DigitalOcean Spaces | Limited-access key | Choose this bucket with Read/Write/Delete. Do not combine it with a bucket policy. |
Verify before builds use it
Saving a new or changed connection automatically checks write, read, prefix list, delete, and multipart access. S3-compatible providers use a multipart create/list/abort check. Azure uploads and lists an uncommitted block; Azure handles cleanup because it has no equivalent multipart abort operation. BoringCache saves the connection even when verification fails so you can correct the provider policy without re-entering the setup.
Rotate an access key by entering the replacement pair and saving again. AWS role connections rotate automatically through temporary sessions; update the role's trust or permissions in AWS when you need to revoke access.
Need help or found something unclear? Open an issue or browse the CLI repo.