tarides/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
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?
| | Bash tool | sudo-proxy MCP |
|---|---|---|
| Privilege escalation | Not possible | sudo with human approval |
| Human review | None — executes immediately | TUI Y/N gate on every command (privileged and unprivileged) |
| Timeout | Up to 10 min, no user prompt | 60 s TUI prompt + configurable overall timeout |
| Remote hosts | Not supported | SSH tunnel with TUI on remote terminal |
| Environment | Inherits shell env | Sanitized allowlist only |
| Audit trail | None | Server logs each request (with -v) |
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.
It is deliberately **not** a way to run *un*privileged commands with less
scrutiny than the Bash tool: an unprivileged command targeting the local
machine is refused and delegated back to the Bash tool (which already applies
your permission rules), and loopback aliases like 127.0.0.1 cannot dodge that.
sudo-proxy handles privilege escalation and commands on remote hosts; there,
unprivileged commands are gated the same way, and the per-command gate is only
relaxed if you deliberately mark a host eligible in hosts.json *and* confirm
once per session (a grant that is never persisted). See
REVIEWING.md invariant **G7**.
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:
- **Per-command human approval** — a single-keypress Y/N TUI gate on
every command, privileged and unprivileged, with no way to bypass it.
- **Real privilege escalation** via sudo — installs packages, edits
system files, manages services; not limited to read-only diagnostics.
- **Local and remote over one flow** — the same approval TUI whether the
command runs on this machine or on a remote host over an SSH tunnel.
- **Stores no secret** — the sudo password is typed live into the
terminal; nothing is cached, encrypted-at-rest, or written to disk.
- **Explicit argv** — commands are passed and displayed exactly as they
run, with no shell-string interpolation.
- **Sanitized environment** — a fixed allowlist, not the inherited shell
environment.
- **Audit trail** — each request is logged by the server (-v).