sudo-proxy MCP server

sudo-proxy

An MCP server that lets an agent run privileged, mutating commands —

locally or over SSH — with a human keypress required on every one and

no credential ever stored.

Privileged command execution proxy with an MCP server for AI agent integration. Receives requests over a Unix socket, shows a single-keypress TUI prompt for human approval, then escalates via sudo. Configure sudo-proxy-mcp in Claude Code or any MCP client and the model can run privileged commands — with explicit human approval on every one.

⚠️ Not yet independently audited. The security assurance in this repo is

self-produced. Security reviewers: REVIEWING.md is a 15-minute

on-ramp — the falsifiable claims, the trust boundary, and where we have no

assurance. Reporting: SECURITY.md.

Architecture

AI model ──► sudo-proxy-mcp ──► Unix socket ──► sudo-proxy ──► TUI Y/N ──► sudo
             (MCP server)         │
                                  │
                            local socket, or SSH tunnel
                        (start_server spawns sudo-proxy --host
                         which sets up the tunnel and remote
                         server)

The TUI prompt asks for approval (single keypress), then sudo handles privilege escalation. The password prompt appears in the same terminal. This flow is identical for local and remote hosts. A non-privileged mode runs commands directly as the current user, still behind the same Y/N gate — see docs/usage.md.

Why not just use the Bash tool?

sudo-proxy fills the gap when a model needs to install packages, edit system files, manage services, or run any other command — with the human always in the loop, even when Claude Code is run with --dangerously-skip-permissions.

For how this relates to mcp-firewall, sandboxing, polkit, doas, and other neighboring tools, see docs/comparison.md.

Features and non-features

What sudo-proxy does:

every command, privileged and unprivileged, with no way to bypass it.

• Per-command human approval — a single-keypress Y/N TUI gate on

system files, manages services; not limited to read-only diagnostics.

• Real privilege escalation via sudo — installs packages, edits

command runs on this machine or on a remote host over an SSH tunnel.

• Local and remote over one flow — the same approval TUI whether the

terminal; nothing is cached, encrypted-at-rest, or written to disk.

• Stores no secret — the sudo password is typed live into the

run, with no shell-string interpolation.

• Explicit argv — commands are passed and displayed exactly as they

environment.

• Sanitized environment — a fixed allowlist, not the inherited shell

even when the agent's own permission prompts are disabled.

• Audit trail — each request is logged by the server (-v).
• Works under --dangerously-skip-permissions — the human gate holds

What sudo-proxy deliberately does not do:

Shortened. The full README is on GitHub.