Cloud agent sandboxes

Start Codex, Cursor, Claude, or another cloud sandbox with restored dependencies and build state, using a read-only token.

Restore cache during environment setup

Restore dependencies and build state inside Codex, Cursor, Claude, or another cloud development environment. Keep the cache settings in .boringcache.toml, use a restore-only token in the setup hook, and publish new cache from trusted CI.

Recommended path

Prewarm during environment setup

Configure BORINGCACHE_RESTORE_TOKEN in the provider's setup environment, run one explicit read-only command, and keep stage, save, and admin credentials out of the sandbox. The agent inherits warmed files without receiving write access.

Configure a Node.js sandbox

.boringcache.toml

workspace = "my-org/app"

[proxy]
metadata-hints = ["lane=agent-sandbox", "agent_provider=codex"]

[entries.npm]
path = ".npm-cache"
tag = "npm-cache"

[profiles.ci]
entries = ["npm"]

Setup-time prewarm

BORINGCACHE_REQUIRE_SERVER_SIGNATURE=1 \
  boringcache run --profile ci --read-only \
  -- npm ci --cache .npm-cache

This Node.js setup restores .npm-cache before running npm ci. Use the same profile and cache path in trusted CI to populate it. For another project, choose the cache entries and install command your repo uses. Set optional metadata in .boringcache.toml; do not record prompts, source text, session IDs, or credentials.

A cold or unavailable cache should not make the sandbox unusable. Keep the normal best-effort miss/error behavior unless the repository deliberately requires strict cache availability; signature verification stays fail-closed in the example.

Put the same command in the provider's native hook

OpenAI Codex cloud

Environment documentation →

Add the command to the Codex environment setup script and add the restore token as a setup secret. Codex documents setup-time internet access and removes secrets before the agent phase, so the warmed filesystem remains while the credential does not.

Cursor Cloud Agents

Environment documentation →

Use the install command in .cursor/environment.json and configure the restore token in Cursor's environment. Cursor caches disk state after installation. Its current model supplies secrets to the agent environment, so restore-only scope is mandatory.

Claude Code on the web

Environment documentation →

Use a cloud environment setup script, or a repo SessionStart hook when the restore must run for every session. Allow the BoringCache API and your workspace’s storage endpoints, and use only a restore token. A token set as an environment variable is readable by the session; use a dedicated, expiring restore token scoped to this workspace.

What the agent can reuse

Setup-time prewarm works best for archive profiles: package stores, dependency directories, generated assets, and local compiler state restored before the agent starts. The agent can reuse restored cache in its first build and new local outputs in later builds.

For native live protocols, invoke the existing tool adapter with --read-only during the agent phase. That requires BoringCache network access and a restore credential for the session. Prefer a short-lived workspace credential when available; never substitute a stage, save, or admin token.

Sandbox checklist

Commit one cache setup; keep the same tags and profiles across providers.
Scope the restore token to one workspace and give it an expiration.
Keep stage, save, and admin credentials outside agent execution.
Allow the BoringCache API and the storage endpoints used by your workspace.
Require server signatures and keep cache misses best-effort by default.
Use stable provider/lane metadata only; inspect actual workspace sessions before adding fleet reporting.

Keep cache access read-only in the sandbox. In the downstream pull-request workflow, use the matching GitHub Actions trust policy.

Need help or found something unclear? Open an issue or browse the CLI repo.