Skip to content
GroundboxDocs
API referenceStatusPricing
DashboardStart free
GroundboxGitHub Actions runners and Linux sandboxes for AI agents. One key, one bill.System status

Product

CI runnersSandboxesBuilds and cacheAgent computersPricing

Developers

DocsAPI referenceAPI explorerCLIMCP serverBenchmark

Compare

vs GitHub-hostedvs Blacksmithvs E2Bvs DaytonaAll comparisons

Company

Talk to usSupportcontact@groundbox.devGroundmail ↗
© 2026 Groundbox
TermsPrivacyllms.txt
OverviewCI in one lineFirst sandboxHand it to your agent
Sizes and labelsCachesBuild cachesMigrateci waitTerminal on a jobPublic repositoriesAuto sizeAuto size: own runnersFlexCI tune-upSplit tests by timeDocker buildsGitLab CI
Start, exec, filesFrom a Docker imageCommandsForkTime machineSnapshotsPause and resumeStop and startIdle pause and wakeScheduled runsPreviewsSecretsEgress allowlistFlex sandboxesTemplatesVolumes
Push and pullIn GitHub ActionsStorage and retention
Desktop and actionsLive view in your appHuman handoffSign in onceAgent loop example
BucketsAccess keysMount a bucket
Move from Runloop
Omnara
REST APIAPI explorerOpenAPI referenceCLIMCP serverSDKsKeys and capsLeave or delete a team
  1. CI runners
  2. Build caches
Markdown
Open in
ClaudeChatGPT
On this page

    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.

    Terminal
    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 that has cache:read, and cache:write to save.

    Turborepo

    Terminal
    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

    Terminal
    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

    Text
    # 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

    Terminal
    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. 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 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.

    ← PreviousFirst sandboxNext →CI tune-up
    System statusSupportPricingllms.txtgroundbox.dev