opsgate

opsgate

The safety gate between AI agents and your servers.

An MCP server that lets Claude, Cursor, or any AI agent operate real infrastructure — without handing it a root shell.

What it looks like · 30-second try · Break it yourself · Tools · Security model · Contributing

---

What it looks like

You ask a question. The agent investigates with read-only tools and answers.

You: Something's listening on port 8000 on my server and I don't remember what. Check it.

▸ listening_ports(host: "hetzner")

Netid State Recv-Q Send-Q Local Address:Port Process tcp LISTEN 0 511 0.0.0.0:443 users:(("nginx",pid=249619),…) tcp LISTEN 0 511 0.0.0.0:80 users:(("nginx",pid=249619),…) tcp LISTEN 0 4096 0.0.0.0:22 users:(("sshd",pid=237597),…) tcp LISTEN 0 151 127.0.0.1:3306 users:(("mysqld",pid=237695),…) tcp LISTEN 0 5 127.0.0.1:8000 users:(("python3",pid=237608),…)

▸ service_list(host: "hetzner", state: "running")

docker.service loaded active running Docker Application Container Engine mysql.service loaded active running MySQL Community Server nginx.service loaded active running A high performance web server… php8.3-fpm.service loaded active running The PHP 8.3 FastCGI Process Manager pm2-root.service loaded active running PM2 process manager

Claude: Port 8000 is a bare python3 process (pid 237608) bound to localhost only, so

it isn't reachable from outside. It's not managed by systemd — no unit owns it — which

means it won't survive a reboot. It's most likely something started by hand in a shell.

Now something that changes state. In operate mode the agent cannot just do it:

You: OK, nginx config changed. Reload it.

▸ nginx_test(host: "hetzner")

nginx: configuration file /etc/nginx/nginx.conf test is successful

▸ nginx_reload(host: "hetzner")

┌─ opsgate: approval required ─────────────────────────────────┐ │ allow nginx_reload on host "hetzner"? │ │ │ │ The nginx configuration passed validation. │ │ This will reload nginx. │ │ │ │ Command: 'nginx' '-s' 'reload' │ │ [ Approve ] [ Deny ] │ └─────────────────────────────────────────────────────────────┘

You click Deny, and nothing happens — the agent is told the operator refused. Approve, and it runs and lands in the audit log. Either way you saw the exact command first.

*(Tool output above is real output from a live server; the prompt is rendered by your MCP client, so it looks however that client draws it.)*

Try it in 30 seconds (no server needed)

opsgate runs with no config file at all — local machine, read-only:

go install github.com/polymatx/opsgate/cmd/opsgate@latest

opsgate serve

opsgate v0.1.3 | mode=observe | default_host=local | audit=~/.opsgate/audit.jsonl

That's it. No config, no SSH, and it defaults to observe — so it can read your disk usage and journal, and it will refuse to change anything:

▸ disk_usage()          → works

▸ service_restart(...) → Refused by opsgate policy: host is in observe mode

Point your client at it and ask "what's using disk space on this machine?" When you're ready for real hosts, opsgate init writes a starter config to ~/.opsgate/config.yaml.

Which clients can reach it

opsgate runs on your machine (or on the server itself) and holds your SSH key, so the transport you need depends on where your client actually executes:

If your client reports it has no access to your servers, it is almost certainly one of the sandboxed kind. Serve over HTTP instead of stdio.

Before publishing that endpoint, read the warning there: it puts an infrastructure-management API on whatever network you expose it to.

Wire it up to your client

Claude Code

As a plugin: the MCP server, a server-ops skill that teaches the agent to diagnose before it acts and to treat refusals as final, and a read-only /opsgate:health-check [host] command.

/plugin marketplace add polymatx/opsgate

/plugin install opsgate@opsgate

The plugin runs opsgate serve, which reads ~/.opsgate/config.yaml (opsgate init writes a starter one). It never reads a config from the project you have open. Or add just the MCP server:

