Desktops Commander Sandbox

Desktops Commander Sandbox is an MCP gateway for selecting a registered Mac, Windows, or Linux machine and working on one of its registered projects through an isolated, Git-versioned workspace.

It is designed for a safer workflow than forwarding a general-purpose desktop-control server directly to an AI client:

• clients select only administrator-registered machines and projects;

• source directories are copied into a fresh sandbox and never mounted writable;

• every modification is visible as a Git diff and can be checkpointed locally;

• path traversal, absolute paths, symbolic links, arbitrary backend URLs, and arbitrary source roots are rejected;

• deterministic policy/scanner failures are authoritative;

• optional AI review can escalate to a human, but cannot override a deterministic denial;

• version 0.1 produces a conflict-aware publish plan and intentionally does not write changes back to source.

Status

This is an early security-focused release. The included local filesystem provider is intended for development and evaluation. Production isolation is designed around Kubernetes SIG Agent Sandbox with a gVisor RuntimeClass; deployment examples live in deploy/agent-sandbox/.

Related MCP server: hermes-local-hands

Quick start

Requirements: Node.js 22.15 or newer and Git.

npm install
cp config/machines.example.json config/machines.json
# Edit config/machines.json with absolute administrator-controlled paths.
export DESKTOPS_COMMANDER_TOKEN="replace-with-at-least-32-random-characters"
npm start

The Streamable HTTP MCP endpoint is http://127.0.0.1:8790/mcp. Bindings are intentionally loopback-only; expose it through an authenticated tunnel or reverse proxy instead of changing the listener to a public interface.

Environment variables:

• DESKTOPS_COMMANDER_CONFIG: configuration file path;

• DESKTOPS_COMMANDER_PORT: loopback port;

• DESKTOPS_COMMANDER_TOKEN: optional bearer token, at least 32 characters;

• DESKTOPS_COMMANDER_SANDBOX_ROOT: override the sandbox data directory.

Legacy HCO_MCP_* environment names are accepted for migration only.

MCP tool surface

The secure sandbox mode exposes:

• machines_list, machines_health, projects_list;

• sandbox_create, sandbox_list, sandbox_status;

• sandbox_read, sandbox_write, sandbox_diff;

• sandbox_commit, sandbox_discard;

• sandbox_review, sandbox_publish_plan.

Raw process execution, host filesystem writes, keychain access, and Desktop Commander configuration mutation are not exposed in sandbox mode.

The old pass-through router remains available as "mode": "legacy" for migration. It forwards downstream tools and is not the recommended public connector.

Review adapters

Trivy and local-review are optional external programs. Adapters use direct process execution without a shell, a bounded timeout/output buffer, and a minimal environment. Scanner output is represented by byte count and SHA-256 digest by default; exposeOutput: true opts into a redacted preview. When deterministic review is enabled, a finding or unavailable scanner blocks publication planning; local AI review is advisory and can require human review.

An OPA decision endpoint can be set as policy.opaUrl. OPA errors fail closed. The example Rego policy is in policy/desktops-commander.rego.

Testing

npm test

Security and attribution

See SECURITY.md for the security model and responsible disclosure, and NOTICE.md for upstream attribution. The project is licensed under Apache License 2.0.

Copyright 2026 Wenhan Hu.