Headmesh Agent Sandbox

Name: Headmesh Agent Sandbox
Author: headmesh-dev

by headmesh-devversion 0.1.0i★ 1iRuns in the cloud

Registry nameio.github.headmesh-dev/headmesh-sandbox

Install

Overview

Description from the maker (original English)

Run commands, edit files and manage Git and persistent sessions in your own isolated sandbox.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi2 of 2 passedChecked from public information; code not scanned yet
UsageiVery new★ 1

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs in the cloud
Transport: Streamable HTTP
Category: Developer tools

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 2 of 2 passed
Runs on the maker’s server: what you ask it goes through their server.
You fill in yourself: Authorization

You need

Runs in the cloudNothing to install; it connects over the internet

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

This address needs a key in a request header, which the add-connector menu cannot set. Use Claude Code, Cursor or VS Code instead.

Run this in your terminal

claude mcp add --transport http headmesh-sandbox 'https://{sandbox_host}/mcp' --header 'Authorization: Bearer {sandbox_token}'

Fill in the empty values before running it.

The address contains {…} parts that only you know (such as your account), so copy it and fill them in.

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "headmesh-sandbox": {
      "url": "https://{sandbox_host}/mcp",
      "headers": {
        "Authorization": "Bearer {sandbox_token}"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

The address contains {…} parts that only you know (such as your account), so copy it and fill them in.

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "headmesh-sandbox": {
      "type": "http",
      "url": "https://{sandbox_host}/mcp",
      "headers": {
        "Authorization": "Bearer {sandbox_token}"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This address needs a key in a request header, which the add-connector menu cannot set. Use Claude Code, Cursor or VS Code instead.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

Authorization HTTP header
A scoped bearer token issued by your own Headmesh sandbox

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

Which apps can use it

Based on how this server connects and on each app’s own docs, checked Nov 10, 2026.

Connect over the internet in

Claude ChatGPT Goose LM Studio Msty Studio Cherry Studio Cursor VS Code + GitHub Copilot Visual Studio Windsurf (Devin Desktop)Zed Kiro Cline Continue JetBrains AI Assistant Claude Code Codex CLI Gemini CLI OpenCode nodecode Warp LibreChat Open WebUI Raycast

All apps, with pros and cons →

What it can do

The address needs your own values, so we cannot read the tool list for you.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 10, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account headmesh-dev, which owns the repo
✓ Pass
Still maintained
Code last changed 3 days ago
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
The address needs your own account values, so we cannot check it for you
– Not applicable
Sign-in with OAuth
The address needs your own account values, so we cannot check it for you
… Not checked yet
No hidden instructions in tool descriptions
Not checked yet; we read the tool list when we check the endpoint

Compared with others in Developer toolsi

More stars than 65% of the other 5729 servers in this category
Published to the registry more recently than 75% of the other 5729 servers in this category
Basic checks equal to or better than 100% of the other 5729 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Headmesh Agent Sandbox safe?

It passed 2 of 2 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs in the maker’s cloud. Connect over the internet with nothing to install, but what you send passes through the maker’s servers.

Is it still maintained?

The GitHub repo last changed 3 days ago, and the latest version (0.1.0) reached the registry 6 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. It connects by URL, so apps that accept remote MCP servers work too, such as ChatGPT in developer mode.

What can I use instead?

In the same category: REA, Netdata, Front-End Checklist

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

REA

Reverse engineer anything from your terminal or agent with one CLI and MCP server.

by morlutoWidely used↓ 388.7K/wk★ 448.2KUpdated 16 days ago

Runs on your computer

Install

Netdata

Real-time infrastructure monitoring with metrics, logs, alerts, and ML-based anomaly detection.

by netdataWidely used★ 81.3KUpdated 6 days ago

Runs in the cloud

Install

Front-End Checklist

Review frontend code and live pages against 386 quality-gated web development rules.

by thedaviddiasWidely used★ 74.7KUpdated 37 days ago

Runs in the cloud

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

Headmesh agent sandbox

A persistent Docker container on the ASUS that joins Aaryn's Headscale tailnet as its own tagged node, so cloud agents can work with real files, real dependencies and private services. Agents reach it through several front doors:

an MCP server, headmesh-sandboxd;
the Claude self-hosted runner and Claude Remote Control;
Codex over Tailscale SSH;
the OpenAI Secure MCP Tunnel;
codex exec-server, driven from the host through the Agents API.

It implements plan §6 and §7 (docs/plan.md).

Path	What
`image/`	Multi-stage Dockerfile on `ubuntu:26.04` (pinned by digest), s6-overlay services, git hooks, guidelines template, `docker-bake.hcl`, container-structure-test, hadolint config
`compose/`	`compose.yaml` with the `regular` and `yolo` profiles (embedded in the CLI)
`config/`	`sandbox.example.toml` and its JSON Schema (`sandbox.schema.json`)
`sandboxd/`	The MCP daemon: tools, sessions (tmux), auth, audit, status
`cmd/headmesh-sandboxd/`	Daemon binary, plus the in-container helpers (`hm`)
`cmd/headmesh-sandbox/`	Host CLI
`host/`	Egress firewall and restic backup units. Aaryn installs them with sudo; see `host/README.md`
`tests/acceptance/`	The five-check harness, the recreate bonus and `prompt.md`
`tests/e2e/`	Live test against a running container
`docs/`	`container-contract.md` (the interface between image, Compose, CLI and daemon) and the ADRs

This is its own Go module, github.com/headmesh-dev/headmesh/sandbox; the root go.work includes it. Run go test -race ./... here.

What's verified (2026-10-27)

All of this was run locally, without tailnet enrollment:

go test -race ./... passes. That includes integration tests on real tmux and real git, and the harness against an in-process sandboxd. golangci-lint run with the repo config reports 0 issues.
docker buildx bake -f sandbox/image/docker-bake.hcl sandbox-local builds headmesh-sandbox:dev (2.39 GB). hadolint is clean, and container-structure-test passes 43/43.
headmesh-sandbox up starts the container through Compose with the §6.3 hardening. It reports healthy with tailscaled logged out, and the unconfigured front doors idle and say why. status and doctor work.
Against the running container, tools/list (31 tools), exec, session_* and fs_* pass over the unix socket, and over HTTP with a bearer token. Both protocol versions work: 2026-07-28 stateless and the 2025-11-25 handshake (tests/e2e).
Acceptance, route mcp and route ssh (run inside the container, phase 1, then phase 2 from a new process):
Checks 1–3 pass: uid 1000, Ubuntu 26.04, the file hash matches the host's copy, and the dependency runs.
Check 5's mechanics pass: the session is still running after the reconnect, and the marker exists.
Checks 4 and 5 still fail because the node isn't enrolled yet.
acceptance recreate passes 5/5: home and ~/.bash_history persist, the boot identity changes, and old sessions report lost (container restarted at …). The tailnet identity part was skipped (not enrolled).
YOLO:
It is refused without a fresh backup record.
With one, it starts with the per-subtree read-only /host. Writes fail even as root, propagation is private, /etc/shadow reads as 0 bytes, ~/.ssh is masked, and the host tailscaled state and Docker data-root are left out.
It halts itself at the TTL, with an audit entry, and the next up is Regular.

Spike outcomes are in docs/adr/spike-t0{1,2,3,7,8}-*.md and docs/adr/spike-t16-*.md. Other implementation decisions are in docs/adr/0001-sandbox-implementation-decisions.md.

Security findings to act on

Install the egress firewall before enrolling (host/firewall, step 1 below). A Docker bridge container can otherwise reach whatever the host can: its LAN, its own services and, on a host that is itself a tailnet node, that tailnet. Host-specific findings are in the internal ops notes.
YOLO shows the host read-only. That includes data directories and certificates, wherever file permissions allow. Agents run as uid 1000; root-only files stay unreadable to them, but tailscaled and the runner run as root in the container. Add anything sensitive to [mounts] extra_denylist: denylisted subtrees are left out of /host.
Inside the sandbox, UV_PROJECT_ENVIRONMENT=.venv-sandbox, so uv never rebuilds a project's host .venv against container paths. Make sure each project's .gitignore covers .venv-sandbox (or .venv*).

Quick start (host)

cd /mnt/storage/projects/headmesh/sandbox

go build -o ~/.local/bin/headmesh-sandbox ./cmd/headmesh-sandbox docker buildx bake -f image/docker-bake.hcl sandbox-local # headmesh-sandbox:dev headmesh-sandbox init # /mnt/storage/headmesh/sandbox $EDITOR /mnt/storage/headmesh/sandbox/config/sandbox.toml # image = "headmesh-sandbox:dev" until GHCR has a release headmesh-sandbox scan-secrets # review, then --apply headmesh-sandbox token create claude-code-mac > ~/.config/headmesh/sandbox-token headmesh-sandbox render --diff headmesh-sandbox up headmesh-sandbox status headmesh-sandbox doctor

Secrets live in /mnt/storage/headmesh/sandbox/secrets/ , mode 0600; an empty file means that front door is off. They are never mounted. The CLI passes them to docker compose through the environment, and Compose copies each one into the container as root:root 0400 (spike T-1).

Steps that need Aaryn

Each step needs sudo, a production change or an account. None of them has been done.

1. Host (sudo)

Install the egress firewall and the home backup units, then run a first backup. The exact commands are in host/README.md. Check the result with headmesh-sandbox doctor; it should show egress firewall ✓ and home backup ✓.
Install restic (plan §5.3). Sleep targets are already masked (doctor checks this).

2. Headscale policy (production ACL change; maintenance window)

This builds on plan §5.2 and §6.6. Add the tags and grants to api/infra/headscale/policy.hujson in the Xcelsior repo. Run headscale policy check first; the policy tests must pass.

"tagOwners": { "tag:sandbox": ["group:admin"], "tag:sandbox-yolo": ["group:admin"] },

"grants": [ // Regular: only the private services you list (keep sandbox.toml [mode.regular] reach in sync). { "src": ["tag:sandbox"], "dst": ["tower-server"], "ip": ["tcp:11434"] }, { "src": ["tag:sandbox-yolo"], "dst": ["*"], "ip": ["*"] }, ], "ssh": [ { "action": "accept", "src": ["xcelsior@"], "dst": ["tag:sandbox", "tag:sandbox-yolo"], "users": ["agent"] }, ],

xcelsior@ must mean Aaryn's own devices only. That's true once the provider hosts are tagged (§5.2).

3. Enroll the node

# On prod-hetzner: a single-use pre-auth key that carries the tag (Headscale 0.29.6).

sudo headscale preauthkeys create --user --tags tag:sandbox --expiration 1h

On the ASUS: store it and recreate.

install -m 600 /dev/stdin /mnt/storage/headmesh/sandbox/secrets/ts_authkey # paste, then Ctrl-D headmesh-sandbox recreate headmesh-sandbox status # tailnet Running, node asus-sandbox, dns-check ok

The key alone sets the tags. --advertise-tags is never passed, because Headscale rejects it with a tagged key (spike T-8). tailscale-up checks the enrolled tags against TS_TAGS instead.
tailscale up runs with the key only while no state exists, so later restarts never re-authenticate. Tagged nodes don't expire. Clear the key file after enrollment.
YOLO is a separate node (asus-sandbox-yolo, tag:sandbox-yolo) with its own state directory. Enroll it the same way, with a tag:sandbox-yolo key, during the first up --yolo.

4. Front doors

MCP over the tailnet (Claude Code, any MCP client):

headmesh-sandbox token create claude-code-mac          # prints hms_… once

claude mcp add --transport http sandbox http://asus-sandbox.mesh.xcelsior.ca:8780/mcp \ --header "Authorization: Bearer hms_…"

Tokens are scoped (sandbox:read|exec|write|admin) and can be revoked: headmesh-sandbox token revoke claude-code-mac takes effect within seconds. OAuth (RFC 9728 metadata is already served at /.well-known/oauth-protected-resource/mcp) arrives with the Headmesh authorization server in M3.

Claude self-hosted runner (plan §7.1):

Turn on "Allow self-hosted environments" in claude.ai admin settings.
Put the environment secret in secrets/claude_env_secret, and fill secrets/github_token with a fine-grained PAT.
Set [entrypoints.claude_runner] enabled = true, then run headmesh-sandbox up.

The runner runs as root. Every session goes through claude-session, which drops to agent with setpriv, so sessions can't read the secret (spike T-1). The checkout hook links repos mapped in [repos] to the shared working copy, on main. One live check is still pending: what the runner puts in the sessions' environment.

Claude Remote Control (plan §7.2):

Set [entrypoints.claude_rc] enabled = true, then run headmesh-sandbox up.
Run headmesh-sandbox shell, then claude auth login (a full claude.ai login), trust /home/agent, and run claude remote-control once to answer "Enable Remote Control? y".
Run headmesh-sandbox recreate.

Never set DISABLE_TELEMETRY, DO_NOT_TRACK, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or DISABLE_GROWTHBOOK: Remote Control refuses to start with any of them (spike T-2). Whether it restarts on its own without a TTY still needs checking after this login.

Codex over Tailscale SSH (plan §7.3):

This needs the ssh rule from step 2.
In Codex desktop, add the remote host agent@asus-sandbox.mesh.xcelsior.ca.
Smoke test: ssh agent@asus-sandbox.mesh.xcelsior.ca codex --version.
Tailscale SSH works inside the container (spike T-3). Codex desktop itself is untested.

OpenAI Secure MCP Tunnel (plan §7.4):

In the Platform, create a Tunnel and a runtime key with Read+Use only. Put the key in secrets/openai_tunnel_key and the id in [entrypoints.openai_tunnel] tunnel_id. Set enabled = true, then run up.
Create a token for the tunnel route: headmesh-sandbox token create chatgpt-tunnel --route tunnel (exec ≤ 110 s, responses ≤ 8 MiB).
In ChatGPT: Plugins → Add custom MCP server → Connection: Tunnel, with bearer auth using that token.

Codex `exec-server` via the Agents API (plan §7.6):

Store the application key outside the sandbox. The CLI runs as you, so use secrets/openai_app_key (0600; never mounted, and denylisted from YOLO's /host). /etc/headmesh/openai-app.key is also accepted if you can read it.
Put the environment key (Agents tab, every other permission None) in secrets/openai_env_key.
Run:

   headmesh-sandbox agent run --provider openai --repo xcelsior \

--prompt-file sandbox/tests/acceptance/prompt.md

The executor runs as agent in the repo with --linux-sandbox-pid-namespace inherit and full access inside the container. Codex's bubblewrap sandbox can't run under the container's seccomp and AppArmor profiles, so the container is the boundary (spike T-16). The environment key reaches the executor through stdin, and the transcript goes to logs/agent-runs/ .jsonl.

5. Acceptance (plan §6.15)

headmesh-sandbox acceptance run --route mcp \

--url http://asus-sandbox.mesh.xcelsior.ca:8780/mcp --token-file ~/.config/headmesh/sandbox-token ssh agent@asus-sandbox.me

Only the beginning is shown; read the rest in the repo

Headmesh Agent Sandbox

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Values you fill in

Which apps can use it

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Developer toolsi

Common questions

Alternatives

REA

Netdata

Front-End Checklist

README from the maker

Headmesh agent sandbox

What's verified (2026-10-27)

Security findings to act on

Quick start (host)

Steps that need Aaryn

1. Host (sudo)

2. Headscale policy (production ACL change; maintenance window)

3. Enroll the node

On the ASUS: store it and recreate.

4. Front doors

5. Acceptance (plan §6.15)