What does this PR do?

Adds Vercel Sandbox as a supported Hermes terminal backend, alongside existing sandbox providers such as Modal and Daytona.

The backend uses Hermes' shared BaseEnvironment contract, syncs Hermes-managed files through FileSyncManager, supports Vercel snapshot-backed filesystem persistence for container_persistent=true, and exposes Vercel through the existing terminal/file/execute_code runtime-selection path rather than as a new model-facing tool family.

Vercel Sandbox exposes higher-level APIs for interacting with background processes, and we considered a broader integration that would take advantage of those native capabilities. For this first introduction, this PR keeps the implementation narrow and consistent with the other Hermes sandbox providers: background commands use Hermes' existing generic non-local background-process flow. Snapshot persistence means filesystem state can be restored for the same task; it does not mean the same sandbox VM, PID namespace, shell state, or running background jobs survive.

Related Issue

Fixes #

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

• Added tools/environments/vercel_sandbox.py, a lazy-imported Vercel Sandbox backend that creates/restores sandboxes, runs commands through Hermes' shell contract, uploads Hermes-managed files, retries transient create/write failures, and syncs remote .hermes/ changes back during cleanup.
• Wired vercel_sandbox into terminal and code execution flows in tools/terminal_tool.py, tools/code_execution_tool.py, tools/file_tools.py, tools/approval.py, and tools/skills_tool.py.
• Added Vercel snapshot persistence metadata under HERMES_HOME, keyed by task_id, with stale snapshot fallback to fresh sandbox creation.
• Added Vercel product-surface support in hermes_cli/config.py, hermes_cli/setup.py, hermes_cli/status.py, hermes_cli/doctor.py, hermes_cli/web_server.py, gateway/run.py, and cli.py. Setup now prompts for long-lived access-token auth (VERCEL_TOKEN, VERCEL_PROJECT_ID, VERCEL_TEAM_ID) and can prefill project/team IDs from the nearest .vercel/project.json.
• Added terminal.vercel_runtime / TERMINAL_VERCEL_RUNTIME support with supported runtimes node24, node22, and python3.13.
• Added the optional dependency extra hermes-agent[vercel].
• Blocked Vercel auth variables from ordinary terminal subprocess inheritance by default: VERCEL_OIDC_TOKEN, VERCEL_TOKEN, VERCEL_PROJECT_ID, and VERCEL_TEAM_ID.
• Updated operator docs in website/docs/user-guide/configuration.md and website/docs/user-guide/features/tools.md.
• Added focused tests for the backend, terminal requirements, setup/status/doctor surfaces, config bridging, auth secret blocking, runtime availability, and sync-back behavior.

How to Test

Automated regression tests

Run the focused regression set:

scripts/run_tests.sh tests/tools/test_vercel_sandbox_environment.py
scripts/run_tests.sh tests/tools/test_terminal_requirements.py tests/tools/test_terminal_tool_requirements.py
scripts/run_tests.sh tests/tools/test_local_env_blocklist.py
scripts/run_tests.sh tests/hermes_cli/test_set_config_value.py tests/gateway/test_config_cwd_bridge.py tests/hermes_cli/test_setup.py tests/hermes_cli/test_status.py tests/hermes_cli/test_doctor.py tests/hermes_cli/test_web_server.py

Live Vercel Sandbox smoke test

1. Create or sign in to a Vercel account.

   • Go to https://vercel.com/signup if you do not already have an account.

   • Create or select the Vercel team you want Hermes to use for sandbox execution.

   • Install the Vercel CLI:

     pnpm i -g vercel

     If you do not use pnpm, install with your usual global Node package manager, for example npm i -g vercel.

   • Confirm the CLI is available:

     vercel --version

   • Log in:

     vercel login

     Follow the browser/email flow until the CLI reports that you are authenticated.

2. Create or select a Vercel project.

   • In the Vercel dashboard, select the correct team, then create a project from the dashboard.

   • Alternatively, from the CLI, create or inspect projects with:

     vercel project ls
     vercel project add
     vercel project inspect your-project-name-here

3. Create a Vercel access token and collect project/team IDs.

   • Create an access token from the Vercel dashboard.
   • Use the project's projectId as VERCEL_PROJECT_ID and the owning team's orgId as VERCEL_TEAM_ID.
   • If the local checkout is linked with Vercel, Hermes setup can prefill the project/team IDs from .vercel/project.json.

4. Install the Hermes Vercel optional dependency, select the backend, and configure access-token auth:

   pip install 'hermes-agent[vercel]'
   hermes config set terminal.backend vercel_sandbox
   hermes config set terminal.vercel_runtime node24
   hermes setup terminal

   When prompted by hermes setup terminal, choose Vercel Sandbox and enter:

   • VERCEL_TOKEN
   • VERCEL_PROJECT_ID
   • VERCEL_TEAM_ID

5. Run Hermes:

   hermes chat

   In the chat session, ask Hermes to run a simple terminal command such as:

   Use the terminal to print the current working directory and Node version.
   

   Expected result: the command runs in Vercel Sandbox, with the default workspace rooted around /vercel/sandbox.

   For one-off local development only, runtime still accepts a short-lived OIDC token instead of saved access-token auth:

   VERCEL_OIDC_TOKEN="$(vc project token your-project-name-here)" hermes chat
   VERCEL_OIDC_TOKEN="$(vc project token)" hermes chat

   OIDC tokens are short-lived and are not the recommended path for Render/Railway/Docker deployments or other long-running Hermes processes.

6. Optional persistence check:

   • With terminal.container_persistent enabled, ask Hermes to create a small file in the sandbox.
   • Let the sandbox clean up or start a new task using the same task/session path.
   • Ask Hermes to read the file again.
   • Expected result: filesystem state is restored from a Vercel snapshot. Live processes are not expected to survive.

7. Optional background check:

   • Ask Hermes to start a short background terminal command, poll/wait for it, and show the output.
   • Expected result: this works through Hermes' existing generic non-local background flow while the sandbox is alive.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• 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 pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Running Hermes Agent Chat

hermes status

hermes doctor