hermes-crabbox

Cloud-agent workflow. Your own computer.

An alternative for people who want the delegated coding workflow of Devin or Cursor Cloud Agents, using hardware they already own. Run independent container dev boxes on a spare computer—or a machine with enough available RAM—while your main agent hands off tasks and collects the results.

The worker environments run on your hardware. The configured LLMs can still use external model APIs or subscriptions; this does not make inference offline or remove provider costs. The aim is a similar delegation workflow, not feature parity with those services. Hardware and current limits.

Related MCP server: Leetcoder

What it does

Parent agents such as Grokbot, Hermes, Codex, Claude, or any agent that supports MCP or HTTP can delegate coding tasks to Hermes Crabbox. The parent submits an assignment; a Hermes worker runs it in a dedicated Crabbox container with its own workspace, Chromium browser, and optional graphical desktop.

Check progress, retrieve code and screenshots, send follow-ups, and prepare a PR from the calling agent. Tasks keep running independently of the parent's connection. Compatibility depends on the caller's network and authentication support; this is not a claim that every named client has been tested.

An actual screenshot from the synthetic Counter Demo task, captured after clicking Increase. This is an example of the evidence a worker returns for review. Screenshots, recordings, and PR evidence →

Choose your setup path

Let your agent set it up

Point your agent at AGENTS.md, or give it this prompt:

Read this repository's AGENTS.md and setup guide. Install Hermes Crabbox on my chosen worker computer and connect the agent I'm using now. Inspect both machines, preserve existing configuration, keep secrets out of chat, and report what actually works.

Agent setup guide → · Platform support →

Connect your agent

Before connecting: the machine running the agent's tools needs Tailscale access to your worker host and a dedicated service credential. The skill installer generates MCP configuration for the server you choose. Source and skill downloads are public. No token is embedded in a button, example, or skill bundle.

Codex: one command to register MCP

Make OMARCHY_CLOUD_TOKEN available to the Codex process through your secret manager, then run:

codex mcp add hermes-crabbox \
  --url https://worker.example.ts.net/mcp \
  --bearer-token-env-var OMARCHY_CLOUD_TOKEN

Hermes: install the delegation skill

Replace the example origin with the HTTPS origin from your host setup receipt:

git clone https://github.com/thomasbek3/hermes-crabbox.git
cd hermes-crabbox
python3 scripts/install-delegation-skill.py --agent hermes \
  --server https://worker.example.ts.net --json

The installer copies the skill and HTTP caller to ~/.hermes/skills/, preserves existing modified installations, and does not touch credentials or start a job. Use --agent codex, --agent claude, or --agent cursor for those harnesses, or --skills-dir PATH for a custom agent/profile skills directory.

Other agents: use the MCP connection guide or the included Python HTTP client. Cursor users get a server-specific cursor.mcp.json in the installed skill. Merge it into the selected profile, preserving existing servers.

Give it a first assignment

After connecting, ask your agent:

Read get_delegation_guide. Delegate the task in examples/task.md to a Hermes worker, supplying the specified repository snapshot. Save the task ID, check progress when I ask, and return the resulting changes and evidence. Do not merge or deploy.

Write a useful assignment →

How it works

Hermes starts inside the task container first. In the optional pstack profile, that running agent can ask Jev to choose an allowed workflow and invoke roles with predefined models. Temporary role sessions share the task's workspace; they are not new containers for every role.

Architecture and lifecycle →

Built for delegated work

• One task, one environment. Separate containers and workspaces, with queueing and resource admission on the execution host.

• Browser and desktop included. Chromium for web work; XFCE/VNC for tasks you want to watch. Desktop guide.

• Evidence with the result. Skills for screenshots and recordings, plus a parent-side PR evidence publisher. Evidence guide.

• Persistent worker instructions. Every supported worker profile loads the cloud-worker SOUL.md, including repository contribution rules and honest completion reporting.

• Optional model routing. Jev selects a workflow; pstack policy fixes the model and effort for each role. Routing guide.

• Private access. Tailscale connectivity, caller-scoped credentials, and owner-isolated tasks. Access and security.

Project status

Preview. Separate host installation and caller setup paths support agent-driven onboarding. The host installer targets Linux x86_64 with systemd and Docker Engine. Provider and Tailscale logins remain owner-controlled. See the verification status before relying on a fresh deployment.

The basic worker, desktop viewing, evidence capture, and MCP have recorded checks. The full optional multi-model workflow remains partially qualified; see status and known limits. The host installer defaults to two concurrent tasks and permits up to eight, subject to resource admission; this is not an eight-task load-test claim.

PR publishing uses the parent agent's authorized GitHub access. Workers do not receive its GitHub credentials. The source is public; access to a running worker host still requires explicit caller provisioning.

Develop and contribute

python3 -m venv .venv
.venv/bin/pip install -e '.[test]'

Start with building and deployment, contributing, and the documentation index. Operator scripts can change a live host; read their documented scope before running them.

Internal Python packages and services retain their cloudworkbench names. Credentials, databases, raw reviews, and private task outputs are excluded. Only the explicitly selected synthetic demo screenshot is included as evidence. Historical documents can reference local evidence that is intentionally absent.

License and acknowledgments

Original integration code is MIT licensed. This project builds on Crabbox, Hermes Agent, Lauren Tan's pstack, its Hermes port, and Vercel's agent-browser. The Hermes Jev router informed the routing design.

Copied upstream material retains its own terms, including Apache 2.0 for the browser skill. See licensing scope and full credits, source pins, and notices.

Independent integration maintained by Thomas Bekkers; not an official release of, or endorsed by, those upstream projects.