Nodus Desktop Sandbox

Nodus Desktop Sandbox lets an MCP-compatible agent work inside an explicitly authorized folder on another computer. It is a single Go binary with an embedded Tailscale node, so neither computer needs the Tailscale application installed and traffic does not pass through Nodus Cloud.

The host controls access. Workspaces start read-only, writes and command execution are opt-in, and every agent connection has a revocable pairing token.

Install

Install the cross-platform npm package:

npm install -g @nodus-ai/desktop@preview
nodus-desktop version

The npm package contains the macOS, Linux, and Windows binaries and does not download a separate runtime during installation.

Alternatively, download a binary from GitHub Releases or build it with Go 1.26.5 or newer:

go build -o nodus-desktop ./cmd/nodus-desktop

Host setup

Add a folder. It is read-only by default:

nodus-desktop workspace add ~/projects/example --name example
nodus-desktop workspace list

Optionally enable writes and command execution:

nodus-desktop workspace grant ws_EXAMPLE --write --exec

Start the sandbox:

nodus-desktop serve

On first use, the embedded Tailscale node prints a login URL. Open it and approve the node. Headless environments can set TS_AUTHKEY or pass --auth-key.

Create a pairing code for one workspace:

nodus-desktop pair create --workspace ws_EXAMPLE

Treat the printed code as a secret. Revoke it at any time:

nodus-desktop pair list
nodus-desktop pair revoke pair_EXAMPLE

Agent setup

Copy the same binary to the machine or container running the agent. Configure a stdio MCP server equivalent to:

{
  "command": "/path/to/nodus-desktop",
  "args": ["mcp"],
  "env": {
    "NODUS_DESKTOP_PAIR": "PAIR_CODE"
  }
}

The connector also prints a Tailscale login URL on first use. Approve it in the same tailnet as the host. No Nodus account or Nodus API key is involved.

MCP tools

• workspace_list lists only workspaces authorized by the pairing.
• directory_list lists a directory beneath a workspace root.
• file_read reads UTF-8 text files up to 4 MiB.
• file_write atomically writes UTF-8 text files up to 4 MiB when enabled.
• command_run executes a program with an argument array when enabled. It does not invoke a shell unless the caller explicitly runs one.

Command execution defaults to a two-minute timeout, caps at ten minutes, and truncates stdout or stderr after 1 MiB.

Security model

• The embedded tailnet provides encrypted transport and device identity.
• Pairing tokens add application-level authorization and are stored only as SHA-256 hashes on the host.
• Each pairing names its allowed workspaces; remote calls cannot add folders or elevate permissions.
• Go's os.Root confines file operations and rejects path traversal and symlink escapes.
• Removing a workspace or revoking a pairing takes effect on the next MCP request.
• The host intentionally exposes no public listener or Tailscale Funnel endpoint.

This is not an isolation boundary against programs already trusted to execute inside a writable workspace. A command can access anything available to the host user unless the operating system separately sandboxes that process.

Configuration

State is stored under the operating system user configuration directory in nodus-desktop/. The config file is created with user-only permissions. Host and connector Tailscale identities are stored separately so one binary can serve both roles.

License

Apache-2.0. See LICENSE and THIRD_PARTY_NOTICES.md.