Kache supports AWS S3, Cloudflare R2, Ceph, MinIO, and other compatible endpoints through its S3 backend.

Configure the remote

[cache.remote]
type = "s3"
bucket = "my-build-cache"
region = "eu-west-1"

The region defaults to us-east-1. Set the actual bucket region for AWS.

[cache.remote]
type = "s3"
bucket = "my-build-cache"
region = "eu-west-1"
profile = "build-cache"

[cache.remote]
type = "s3"
bucket = "my-build-cache"
endpoint = "https://<account-id>.r2.cloudflarestorage.com"
region = "auto"

[cache.remote]
type = "s3"
bucket = "build-cache"
endpoint = "https://s3.internal.example.com"
region = "us-east-1"

Credentials

Kache checks these sources in order:

1. KACHE_S3_ACCESS_KEY and KACHE_S3_SECRET_KEY
2. standard AWS credential environment variables
3. the selected shared profile
4. legacy inline SSO or credential_process
5. environment-based web identity
6. ECS/task credentials, then EC2 instance credentials

Both explicit KACHE_S3_* credential variables are required. If only one is present, Kache warns and continues down the standard credential chain.

The configuration fields also have environment overrides:

For a persistent daemon, put remote settings in the config file or service definition. An auto-started daemon does not take per-build remote variables from whichever build happened to start first. kache doctor and kache stats report mismatches between client and daemon configuration.

Compatibility boundaries

The S3 implementation signs with SigV4. It does not currently load SigV4a/Multi-Region Access Point settings, assume-role profiles using source_profile or credential_source, modern [sso-session] profiles, or profile-based web identity. Resolve those credentials before starting Kache or use credential_process.

AWS_ENDPOINT_URL_S3 is accepted when no Kache endpoint is set. An endpoint stored only inside an AWS shared profile is not loaded; copy it to cache.remote.endpoint or KACHE_S3_ENDPOINT.

Prefixes are normalized by trimming surrounding separators and collapsing repeated /. Backslashes and . or .. segments are rejected. A normalized prefix may point at a different object path from an older non-canonical configuration.

Object layout and policy

{prefix}/v3/manifests/{crate}/{key}.json
{prefix}/v3/packs/{crate}/{key}.tar.zst
{prefix}/_manifests/...

The default prefix is artifacts. Writers need s3:GetObject, s3:PutObject, and s3:ListBucket. Read-only clients need GetObject and ListBucket. Prefix-scoped policies must include both v3/ and _manifests/.

Remote packs use zstd; local blobs remain uncompressed. Configure the level with cache.compression_level or KACHE_COMPRESSION_LEVEL.

macOS LAN access

macOS may request Local Network permission when an installed LaunchAgent reaches a LAN endpoint. If only the service gets No route to host, reinstall it with the current binary and check System Settings > Privacy & Security > Local Network.

Verify the result with:

kache doctor
kache daemon status
kache sync --dry-run