Skip to content
Docs

Warm sandboxes for coding agents

Updated

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

WhatWhenNeeds
A whole checkSomeone passed it on these exact filesThe check run through hushrun run, as npx hushrun init wraps it
Single testsThe check's code changed, and some tests passed on the files they readtests: reuse for that check in hushrun.yaml, for these runners
Compiled Rust cratesThe repository's trusted CI compiled them, for the same system and compilerYour organization's shared store, 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.

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:

hushrun token create --agent fleet-a

At a terminal, the first line it writes to stderr is HUSHRUN_AGENT=<the string>, 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:

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:

HostFor
api.hushrun.comResults: what passed, and recording what runs
Your package registry, such as registry.npmjs.orgInstalling hushrun and your dependencies
Your organization's store host, which ends in .r2.cloudflarestorage.comCompiled 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:

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:

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.

Check it

In the sandbox:

$ 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:

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.

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 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. What has to match for a skip, and what it doesn't see: Why a skip is safe.

Markdown