Run Hermes Agent's Terminal in Upstash Box

Hermes runs shell commands, code and file edits on your machine by default. The upstash-box plugin moves that work into a box: Hermes, your model calls and your sessions stay local, and the terminal, execute_code and file tools run in the box.

Each chat gets its own box. When you close Hermes the box is paused, and it resumes with your files and installed tools the next time.

1. Install the plugin#

Needs Hermes Agent 0.22.3 or newer. Have an Upstash Box API key ready.

hermes plugins install upstash-boxhermes plugins enable upstash-box

The install asks for your API key and saves it as UPSTASH_BOX_API_KEY in ~/.hermes/.env.

2. Switch the terminal backend#

hermes config set terminal.backend upstash_box

Or pick Upstash Box in hermes setup terminal. Check it with hermes doctor.

Restart Hermes so it picks up the new backend. In Hermes Desktop, quit the app and open it again.

3. Try it#

Start Hermes, or open a new chat in Hermes Desktop, and ask:

Run uname -a and whoami.

The answer comes from the box, with the user boxuser. The first command of a chat takes about 10–15 seconds while the box starts and your Hermes skills are uploaded. Later commands start right away.

Commands start in /home/boxuser.

Configure#

All settings are optional and go under terminal: in ~/.hermes/config.yaml:

terminal:  backend: upstash_box  container_persistent: true    # false: a new box per session, deleted when it ends  upstash_box_size: small       # small | medium | large  upstash_box_runtime: python   # node (default), python, golang, ruby, rust, ...  upstash_box_name_prefix: hermes

The default node image has Python but no pip. For Python work, set upstash_box_runtime: python. It applies to boxes created after the change.

Clean up boxes#

Paused boxes count toward your plan’s box limit, and every Hermes Desktop chat gets its own box. The plugin labels its boxes hermes:

box list --label hermesbox delete <box-id> --yes

To not keep boxes at all, set container_persistent: false. Each session then gets a new box, deleted when the session ends.

What runs where#

• Every command, and every file the file tools read or write, goes to the box.
• Your Hermes skills and cache are uploaded to ~/.hermes in the box. Changes made there are copied back when the session ends.
• If you connected GitHub under Box > Settings > GitHub, the box has your GitHub credentials, so the agent can clone and push.
• Your API key stays on your machine and is never sent into the box.
• Hermes skips its dangerous-command approval for commands in the box, as for its other cloud backends.

Next steps#