feat(tools): add Sprites stateful sandbox backend 👾

[kylemclaren]

What does this PR do?

Adds a new terminal backend, TERMINAL_ENV=sprites, that runs the agent's shell commands inside a Sprite — a stateful cloud sandbox on Fly.io with native checkpoint & restore.

Sprites fills a gap between the existing cloud-sandbox backends. e.g:

• vs Modal / Vercel Sandbox — Sprites are persistent by default: a Sprite outlives the Hermes session and is reused (not just its filesystem snapshot) on the next run with the same identity. Live processes, sockets, and PID space survive across cleanup.

Wired through the existing _create_environment factory; no changes to the agent or tool surfaces. A pip install 'hermes-agent[sprites]' plus SPRITES_TOKEN is the only user-facing setup, and hermes setup terminal walks through it.

Sprite identity is profile-scoped: sandboxes are named hermes-{profile}-{task_id} (hermes-{task_id} on the default profile), so independent Hermes profiles never resume into one another's live Sprite, while the same (profile, task_id) always resumes the same one. Within-profile reuse across sessions is the backend's designed behavior — the same naming scheme and task-id resolution the Daytona backend uses on main.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Backend: tools/environments/sprites.py — SpritesEnvironment on sprites-py. Spawn-per-call, stdin via heredoc, persistent by default. _resolve_sprite_name derives the deterministic, profile-scoped, Fly/DNS-safe Sprite name.
• Wiring: terminal_tool.py (dispatch + _CONTAINER_BACKENDS cwd sanitization + container_config builder, so container_persistent: false actually reaches the backend), environments/__init__.py, file_operations.py.
• Backend classifications: registered sprites in every shared remote-backend set on current main — agent/prompt_builder.py (_REMOTE_TERMINAL_BACKENDS + fallback description, so host info is suppressed and the live in-backend probe is used), tools/approval.py (_should_skip_container_guards), file_tools.py, code_execution_tool.py, skills_tool.py.
• CLI: setup.py (menu + token prompt), status.py (SDK/token state), doctor.py (diagnostics), config.py (token status), AGENTS.md (structure tree).
• Dependency: sprites-py>=0.5.0,<0.6 in lazy_deps.py + pyproject.toml (upper-bounded per the pre-1.0 rule; full live integration suite verified against 0.5.0).
• Tests: test_sprites_environment.py (27 unit, mocked SDK — construction, naming/profile isolation, dispatch wiring, persistence, file sync), test_sprites_terminal.py (8 integration vs live API, gated by SPRITES_TOKEN).
• Docs: README.md (backend count → eight), configuration.md (per-backend section + restricted-token notes), environment-variables.md (SPRITES_TOKEN row), tools.md, security.md, cli-config.yaml.example (Sprites stanza).

How to Test

1. pip install -e . && pip install 'hermes-agent[sprites]'
2. Get a token: sprite login (or sprite auth setup --token …). Drop it into ~/.hermes/.env as SPRITES_TOKEN=….
3. Configure: ~/.hermes/config.yaml → terminal.backend: sprites, terminal.cwd: /home/sprite, terminal.container_persistent: true.
4. Smoke test the backend directly:

   from tools.environments.sprites import SpritesEnvironment
   env = SpritesEnvironment(cwd="/home/sprite", timeout=60, task_id="repro", persistent_filesystem=True)
   print(env.execute("sprite-env info"))   # → sprite_name=hermes-repro, distinct boot_id
   env.cleanup()

5. End-to-end via the agent: hermes --yolo -z "Run sprite-env info and quote the output". Confirm the sprite_name / sprite_id / boot_id returned differ from the host's.
6. Resume: re-run step 5, confirm client.list_sprites() shows the same Sprite (status warm) and the filesystem state from the prior run is intact.
7. Ephemeral: rerun with container_persistent: false, confirm client.list_sprites() no longer contains the Sprite after cleanup().
8. Profile isolation: run step 5 under a named profile (HERMES_HOME=~/.hermes/profiles/work), confirm a separate hermes-work-default Sprite is created and the default profile's Sprite is untouched.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(terminal):, docs(terminal):)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run the touched test suites (test_sprites_environment.py, test_container_cwd_sanitize.py, test_prompt_builder.py, test_approval.py, test_file_tools.py — 500+ tests) and all pass. The full pytest tests/ -q currently has 11 collection errors on unmodified upstream modules (acp/mcp) that reproduce on main.
• I've added tests for my changes
• I've tested on my platform: Ubuntu 25.10 (Sprite VM)

Documentation & Housekeeping

• I've updated relevant documentation (user-guide/configuration.md, reference/environment-variables.md, module docstrings)
• I've updated cli-config.yaml.example (OPTION 7: Sprites cloud execution)
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A (no architecture changes; followed the existing BaseEnvironment contract)
• I've considered cross-platform impact — backend uses httpx + websockets (both cross-platform) and bash -c on the remote Sprite (Linux); same host requirements as the existing Modal/Daytona backends. No new Windows/macOS constraints.
• I've updated tool descriptions/schemas — N/A (no tool schema changes; the change is purely the execution-environment layer)

Screenshots / Logs

Full agent loop:

$ hermes --yolo -z "Run 'sprite-env info' and quote its raw output verbatim. Then also run 'hostname' and 'cat /proc/sys/kernel/random/boot_id'."

Here's the raw output from sprite-env info:

{"org":"","sprite_id":"sprite-dd79f1ee-...","sprite_name":"hermes-default","sprite_url":"https://hermes-default-xyz.sprites.app","version":"0.0.1-rc43"}

hostname: hermes-default
boot_id: 64d0ad04-...

