# Build caches

Groundbox is a remote build cache for 5 build tools: Turborepo, Gradle, sccache, Bazel and Nx. A task one build ran is not run again by the next one that has the same inputs, whether that build is a CI job, a sandbox, a laptop or an agent. One store per team, kept on the same machines as your runners.

## On Groundbox runners: nothing to set

Every job on a Groundbox runner already points these tools at the cache on its machine, with no key:

- **Turborepo:** `TURBO_API`, `TURBO_TEAM` and `TURBO_TOKEN` are set. `turbo run` uses it.
- **sccache:** `SCCACHE_BUCKET`, `SCCACHE_ENDPOINT` and the rest of its S3 settings are set. Set `RUSTC_WRAPPER=sccache` as usual.
- **Gradle:** an init script makes the box the remote cache of any build that turns the build cache on and names no remote cache of its own. Turn it on in `gradle.properties`:

gradle.properties

```
org.gradle.caching=true
```

- **Bazel:** `/etc/bazel.bazelrc` sets `--remote_cache`. Your project's `.bazelrc` comes after it and wins.
- **Nx:** not on by default, since a workspace on Nx Cloud would change caches. One step turns it on:

.github/workflows/ci.yml

```
- name: Nx remote cache on the box
  run: echo "NX_SELF_HOSTED_REMOTE_CACHE_SERVER=$GROUNDBOX_NX_CACHE_URL" >> "$GITHUB_ENV"
```

Your workflow's own env wins over any of these: set `TURBO_API` to keep another remote cache, or `GROUNDBOX_GRADLE_CACHE=off` for Gradle.

## In sandboxes: off until you turn it on

A sandbox does not use the cache unless it asks, so a build in it runs in full and never restores another sandbox's or a CI job's results. Set `GROUNDBOX_BUILD_CACHE=on` in the sandbox's env, or in its template's, and its commands get the same Turborepo and sccache settings as a runner, the Gradle init script, and `GROUNDBOX_BAZEL_CACHE_URL` and `GROUNDBOX_NX_CACHE_URL` for Bazel's `--remote_cache` and Nx. The sandbox's own env wins over them.

```
groundbox sandbox create --env GROUNDBOX_BUILD_CACHE=on
```

## From laptops and other CI

Use `https://api.groundbox.dev/build-cache` with an API key from [API keys](https://app.groundbox.dev/keys) that has `cache:read`, and `cache:write` to save.

### Turborepo

```
export TURBO_API=https://api.groundbox.dev/build-cache
export TURBO_TEAM=groundbox
export TURBO_TOKEN=gbx_...   # a key with cache:read (cache:write to save)
turbo run build
```

### Gradle

settings.gradle.kts

```
// settings.gradle.kts: the box's cache on Groundbox runners, api.groundbox.dev/build-cache anywhere else
buildCache {
    remote<HttpBuildCache> {
        val onBox = System.getenv("GROUNDBOX_GRADLE_CACHE_URL")
        url = uri(onBox ?: "https://api.groundbox.dev/build-cache/gradle/")
        isPush = true
        if (onBox == null) {
            credentials {
                username = "groundbox"
                password = System.getenv("GROUNDBOX_CACHE_KEY")
            }
        } else {
            isAllowInsecureProtocol = true
        }
    }
}
```

Put the key in `GROUNDBOX_CACHE_KEY`. Keep `org.gradle.caching=true` in `gradle.properties`.

### sccache

```
export RUSTC_WRAPPER=sccache
export SCCACHE_BUCKET=groundbox
export SCCACHE_ENDPOINT=https://api.groundbox.dev/build-cache/s3
export SCCACHE_REGION=auto
export AWS_ACCESS_KEY_ID=gbx_...        # the key goes here; the signature is not checked
export AWS_SECRET_ACCESS_KEY=unused
```

### Bazel

```
# user.bazelrc or ~/.bazelrc (not committed: it holds the key)
build --remote_cache=https://api.groundbox.dev/build-cache/bazel
build --remote_header=Authorization=Bearer gbx_...
```

### Nx

```
export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=https://api.groundbox.dev/build-cache/nx
export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=gbx_...
```

## Who can save what

- Builds of a repository's default branch, and API keys with cache:write, save to your team's shared cache. Everyone in the team restores from it.
- Pull requests and other branches save to a cache of their own, and restore from it, then the shared one. Code in a pull request can never put an entry where a default-branch build will restore it.
- To let pull requests from your own repositories save to the shared cache, turn it on in [settings](https://app.groundbox.dev/settings). A pull request from a fork never does.
- Sandboxes that turn the cache on save to a sandbox cache and restore from it, then the shared one. Other sandboxes neither save nor restore.
- Caches are never shared between teams.

## Limits

A team keeps 5 GB on the free plan and 50 GB on the $20 plan. Past that, the entries used longest ago go first; saving never fails for room. One entry is at most 5 GB. From outside, an upload is at most 32 MB; a larger entry is not saved and the build goes on.

## Hits and misses

The [Caches](https://app.groundbox.dev/repos/cache) page shows what the cache holds and its hit rate per tool over the last week, with the build time Turborepo says its hits saved. `groundbox cache stats` prints the same.
