Run Hermes in a Vercel Sandbox

The vercel_sandbox terminal backend moves command execution into a Vercel Sandbox cloud microVM. Hermes still presents its normal terminal, process, and file-tool surfaces to the model; there are no Vercel-specific model-facing tools. This makes the backend useful when you want cloud isolation without teaching the agent a separate command vocabulary.

A correct setup has four parts: install the optional SDK extra, provide supported Vercel authentication, select a runtime, and decide whether filesystem snapshots should persist for the task.

Install the Vercel backend dependency

Install the optional Vercel extra in the Python environment that runs Hermes:

pip install 'hermes-agent[vercel]'

Do this before switching the backend. Otherwise Hermes can have a valid configuration but still be unable to create the sandbox because the Vercel SDK is unavailable.

Configure supported authentication

For deployments and normal long-running Hermes processes, use access-token authentication. All three variables are required:

VERCEL_TOKEN
VERCEL_PROJECT_ID
VERCEL_TEAM_ID

Store those values in the Hermes environment or inject them through the deployment platform's secret manager. For a conventional install, secrets belong in ~/.hermes/.env, not in config.yaml. Avoid printing the values during diagnostics; verify only that each variable is present.

The three-variable access-token path is the documented choice for Hermes processes hosted on services such as Render, Railway, or Docker. Supplying only the token is incomplete, even if another Vercel CLI command happens to work in your interactive shell.

Select the backend and runtime

Use the CLI to set the backend and one of the supported runtimes:

hermes config set terminal.backend vercel_sandbox
hermes config set terminal.vercel_runtime node24

The runtime choices are node24, node22, and python3.13. Hermes defaults to node24 when terminal.vercel_runtime is unset. The equivalent configuration is:

terminal:
  backend: vercel_sandbox
  vercel_runtime: node24
  container_persistent: true

Vercel Sandbox uses its standard workspace root by default, so most installations do not need to set terminal.cwd. Keep container_disk unset. Vercel does not currently support Hermes' custom disk-size control. The shared default value is 51200, but any non-default request fails diagnostics and backend creation rather than being ignored.

Run hermes config get terminal.backend and hermes config get terminal.vercel_runtime after editing to confirm the resolved values.

Use OIDC only for one-off local development

Hermes also accepts a short-lived Vercel OIDC token for an ad hoc local session. From anywhere, name the project explicitly:

VERCEL_OIDC_TOKEN="$(vc project token <project-name>)" hermes chat

From a directory already linked to the Vercel project, omit the project name:

VERCEL_OIDC_TOKEN="$(vc project token)" hermes chat

OIDC tokens are intentionally short-lived. They are convenient for a local experiment, but they are not the documented deployment path and should not replace the three access-token variables in an always-on service.

Understand snapshot persistence

With container_persistent: true, Hermes snapshots the sandbox filesystem during cleanup and can restore a later sandbox for the same task from that snapshot. This preserves files and installed state. It can also preserve Hermes-synced credentials, skills, and cache files that were copied into the sandbox, so persistence is a security and retention decision—not merely a convenience flag.

Snapshots do not preserve the live sandbox identity, PID space, shell state, or running background processes. Treat a restored sandbox as a new microVM with recovered filesystem contents. Startup scripts and process supervisors must recreate any services that need to run again.

If persistence is not wanted, set container_persistent: false and design the task so required inputs can be recreated. Do not rely on files remaining after cleanup in that mode.

Manage background commands through Hermes

While the sandbox is alive, terminal(background=true) uses Hermes' generic non-local background-process flow. The process tool can spawn, poll, wait, read logs, and kill tracked work. This is useful for a build, test run, or temporary development server.

The tracking contract ends with the live sandbox. Hermes does not provide Vercel-native detached-process recovery after cleanup or restart. If work must survive that boundary, persist its files and arrange for a fresh process to restart it; do not assume an old process can be reattached.

Pitfalls

Selecting vercel_sandbox before installing hermes-agent[vercel].
Providing VERCEL_TOKEN but omitting the project or team identifier.
Using a short-lived OIDC token as an always-on deployment credential.
Requesting a custom container_disk value and expecting Vercel to ignore it.
Treating snapshot persistence as live-process persistence.
Forgetting that credentials and cache files copied into a persistent sandbox may also enter a snapshot.
Looking for Vercel-specific agent tools instead of using the standard terminal, process, and file tools.

Verification checklist

Verify the optional Vercel SDK extra is installed in the same Python environment that launches Hermes.
Verify all three access-token variables are present without displaying their values.
Verify hermes config get terminal.backend returns vercel_sandbox.
Verify hermes config get terminal.vercel_runtime returns node24, node22, or python3.13.
Verify hermes doctor reports no Vercel backend dependency, authentication, or disk-setting error.
Verify a harmless terminal command and file write occur in the remote sandbox rather than on the host.
Verify a tracked background command can be polled and stopped while the sandbox is alive.
Verify any persistence test checks filesystem recovery only and does not claim the same PID or process survived.