Host VM (for comparison) reports sprite_name=hermes, sprite_id=sprite-8366d184-…, boot_id=16a68ded-… — all distinct, confirming the agent's command ran inside the Sprite the backend created (not on the host).

Notes

• No sync-back on cleanup. SSH/Modal/Daytona copy agent-modified files back to ~/.hermes/cache/remote-syncs/… because their sandboxes are torn down or reset between sessions. Sprites is persistent by default — the ext4 filesystem is the authoritative store and the same Sprite is resumed by (profile, task_id), so a sync-back would be redundant work.
• No region / CPU / memory / disk / base-URL config. Sprites allocates compute dynamically (up to 8 CPU / 16 GB RAM per Sprite) and pins the API endpoint to api.sprites.dev; the dashboard does not expose user-selectable knobs for those today. The setup wizard surfaces this as a note instead of prompting for ignored values.
• Cmd.kill() is a no-op. The sprites-py SDK has no public cancel hook on a running WebSocket exec; timeouts use the SDK's WebSocket deadline.

Changelog since the automated review

• July: merged onto then-current main; profile-scoped Sprite identity (_resolve_sprite_name) + TestSpriteNaming covering resume, cross-profile isolation, slug sanitization, and resolver-failure fallback; registered sprites in the then-current backend classification paths (prompt host-suppression/probe, cwd sanitization, container_config builder, approval guard helper) with wiring tests pinning each.
• August: re-merged onto current main (~8.4k commits, spanning the Vercel Sandbox revert/re-add — resolutions keep upstream's Vercel surface and add Sprites alongside); swept the classification sites added since July (tools/env_probe.py _REMOTE_BACKENDS — the file cited in the review — plus file_tools fallback set/backend sniff, terminal_tool env-parse gate, prompt_builder probe config, credential_files cache-path translation); modernized the sprites-py pin to the stable 0.5.x series; re-ran the full live integration suite (8/8 green against api.sprites.dev on sprites-py 0.5.0).

[kylemclaren]

@teknium1 what's a good way to get this over the line?

[teknium1]

Thanks for the substantial backend implementation and the mocked/live coverage.

Problems

• tools/environments/sprites.py:83 names persistent resources from task_id, but the branch resolver maps ordinary top-level calls and delegated children to default (tools/terminal_tool.py:973-989). The new integration test explicitly accepts hermes-default for every supplied task id (tests/integration/test_sprites_terminal.py:103-106). That makes durable state shared across normal sessions rather than session-scoped.
• This branch predates current backend classification paths. Current main requires remote backends to be represented in tools/terminal_tool.py:1216, tools/file_tools.py:206-212, agent/prompt_builder.py:891-908, tools/env_probe.py:48-53, and tools/approval.py:2242-2253. The PR does not cover that current surface, so a direct salvage would retain host-path/host-prompt behavior in some paths.

Suggested changes

• Define a stable, profile/session-safe Sprite identity and test both intended resume and isolation between independent sessions.
• Salvage the backend onto current main's shared backend classifications, including file-tool-first and prompt/probe paths, then add tests for those routes.

Automated hermes-sweeper review.

[kylemclaren]

This comment is an answer to the automated hermes-sweeper review. It maps each problem to the commits that correct the problem.

Problem 1: All usual sessions shared one durable Sprite

The old code made the Sprite name from task_id only. The resolver maps usual sessions to default. Thus all usual sessions used one Sprite.

Commit 4c4b387 corrects this. The function _resolve_sprite_name now makes the Sprite name. The name is hermes-{profile}-{task_id}. The default profile keeps the old name hermes-{task_id}. Thus old Sprites keep their names. The function changes each name part into a safe DNS format.

The result is this. Two different profiles cannot attach to one live Sprite. The same profile and the same task always attach to the same Sprite.

Note: Sessions in one profile share one Sprite. This is the design, not an error. The Daytona backend on main has the same name procedure. A Sprite keeps live state between sessions. This is the primary feature of this backend.

Problem 2: The branch was older than the current backend classification paths

Two commits correct this. Commit 4c4b387 added sprites to the classification sets that were on main in July. Commit dd39668 added sprites to the sets that came to main after July. The merge commit dfdae48 put the branch on the current main.

The five cited files now all include sprites:

• tools/terminal_tool.py — _CONTAINER_BACKENDS, the dispatch, the container-config builder, and the env-parse gate
• tools/file_tools.py — the primary set, the fallback set, and the backend-name check
• agent/prompt_builder.py — _REMOTE_TERMINAL_BACKENDS, the fallback description, and the probe config
• tools/env_probe.py — _REMOTE_BACKENDS (this file was not on main in July)
• tools/approval.py — _should_skip_container_guards

Thus the prompt does not show host data for a Sprite session. The file tools use the container path rules. The approval layer uses the container rules.

Suggested change 1: A stable identity, with tests for resume and for isolation

The tests are in the unit suite. TestSpriteNaming has tests for these conditions: a stable name for resume, isolation between profiles, safe name format, and a fallback when the profile resolver fails.

The live test test_filesystem_survives_session_recycle does a resume against the real API. The teardown of each live test does an ephemeral deletion. We did the full live suite on 2026-08-18 against api.sprites.dev with sprites-py 0.5.0. All 8 tests passed.

Suggested change 2: Salvage on the current classifications, with tests for those routes

This is complete. See Problem 2 above. The test TestDispatchWiring fails if sprites is not in the container-config builder. The set guards in test_container_cwd_sanitize.py and test_prompt_builder.py now include sprites. Thus a regression will cause a test failure.

Other changes

• The sprites-py pin is now >=0.5.0,<0.6. The old pin was for a pre-release version.
• The inline review comments have answers with more detail.