Hermes

Hermes is Nous Research's open source terminal coding agent. Its Vercel Sandbox terminal backend runs every command the agent executes inside an isolated Vercel Sandbox microVM instead of on your machine.

Before you begin, make sure you have:

• macOS, Linux, or Windows with WSL2
• Hermes 0.20.0 or newer. Older releases do not include the Vercel Sandbox backend.
• Vercel CLI installed, logged in, and a Git repository linked to a Vercel project with vercel link

Sandbox time that Hermes uses is billed as normal Vercel Sandbox usage, including snapshot storage for persisted task filesystems.

1. Install Hermes

   Install with the official installer, or update an existing install:

   Terminal

   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

   If Hermes is already installed, run hermes update and confirm the version is 0.20.0 or newer with hermes version.

2. Enable the Vercel Sandbox backend

   Point the terminal backend at Vercel Sandbox and give the sandbox a valid resource shape:

   Terminal

   hermes config set terminal.backend vercel_sandbox
   hermes config set terminal.vercel_runtime node24
   hermes config set terminal.container_cpu 2
   hermes config set terminal.container_memory 4096

   The runtime is one of node24 (the default), node22, or python3.13. These are Vercel Sandbox's legacy runtimes: the terminal.vercel_runtime setting configures a legacy runtime, while new SDK v3 sandboxes default to the Ubuntu-based vercel/sandbox/universal:latest managed image.

   Vercel Sandbox allocates 2,048 MB of memory per vCPU, so terminal.container_memory must be 2,048 times terminal.container_cpu. Hermes's generic container default of 5,120 MB is not a valid value for this backend and fails with a memory allocation validation error. Leave terminal.container_disk unset: custom disk sizes are not supported.

   You can also configure the same settings interactively with hermes setup terminal. When the current directory is linked to a Vercel project, the setup prompt reads its defaults from the nearest .vercel/project.json.

3. Authenticate with Vercel

   For local development, pull a short-lived OIDC token from your linked project and export it:

   Terminal

   vercel env pull
   export VERCEL_OIDC_TOKEN="<value of VERCEL_OIDC_TOKEN from .env.local>"

   OIDC tokens are development-only and expire. For deployments and long-running Hermes processes, set VERCEL_TOKEN, VERCEL_PROJECT_ID, and VERCEL_TEAM_ID instead. See Sandbox authentication for both methods.

4. Verify the backend

   Run the built-in diagnostics:

   Terminal

   hermes doctor

   The report should show passing checks for the Vercel runtime, the vercel SDK, and Vercel auth, including which auth mode is active.

5. Run Hermes

   Start a conversation with hermes. When the agent uses its terminal tool, the command executes inside a Sandbox microVM as the vercel-sandbox user with /vercel/sandbox as the workspace root, not on your machine.

• One sandbox per task: Hermes creates a sandbox on demand when the agent first runs a terminal command and reuses it for the rest of the task. Sandboxes are short-lived and are recreated automatically as needed.
• Snapshot persistence: With terminal.container_persistent: true (the default), Hermes snapshots the sandbox filesystem per task and restores it when the task resumes. Live processes do not survive sandbox recreation.
• Isolation: Commands run in a Firecracker microVM with its own filesystem and network. See Sandbox concepts for the isolation model.

To route Hermes model requests through Vercel AI Gateway, run hermes model and choose Vercel AI Gateway. That configuration is covered on the Hermes page in the AI Gateway docs.

The configured memory does not match Vercel's allocation model. Set a valid pair, for example terminal.container_cpu 2 with terminal.container_memory 4096 (2,048 MB per vCPU).

Your VERCEL_OIDC_TOKEN has expired. Run vercel env pull in the linked project and export the fresh token. For processes that outlive a development session, use access-token auth instead.

pip install 'hermes-agent[vercel]' installs 0.19.0 from PyPI, which predates the Vercel Sandbox backend, and warns that the vercel extra does not exist. Install or update with the official installer instead, and confirm hermes version reports 0.20.0 or newer.