# Warm sandboxes for coding agents A coding agent's sandbox starts cold: it has no record of what passed and nothing compiled, so the agent runs every check and compiles every crate again. With one variable, `HUSHRUN_AGENT`, the sandbox skips the checks that you, CI or another agent already passed on these exact files, can leave out tests that already passed, and can download the Rust crates your CI compiled. ## What a fresh sandbox reuses | What | When | Needs | |---|---|---| | A whole check | Someone passed it on these exact files | The check run through `hushrun run`, as `npx hushrun init` wraps it | | Single tests | The check's code changed, and some tests passed on the files they read | `tests: reuse` for that check in `hushrun.yaml`, for [these runners](https://hushrun.com/docs/tests.md#runners) | | Compiled Rust crates | The repository's trusted CI compiled them, for the same system and compiler | Your organization's [shared store](https://hushrun.com/docs/compiled-code.md), turned on and reusing, and the store's host allowed | Whatever the sandbox passes is recorded for your team, so CI and the next sandbox can skip it too, within [CI's rules](https://hushrun.com/docs/run.md#in-ci). ## Before you begin - The repository's checks run through hushrun, as `npx hushrun init` sets them up, and the repository installs hushrun 0.6.0 or later. For single tests, 0.16.0; for the shared store, 0.15.0. - An admin or owner of your organization on hushrun, to create the token. ## Create an agent token On the dashboard's **Agents** page, or in the repository, signed in with `hushrun login`: ```bash hushrun token create --agent fleet-a ``` At a terminal, the first line it writes to stderr is `HUSHRUN_AGENT=`, shown once. Copy the whole line. The string holds your organization's backend, the token and its machine key, and one string can serve a whole fleet. A token covers one repository unless you add `--org-wide`, and expires after 30 days unless you set `--expires`. ## Give the sandbox the variable Store the string as a secret in the sandbox's environment: ```dotenv HUSHRUN_AGENT=hushrun_agent_v1_… ``` It holds a private key. Never put it in `HUSHRUN_TOKEN`. ## Allow the network hosts A sandbox that reaches only a list of hosts needs: | Host | For | |---|---| | `api.hushrun.com` | Results: what passed, and recording what runs | | Your package registry, such as `registry.npmjs.org` | Installing hushrun and your dependencies | | Your organization's store host, which ends in `.r2.cloudflarestorage.com` | Compiled code, where your organization shares it | You don't need to know the store's exact host in advance. When it's blocked, the sandbox compiles as usual, and the run names the host to allow, once: ```text hushrun: build: the shared store's host, acme.r2.cloudflarestorage.com, can't be reached from here: where this network allows only some hosts, allow acme.r2.cloudflarestorage.com to reuse what other machines built ``` ## Install dependencies in setup The sandbox's setup script installs the repository's dependencies, such as `npm ci`, which installs hushrun and the pre-push hook. For a Rust repository, install the toolchain the repository pins. If the sandbox turns the network off once setup ends, as Codex cloud's does, fetch the compiled code during setup, at the repository's root, naming the checks the agent will run: ```bash hushrun build fetch test lint ``` What it fetched is kept sealed for 24 hours, with no token, and later runs reuse it when they can't reach hushrun's server. Checks and tests need the network to skip. Details: [A sandbox that loses its network](https://hushrun.com/docs/shared-store.md#offline-sandbox). ## Check it In the sandbox: ```console $ hushrun whoami backend https://api.hushrun.com/o/acme (HUSHRUN_AGENT names it) token HUSHRUN_AGENT, an agent token as agent:fleet-a in acme … ``` Then the agent runs the repository's checks the usual way. A check that already passed on these files skips: ```text hushrun: e2e skipped: this exact code passed 1 min ago (saves 16s) ``` ## For Claude Code cloud sessions In the environment's settings: - the environment variable `HUSHRUN_AGENT`, with the string `hushrun token create` printed; - network access that reaches `api.hushrun.com` and the npm registry, and the store's host where your organization shares compiled code; - a setup script that installs the dependencies, such as `npm ci`. For a Docker container, an E2B sandbox or a Kubernetes job, pass the same variable through its environment: [A container](https://hushrun.com/docs/agents.md#a-container). ## What a sandbox doesn't do - **It writes no compiled code** unless an admin turns writing on for its agent token. It reuses only what your trusted CI compiled. - **It reuses compiled code only from `hushrun run NAME -- COMMAND`.** A check of `hushrun.yaml` run as `hushrun run CHECK` reuses nothing from the shared store. - **It gets nothing from another system.** Code built on Linux CI doesn't reach a macOS sandbox, or one with another compiler version. - **Don't restore a cached `target/`.** hushrun shares only what the sandbox compiled itself. - **Variables don't count.** A check that depends on an environment variable or a tool version needs a name per variant, or a [`counts_from`](https://hushrun.com/docs/where-a-check-counts.md) rule. ## Decide what CI trusts A pass from a sandbox is the agent's word that its sandbox ran the check, signed with its token's key. By default it skips a CI job without variants. To make CI skip only on its own passes, turn on [CI reuses only CI's results](https://hushrun.com/docs/ci.md#ci-only). What has to match for a skip, and what it doesn't see: [Why a skip is safe](https://hushrun.com/trust). ## Related - [Agents in sandboxes](https://hushrun.com/docs/agents.md): every setting of `HUSHRUN_AGENT`. - [hushrun in sandboxes](https://hushrun.com/sandboxes): what a sandbox stops doing again. - [Keep CI useful with coding agents](https://hushrun.com/docs/guides/coding-agents-ci.md) - [A Rust build cache in GitHub Actions](https://hushrun.com/docs/guides/rust-build-cache-github-actions.md)