Platform-restored setup cache: persist allowlisted $HOME toolchain caches across sandbox restarts (seam: run_setup_scripts)

Open
#23 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python

Research direction

Start at openhands/app_server/app_conversation/app_conversation_service_base.py and trace run_setup_scripts() around maybe_run_setup_script(). Review how sandbox workspace and $HOME files are persisted, then check existing tests for setup-script execution and persistence. Done means the allowlisted caches restore before setup, save after success within the size budget, and corrupted entries or credentials are handled as specified.

Written by the indexing model from the issue text.

Description

Context

Companion to OpenHands/OpenHands#18942 (filed on the Canvas repo; triage scoped the platform half of that issue to this repository because the setup-script seam lives here). This issue carries outcome (a) from that thread — a platform-restored setup cache. Outcome (b), the public "Writing a robust setup.sh" guide, is docs#1005.

Production evidence: in nine frumfinance repositories, .openhands/setup.sh install steps that take 3-7 minutes are already convergent (fingerprint-gated, re-runnable), so a warm cache turns them into a few seconds. Today every restart re-downloads hundreds of MB because $HOME is recycled between sandbox restarts while the workspace (/workspace) persists.

Seam

openhands/app_server/app_conversation/app_conversation_service_base.py → run_setup_scripts():

clone_or_init_git_repo()          # workspace ready
  ↓
RUNNING_SETUP_SCRIPT → maybe_run_setup_script(workspace, project_dir)   # ← restore BEFORE, save AFTER
  ↓
SETTING_UP_GIT_HOOKS → maybe_setup_git_hooks(...)
  ↓
SETTING_UP_SKILLS → load_and_merge_all_skills(...)

Restore should happen before the first maybe_run_setup_script call; save after its successful completion (mirror the "stamp on success only" semantics the setup.sh guide prescribes).

Proposed convention

.openhands/setup-cache/ inside the workspace (persists with /workspace, is repo-scoped, and is defined by the repo's own .openhands/ namespace). The platform transparently maps/restores a blessed allowlist of $HOME paths to/from it around maybe_run_setup_script.

Bless-list (from the nine production setup.sh scripts)

Package-manager caches and shims only — everything these scripts actually populate:

Path Backed by
$HOME/.cache/pip pip
$HOME/.cache/uv uv
$HOME/.cache/pypoetry poetry
$HOME/.cache/pre-commit pre-commit hooks
$HOME/.cache/ms-playwright Playwright browsers (large, biggest win)
$HOME/.npm npm cache
$HOME/.local/bin tool shims (poetry etc.)

Explicitly NOT restored: project node_modules/.venv (already handled by workspace persistence + setup.sh convergence), git configs, shell rc files, anything outside the allowlist.

Credential exclusion (deny-by-default)

Restored files must be cache artifacts only. Never restore or persist: ~/.npmrc (auth tokens), ~/.netrc, ~/.ssh/*, ~/.aws/*, ~/.pypirc, ~/.gitconfig, ~/.config/gh/*. Since restore is allowlist-only, these are excluded by construction — the allowlist must never grow to include an rc/config file.

Size budget + eviction
  • Budget: configurable, default ~2 GB per repo (Playwright browsers alone are ~400 MB; pip/uv/npm caches are the rest).
  • Eviction: LRU at the file level inside the cache, evict on save when over budget. Never evict mid-restore.
  • Save is atomic (write to temp + rename), and restore merges rather than replaces (a newer cache entry wins over an older restored one) — same merge/atomic-swap semantics proposed in OpenHands/OpenHands#18942.

Acceptance criteria

  1. Given a warmed .openhands/setup-cache/, a fresh sandbox + the same repo runs setup.sh in well under a minute without network installs (allowing for cache-hit checks).
  2. A corrupted/truncated cache entry is treated as a miss (setup.sh must remain correct and convergent without it — that property is load-bearing, see docs#1005).
  3. No credential-bearing file ever appears in the cache or in a restored $HOME.
  4. Cache size never exceeds the budget after save.

This issue was filed by an AI agent (OpenHands) on behalf of the user.

Dominant language
Python
Stars
9
Forks
16
Avg merge
7d 4h
Merged PRs (30d)
2

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenHands/sandbox-server

All issues in OpenHands/sandbox-server

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.