NousResearch/hermes-plugin-sprites

NousResearch/hermes-plugin-sprites

Description: Sprites terminal backend plugin for Hermes Agent — stateful Fly.io cloud sandboxes with checkpoint & restore

Language: Python

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-08-25T03:06:21Z

Pushed: 2026-08-25T03:06:24Z

Default branch: main

Fork: no

Archived: no

README:

hermes-plugin-sprites

Sprites terminal backend for Hermes Agent — run agent shell commands in Sprites, stateful cloud sandboxes on Fly.io with checkpoint & restore.

Built on the pluggable terminal-backend extension point (hermes-agent PR #94400): this plugin registers terminal.backend: sprites as a first-class backend across dispatch, the setup wizard, hermes status / hermes doctor, the dashboard picker, approval policy, path handling, and subprocess secret stripping — with zero changes to hermes-agent core.

Install

# 1. Copy/clone this repo into the Hermes plugins dir
git clone git@github.com:NousResearch/hermes-plugin-sprites.git ~/.hermes/plugins/sprites

# 2. Install the SDK
pip install 'sprites-py>=0.5.0,> ~/.hermes/.env

hermes doctor reports token/SDK status once terminal.backend: sprites is active.

Behavior

• Persistent by default. Each Sprite outlives the session and is resumed via a deterministic, profile-scoped name (hermes-{task} on the default profile, hermes-{display}-{digest12} on named profiles). Its ext4 filesystem is the authoritative store — no sync-back.
• Profile isolation is fail-closed. Identity digests are collision-resistant across component boundaries and DNS-bounded; profile-resolution failure refuses to fall back to the default profile's Sprite.
• Ephemeral mode (terminal.container_persistent: false): run-unique Sprite names (never adopted, deleted on cleanup), with per-session sandbox identities so two ephemeral runs can never attach the same live VM.
• Bounded exec deadlines. Commands without a positive timeout stop at 3600s inside the Sprite (the SDK has no kill hook on a running command).
• Sharing model: gateway/WebUI sessions each get their own Sprite; delegate_task children share their parent's; key-less flows (CLI, cron) share the profile-default Sprite.
• SPRITES_TOKEN / SPRITE_TOKEN are stripped from every subprocess the agent spawns.

Tests

# Unit (no token needed) — run from a hermes-agent checkout's venv so
# agent/ and tools/ imports resolve:
python -m pytest tests/test_sprites_environment.py

# Live integration (needs SPRITES_TOKEN; creates run-unique hermes-test-*
# sprites and deletes them):
python -m pytest tests/test_sprites_terminal_live.py -m integration

Attribution

The Sprites environment was authored by Kyle McLaren (@kylemclaren, Fly.io) as hermes-agent PR #30112 and hardened through three rounds of review in PR #93523 (identity digests, DNS bounds, fail-closed profile resolution, race-safe first-use create, bounded deadlines, sandboxed live test suite). Extracted to this standalone plugin repo per the hermes-agent policy that third-party service integrations ship as plugins rather than core code.

License

MIT