The problem
An agent that manages infrastructure normally needs your ssh keys or your kubeconfig. Once it holds them, whatever the credential allows, the agent can do, and you find out afterwards, if at all. ksproxy moves the credential to your side: you open the connections, and the agent only gets a narrow, logged tool interface.
How it works
- You run
ksproxy startin a terminal, pick the targets, and leave it running. It opens the ssh connections (ssh may ask for your password or key passphrase in that terminal) and thekubectl proxyprocesses. A third kind,local, lets the agent run allowlisted commands in a folder on your own machine; opening it only checks that the folder exists, can be resolved, and is not your home directory, the root, ksproxy's own folders or a folder holding an inventory kubeconfig. - Your agent talks to the built-in MCP server,
ksproxy mcp. Each call is checked against the target's allowlist, and refused unless a rule allows it. If you turn on model review for a target, a model can also approve a command that no rule matches. - Every call and event appears in your terminal as it happens. Ctrl-C closes every connection and stops every proxy.
What the agent gets
Four MCP tools. Timeouts are 1 to 600 seconds (default 60), and stdout and stderr are each capped at 256 KiB.
| Tool | What it does |
|---|---|
list_targets | Lists the targets you opened, with their descriptions and allowed rules. |
ssh_exec | Runs a command on an ssh target: server, command, optional timeout_seconds. |
kubectl | Runs kubectl against a cluster through its local proxy: cluster, args, optional timeout_seconds. |
local_exec | Runs an allowlisted command on your machine in a local target's folder: target, command, optional timeout_seconds. No shell is involved. A wildcard in a local rule matches only plain names and paths, never a flag (flags and anything else must be written literally in the rule), and each plain value, links followed, must stay inside the folder. A file outside it is reachable only if you write it literally into a rule (cat /etc/hosts). Paths you list in protect, and names that usually hold secrets, are never matched by a wildcard. |
You decide what it may run
Targets live in ~/.config/ksproxy/inventory.json. Each has an allow list; a target with no allow refuses everything.
{
"ssh": [
{
"name": "web1",
"host": "web1.example.com",
"description": "production web box",
"allow": ["systemctl status *", "journalctl -u myapp ...", "df -h"]
}
],
"kubernetes": [
{
"name": "lab",
"kubeconfig": "~/.kube/lab-agent.yaml",
"proxyPort": 8001,
"manifestRoots": ["~/projects/lab/manifests"],
"description": "lab cluster",
"allow": ["get ...", "describe ...", "logs ...", "rollout status ...", "apply -f *"]
}
],
"local": [
{
"name": "infra",
"cwd": "~/projects/infra",
"description": "terraform repo",
"allow": ["git status", "git log --oneline -n * ...", "terraform plan", "ls -l ..."]
}
]
}
A rule is whitespace-separated tokens matched against the command's arguments:
- A literal matches an argument equal to it.
df -hallows exactlydf -h. *matches exactly one argument that does not start with-.systemctl status *allowssystemctl status nginx....matches zero or more arguments of any shape, and only as the last token.journalctl -u myapp ...allowsjournalctl -u myapp --since today -n 50.
ssh commands are split into tokens and every character is checked: quotes, ; | & $, backticks, redirects, globs and newlines are refused outright, so no shell syntax reaches the remote host. Kubernetes arguments pass a fixed verb-and-flag allowlist first, which refuses exec, port-forward, credential-flags and secret resources whatever your rules say. Files given with -f must sit inside manifestRoots.
Try a rule without opening anything:
ksproxy check ssh web1 systemctl status nginx
ksproxy check kube lab get secrets
ksproxy check local infra git status
Optional model review
When no rule matches a command, ksproxy can ask a model if it fits a policy you wrote. It is off by default and set per target, and it works with any OpenAI-compatible provider. Anything but a clean approval is a refusal, and the tool's reply does not show the model's reason.
{
"reviewers": {
"groq": {
"baseUrl": "https://api.groq.com/openai/v1",
"model": "<model id>",
"keyEnv": "GROQ_API_KEY"
}
},
"ssh": [
{
"name": "web1",
"host": "web1.example.com",
"allow": ["uptime", "df -h"],
"review": {
"reviewer": "groq",
"policy": "read-only diagnostics, no restarts, no file contents"
}
}
]
}
The model judges the words of a command, not what it does, so keep write commands on the allow list. The README lists the limits.
You see everything
ksproxy start prints one line per agent call and per event, and ksproxy log shows the same lines later. A refused call shows a short reason; the agent receives the full explanation with the allowed rules. Every call is also kept as a JSON line in logs/audit.log in the state folder (command and decision, not output). The log is rotated at 5 MiB and the 5 newest old files are kept.
12:18:40 ssh web1 OPENING web1
12:18:41 ssh web1 UP
12:18:43 -- session READY 2 targets, pid 31973
12:19:19 ssh web1 ok 0.1s uptime
12:19:20 ssh web1 DENIED cat /etc/shadow [not on allowlist]
12:19:23 kube lab DENIED get secrets -A [secret resource]
12:41:00 -- session CLOSING Ctrl-C
12:41:01 -- session CLOSED 3 calls: 1 ok, 0 failed, 2 denied
Quick start
Write a sample inventory. It never overwrites an existing file.
ksproxy init
Edit it: your own targets, and an allow list for each.
$EDITOR ~/.config/ksproxy/inventory.json
Start a session, pick targets, and leave the terminal open. Ctrl-C ends it.
ksproxy start
Add the MCP server to your agent once. The summary printed by start shows the exact line; for Claude Code it has this shape:
claude mcp add ksproxy -- <node> <path to bin/ksproxy.js> mcp
Check the session at any time.
ksproxy status
What it does not do
The allowlist is a second lock; the first is that the agent never holds a credential. These limits are in the project README and matter when you decide what to allow.
- The allowlist binds only the MCP path. An agent that also has an unrestricted local shell can use the ssh sockets and proxy ports directly.
- An agent that can edit the inventory or the session files can widen its own rules.
- A rule is only as safe as the program it allows.
find ...,awk ...,vim,lessandsudo ...can run other commands. - Command output is returned as-is. A program that prints a secret leaks it to the agent. Replacing local paths and proxy addresses in the output is not redaction.
- The remote user's permissions and Kubernetes RBAC remain the boundary. A workload the identity may create, such as a Pod that mounts a Secret or a service-account token, is not inspected by this tool.
- With
"allow": "any"on an ssh target, the command is sent as written, so pipes and redirects work. Local targets refuse"any". - A local command runs as you, on the machine that holds your keys, so give local targets the shortest allow list of all. The folder check looks at arguments only: a program can still read other files by itself, and some programs (
git,make,npm,terraform plan) run code they find in the folder. The full list is in docs/LOCAL-TARGETS.md. - Protected locations are those recorded by
ksproxy start(its own state and configuration folders and every inventory kubeconfig), not whatever the agent host's environment says. Programs are found through the absolute entries of yourPATH; relative entries and entries inside any local target's folder are dropped. The folder path is replaced in output, also when its letter case differs; a path cut by the 256 KiB output limit may be only partly replaced. - After a SIGKILL or power loss, connections and proxies it opened can outlive it until the next
ksproxy startcloses them. - Out of scope: creating server users, sudoers rules, RBAC, tokens or kubeconfigs; file transfer; interactive shells; port forwarding for the agent; redacting secrets from output; Windows.
Reliable setups for the agent side are an agent with no general shell, or one whose shell runs in a sandbox that cannot read ~/.ksproxy or ~/.config/ksproxy and cannot reach local sockets and ports.