claude mcp add opsgate -- opsgate serve --config ~/.opsgate/config.yaml

Claude Desktop / Cursor ( claude_desktop_config.json or .cursor/mcp.json )

{

"mcpServers": { "opsgate": { "command": "opsgate", "args": ["serve", "--config", "/absolute/path/to/opsgate.yaml"] } } }

</details>

Docker ( ghcr.io/polymatx/opsgate )

For hosts reached over SSH. Inside a container, local is the container itself.

docker run -i --rm \

-v ~/.opsgate:/root/.opsgate \ -v ~/.ssh:/root/.ssh:ro \ ghcr.io/polymatx/opsgate serve

The image is also how opsgate is listed in the MCP Registry as io.github.polymatx/opsgate.

Any client, over HTTP (needed for cloud/sandboxed clients)

http:

addr: "127.0.0.1:8080" auth_token: "a-long-random-token" # sent as: Authorization: Bearer

opsgate serve --http 127.0.0.1:8080

The tidiest deployment is to run opsgate on the server it manages — then it needs no SSH key at all (default_host: local) — behind a TLS-terminating reverse proxy:

client ──HTTPS──▶ nginx / Caddy ──▶ 127.0.0.1:8080  opsgate

• Bearer token

opsgate refuses to serve HTTP on a non-loopback address unless http.auth_token is set.

[!WARNING]

Exposing this endpoint puts an infrastructure-management API on that network, and the

bearer token becomes the only thing protecting it. If you must publish it: keep

mode: observe, generate 32+ bytes of randomness for the token, require TLS, and add an

IP allowlist at the proxy. Binding it to a VPN interface (WireGuard, Tailscale) instead of

the public internet is strictly safer — your own devices reach it, nobody else can.

Note also that operate mode expects a human who can answer an approval prompt. An

unattended HTTP deployment usually means observe.

The problem this solves

Letting an AI agent run your servers today means giving it exec(" ") over SSH. The usual mitigation is a denylist of commands that *look* dangerous.

That does not work. Denylists are guesswork against an adversary with infinite phrasings:

rm -rf /                              →  blocked

r''m -rf / → not blocked echo cm0gLXJmIC8K | base64 -d | sh → not blocked

And "dangerous-looking" isn't even the hard part. systemctl restart nginx is a perfectly ordinary command that is catastrophic at 3pm on Black Friday.

The approach

opsgate does not filter strings. It never gives the agent a string to fill in.

The agent gets 25 typed tools — service_restart(name), docker_logs(container), journal_tail(unit, since, priority) — and opsgate builds the command itself as an argv array. There is no shell to inject into, because no shell string is ever assembled from agent input.

// What opsgate does — the name is one argv element, whatever it contains

argv := []string{"systemctl", "restart", in.Name}

// What it never does argv := []string{"sh", "-c", "systemctl restart " + in.Name}

Send nginx; rm -rf / as the service name and systemctl receives it as a single literal argument and fails as an unknown unit. Nothing else runs.

Every call then passes through four gates:

flowchart LR

A[Agent calls a tool] --> B{Policy mode + allowlist} B -->|deny| X[Refused

• audited] B -->|allow| D[Build argv] B -->|needs approval| C{Human} C -->|deny| X C -->|approve| D D --> E[Execute] E --> F[Audit

hash-chained]

The default mode is observe. Out of the box, an agent can diagnose your servers and change nothing.

Break it yourself

Don't take the claims on faith. Start opsgate in observe mode with files.allow_paths: [/var/log] and try these — every one is refused, and the refusal is logged:

Then confirm nothing landed:

$ ls /tmp/pwned

ls: cannot access '/tmp/pwned': No such file or directory

$ opsgate audit verify audit chain OK: 6 records verified in ~/.opsgate/audit.jsonl

(Six, not seven: shell_exec isn't a registered tool at all when it's disabled, so that call is rejected by the protocol before it reaches a gate.)

Found something that *does* get through? That's a security bug — please [report it](SECURITY.md