sudo-proxy is a privileged command execution proxy with an MCP server for AI agent integration. It accepts requests sent over a Unix socket, displays a single-key confirmation TUI prompt in the terminal for human approval, then executes with sudo privileges. After configuring sudo-proxy-mcp in Claude Code or any MCP client, the model can run privileged commands, but every command must receive explicit human approval.
Purpose
sudo-proxy fills the gap when the model needs to install packages, edit system files, manage services, or run other commands, while always keeping a human in the loop; even when Claude Code runs with --dangerously-skip-permissions, the human approval gate still applies. It is intentionally not meant for running unprivileged commands with less scrutiny: unprivileged commands targeting the local machine are rejected and handed back to the Bash tool (the Bash tool already has your permission rules), and loopback aliases like 127.0.0.1 cannot bypass this. sudo-proxy handles privilege escalation and commands on remote hosts; on remote hosts, unprivileged commands are likewise subject to the gate, and the per-command gate is relaxed only when you deliberately mark a host as eligible in hosts.json and confirm once per session (that authorization is not persisted).
Main capabilities
- Per-command human approval: every command, whether privileged or not, goes through a single-key Y/N TUI gate that cannot be bypassed.
- Real privilege escalation via sudo: install packages, edit system files, manage services, not limited to read-only diagnostics.
- Same flow for local and remote: whether the command runs on the local machine or on a remote host via an SSH tunnel, the approval TUI is the same.
- Stores no secrets: the sudo password is entered live in the terminal, not cached, not stored encrypted, not written to disk.
- Explicit argv: commands are passed and displayed exactly as they will be executed, with no shell string interpolation.
- Environment variable sanitization: uses a fixed allowlist rather than an inherited shell environment.
- Audit log: the server records every request with -v.
- Still works under --dangerously-skip-permissions: even if the agent's ownpermission prompts are disabled, the human gate still applies.
The capabilities it intentionally does not provide include: no storing or managing credentials, no unattended execution or auto-approval mode, not a sandbox, not a policy engine or ACL, not limited to read-only, no hosted service, not a general-purpose remote shell (no persistent interactive sessions, SFTP browser, or cluster management, only gated one-off commands).
Usage
Installing the binary requires a Rust toolchain; prebuilt static binaries are available in Releases.
cargo install --path .
Or get a prebuilt static binary via cargo binstall without compiling:
cargo binstall sudo-proxy
cargo binstall downloads the release archive from GitHub and verifies its minisign signature (public key RWT7gwtBU0v4puI76u0oYwMAT9nmYwGimSOnqJJ+kHExsjTDQj1eZkMW, key ID A6F84B53410B83FB) before installing; a missing or incorrect signature aborts the installation. If you would rather build from source, prefer cargo install.
Point the MCP client at this server—add it to the project's .mcp.json or ~/.claude/claude_desktop_config.json.
Install as a Claude Code plugin: this repository is both a Claude Code plugin and its own marketplace. No manual editing of .mcp.json is needed: the plugin registers the sudo-proxy MCP server and comes with a skill that tells the model to use sudo-proxy only when working with privileges or remotely, to start the server before execution, and to write a clear description for each command so that approval prompts are easy to judge. It does not install the sudo-proxy-mcp binary—that file must already be in your PATH. A tool centered on explicit human consent should not silently install itself.
The model then starts the server (opening a terminal with an approval TUI) and runs commands through it. Each execution shows the exact command in the TUI; press y to approve, press N (default) to deny. For remote hosts, pass host to start_server and execute.
It is listed in the official MCP Registry as mcp-name: io.github.tarides/sudo-proxy.
Applicable scenarios and limitations
Suitable for operations, development environment configuration, remote server management, and other scenarios that require an AI agent to perform privileged system operations but must have human confirmation. Limitations include: the project has not yet undergone an independent audit, and the security guarantees in the repository are self-produced; there is no automatic approval mode, and every command requires a manual keypress; it is not a sandbox, and it grants real privileges; it is not a policy engine, and the human keypress is the policy; it does not support persistent interactive sessions or file transfer. Security reviewers can learn from REVIEWING.md about falsifiable claims, trust boundaries, and what is not guaranteed; for reporting issues, see SECURITY.md.
Documentation and related
docs/install.md covers installation variants, remote deployment, and building from source; docs/mcp.md covers the MCP tools (start_server, execute, status, stop_server, update_host), configuration, and known hosts; docs/usage.md covers CLI flags, unprivileged mode, SSH tunneling, and agent forwarding; docs/protocol.md covers the JSON-line wire protocol over a Unix socket; docs/security.md covers the security model; docs/security-audit.md is a point-in-time audit; docs/threat-model.md is STRIDE and attack trees; docs/formalisation-roadmap.md is the progressive assurance plan; docs/assurance-case.md is the GSN argument. proofs/ contains machine-checked models: the TLA+/PlusCal approval state machine (TLC, Rung 4) and the ProVerif SSH channel model (Rung 4); the Kani bounded proofs are in src/proofs.rs (Rung 3). docs/pkexec.md covers --pkexec mode and polkit authentication caching (not recommended); docs/architecture.md covers the source layout and implementation status; docs/comparison.md covers how sudo-proxy relates to other tools.
Development notes
sudo-proxy was developed with extensive AI assistance from Claude Code. Commits with substantive AI contributions carry a Co-Authored-By trailer identifying the specific model. All design decisions, threat modeling, and the final form of every committed change are reviewed and approved by the human maintainer, who is responsible for the codebase. This disclosure is in line with industry practices for transparency about generative AI involvement in software development, and is not a claim that the project is "AI-generated": the human-in-the-loop principle that the tool enforces at runtime is also the principle on which it was built.
