dotunnel

English | 한국어

dotunnel is a self-hosted stdio MCP server and helper for connecting a Linux server to a private Secure MCP Tunnel. Its base API exposes seven bounded workspace file/task tools. An operator may optionally configure agent supervision for registered Herdr and/or tmux targets, adding eight shared agent_* tools. It is not a hosted service or public MCP endpoint.

Requirements

• Non-root Linux account; Python 3.11+ with python3, venv and pip.

• curl and sha256sum for the one-line installer; no uv required.

• ChatGPT/Platform eligibility and permissions, an OpenAI Tunnel ID and restricted runtime key, and the official tunnel-client are prepared separately. dotunnel cannot grant access or supply these.

Related MCP server: Portal

Install

Install the current release without a GitHub account:

curl -fsSL https://raw.githubusercontent.com/junited31/dotunnel/main/install.sh | sh

The installer verifies the pinned wheel before pip installs it in $HOME/.local/share/dotunnel/venv, then exposes $HOME/.local/bin/dotunnel. It does not run setup from piped stdin, install the official client, or change accounts, permissions, keys, Tunnel settings, shell startup or services. It refuses to overwrite an existing install or unrelated launcher; use dotunnel update for an existing installation. If dotunnel is not on PATH, add $HOME/.local/bin yourself or invoke it by absolute path.

Prefer downloading the wheel yourself? See manual installation.

Configure

Setup requires an interactive terminal. Separately install and checksum-verify the official client; obtain the required account permissions, Tunnel ID and Restricted runtime key. dotunnel cannot create these for you.

"$HOME/.local/share/dotunnel/venv/bin/dotunnel" setup --directory "$HOME/.dotunnel-setup"

Setup creates a private profile/config/key outside the workspace. In 0.1.6, interactive setup also asks which workspace paths MCP file tools may read or write. Both rule lists start empty, and write access must stay within read access. You review and explicitly approve the permission summary before key entry or generated files. Tunnel connection start and live-agent scope approval are separate choices; see the detailed guide.

Commands

Optional Herdr/tmux agent supervision

Supervision is disabled unless the trusted configuration contains a fixed supervision registry and its private state has been explicitly initialized. It adds eight shared agent_* tools (15 MCP tools total). From 0.1.6, interactive setup can select project action ceilings and per-profile start/prompt/answer rights; new grants start empty. Setup grants do not approve runtime scopes or start agents. Live profiles default to the compatible executable policy, which may allow writable or shared-inode executable code; strict is available. Live agents retain their native OS authority and are not run in the fixed-job Bubblewrap candidate. See the detailed guide for scope and identity limits.

Available in 0.1.5. Installing the package does not configure or activate supervision.

Optional common adapter runner

The standalone runner uses the existing seven file/task MCP tools. Install it separately from reviewed source and explicitly register one fixed task; base installation and setup do not enable it. Mutations require local interactive consent bound to the exact request and private registry profile. Durable replay returns the recorded outcome without redispatch; ambiguous effects remain outcome_unknown.

That runner ships no Herdr, Orca, tmux or provider adapters. Core supervision is a separate feature; it supports configured Herdr/tmux backends, while Orca support remains unavailable.

Safety

• Run as a non-root account, preferably a dedicated account without broad groups or sudo. The project does not create accounts or change permissions.

• Keep the installed program, trusted configuration/credentials and writable workspace separate. Setup starts with tasks: [] and empty MCP read/write rules; credentials are stored outside the workspace.

• Fixed tasks run with the MCP process account's full OS permissions. A fixed command or workspace is not a sandbox; review task code and side effects.

• stdio MCP has no separate user authentication. Restrict who can reach it; allowed files and task output may contain sensitive data.

• Optional fixed CLI jobs require Bubblewrap and use allowlisted candidate copies; edits are not applied to source files automatically. The native CLI still runs as the same user, can read referenced credentials and shares provider networking.

• Live Herdr/tmux agents do not use that Bubblewrap candidate boundary. They retain the native agent's OS filesystem and authentication authority; MCP file rules do not confine them. Compatible live executable policy accepts a writable/shared-inode code risk, not a security guarantee.

• curl | sh executes the repository's installer code as your user. Trust/review that script; the wheel checksum does not make the shell script itself a trust-free download.

• For source development, enable the pre-commit secret guard; keep runtime/key files outside the checkout.

Detailed guide · Design · Example config · License