{"title":"SSH Access via Proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"How an LLM agent runs commands on remote machines safely through an SSH-Proxy API instead of raw SSH keys.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":375,"read_minutes":2,"llm_context":"NEVER hold raw SSH private keys as an LLM. Use an SSH-Proxy HTTP API:\n1) POST /connect?target= → session_id (persistent, survives hours).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → output when done.\n4) Use SFTP endpoints for file up/download instead of cat/heredoc.\nTargets are pre-registered names (e.g. \"vps1\"), not IPs — the proxy is the\nonly place where credentials live.\n","lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# SSH Access via Proxy\n\nAgents need to run commands on remote machines — deploy a container, read a\nlog, fix a config. Handing raw SSH private keys to an LLM is a bad idea:\nkeys end up in context windows, logs and transcripts. An SSH-Proxy solves\nthis: it owns the credentials, the agent only speaks HTTP.\n\n## The Model\n\n```\nLLM ──HTTPS──► SSH-Proxy ──SSH──► target machines\n (owns keys,\n audit log,\n rate limits)\n```\n\nThe proxy exposes persistent sessions with a simple REST surface:\n\n| Endpoint | Purpose |\n|---|---|\n| `POST /connect?target=vps1` | open a session → `session_id` |\n| `POST //exec` `{command, timeout}` | run a command (async) → `exec_id` |\n| `GET //exec/` | poll for output |\n| SFTP endpoints | file up-/download, `ls`, `mkdir`, `rm` |\n\nAuth is a Bearer token — the same pattern as every other API you use.\n\n## The Execution Pattern\n\n```bash\n# 1. connect once, reuse the session for the whole task\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. run a command\nEID=$(curl -s -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -X POST \"https://ssh-proxy.example/$SID/exec\" \\\n -d '{\"command\": \"docker ps --format \\\"{{.Names}}\\\"\", \"timeout\": 120}' | jq -r .exec_id)\n\n# 3. poll the result\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Rules of Engagement\n\n1. **Reuse sessions.** Connecting per command wastes resources and trips\n rate limits. Store the `session_id` (e.g. `/tmp/vps1_sid`) and heartbeat\n it before reuse.\n2. **Name targets, don't discover them.** Targets are pre-registered\n (`vps1`, `pi`, …). The proxy is the single source of truth — never hardcode\n IP addresses in agent code.\n3. **Prefer SFTP over shell cat/heredoc for files.** Escaping binary data\n through `exec` corrupts payloads. Use the dedicated upload/download\n endpoints.\n4. **Quote your commands.** The JSON body is parsed twice (HTTP + shell).\n Wrap remote commands in single quotes and keep them one-liners.\n5. **Assume auditing.** Every exec lands in the proxy's audit log — behave\n as if the human reads everything (they can).\n\n## When NOT to use exec\n\n- Reading structured state that has an API (Docker, databases, the Synapse\n Mind API) — always prefer the API over parsing CLI output.\n- Long-running interactive processes. `exec` is fire-and-forget with a\n timeout; use `nohup` + a status file on the target instead.\n- Anything destructive without an explicit instruction. The proxy gives you\n the power — the human gives you the permission.\n\n## Error Recovery\n\n| Symptom | Fix |\n|---|---|\n| 401 on connect | token expired — re-read it from memory/settings, never from a transcript |\n| session 404 | session expired (24h cap) — reconnect |\n| exec timeout | raise `timeout` or split the command; check load on the target |\n| garbled file content | you used `exec` instead of SFTP — switch to the SFTP endpoints |\n","content_html":"

SSH Access via Proxy

\n

Agents need to run commands on remote machines — deploy a container, read a\nlog, fix a config. Handing raw SSH private keys to an LLM is a bad idea:\nkeys end up in context windows, logs and transcripts. An SSH-Proxy solves\nthis: it owns the credentials, the agent only speaks HTTP.

\n

The Model

\n
LLM ──HTTPS──► SSH-Proxy ──SSH──► target machines\n                (owns keys,\n                 audit log,\n                 rate limits)

The proxy exposes persistent sessions with a simple REST surface:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointPurpose
POST /connect?target=vps1open a session → session_id
POST /<sid>/exec {command, timeout}run a command (async) → exec_id
GET /<sid>/exec/<exec_id>poll for output
SFTP endpointsfile up-/download, ls, mkdir, rm
\n

Auth is a Bearer token — the same pattern as every other API you use.

\n

The Execution Pattern

\n
# 1. connect once, reuse the session for the whole task\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. run a command\nEID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \\\n  -X POST "https://ssh-proxy.example/$SID/exec" \\\n  -d '{"command": "docker ps --format \\"{{.Names}}\\"", "timeout": 120}' | jq -r .exec_id)\n\n# 3. poll the result\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Rules of Engagement

\n
    \n
  1. Reuse sessions. Connecting per command wastes resources and trips\nrate limits. Store the session_id (e.g. /tmp/vps1_sid) and heartbeat\nit before reuse.
    2. \n
  2. Name targets, don't discover them. Targets are pre-registered\n(vps1, pi, …). The proxy is the single source of truth — never hardcode\nIP addresses in agent code.
    3. \n
  3. Prefer SFTP over shell cat/heredoc for files. Escaping binary data\nthrough exec corrupts payloads. Use the dedicated upload/download\nendpoints.
    4. \n
  4. Quote your commands. The JSON body is parsed twice (HTTP + shell).\nWrap remote commands in single quotes and keep them one-liners.
    5. \n
  5. Assume auditing. Every exec lands in the proxy's audit log — behave\nas if the human reads everything (they can).
    6. \n
\n

When NOT to use exec

\n
    \n
  • Reading structured state that has an API (Docker, databases, the Synapse\nMind API) — always prefer the API over parsing CLI output.
    • \n
  • Long-running interactive processes. exec is fire-and-forget with a\ntimeout; use nohup + a status file on the target instead.
    • \n
  • Anything destructive without an explicit instruction. The proxy gives you\nthe power — the human gives you the permission.
    • \n
\n

Error Recovery

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptomFix
401 on connecttoken expired — re-read it from memory/settings, never from a transcript
session 404session expired (24h cap) — reconnect
exec timeoutraise timeout or split the command; check load on the target
garbled file contentyou used exec instead of SFTP — switch to the SFTP endpoints
\n","urls":{"html":"/docs/llm-cookbook/ssh-proxy-access","text":"/docs/llm-cookbook/ssh-proxy-access?format=text","json":"/docs/llm-cookbook/ssh-proxy-access?format=json","llm":"/docs/llm-cookbook/ssh-proxy-access?format=llm"},"translations_available":["en","de"],"wordCount":375,"readMinutes":2,"llmContext":"NEVER hold raw SSH private keys as an LLM. Use an SSH-Proxy HTTP API:\n1) POST /connect?target= → session_id (persistent, survives hours).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → output when done.\n4) Use SFTP endpoints for file up/download instead of cat/heredoc.\nTargets are pre-registered names (e.g. \"vps1\"), not IPs — the proxy is the\nonly place where credentials live.\n","requestedLang":"en","contentMarkdown":"\n# SSH Access via Proxy\n\nAgents need to run commands on remote machines — deploy a container, read a\nlog, fix a config. Handing raw SSH private keys to an LLM is a bad idea:\nkeys end up in context windows, logs and transcripts. An SSH-Proxy solves\nthis: it owns the credentials, the agent only speaks HTTP.\n\n## The Model\n\n```\nLLM ──HTTPS──► SSH-Proxy ──SSH──► target machines\n (owns keys,\n audit log,\n rate limits)\n```\n\nThe proxy exposes persistent sessions with a simple REST surface:\n\n| Endpoint | Purpose |\n|---|---|\n| `POST /connect?target=vps1` | open a session → `session_id` |\n| `POST //exec` `{command, timeout}` | run a command (async) → `exec_id` |\n| `GET //exec/` | poll for output |\n| SFTP endpoints | file up-/download, `ls`, `mkdir`, `rm` |\n\nAuth is a Bearer token — the same pattern as every other API you use.\n\n## The Execution Pattern\n\n```bash\n# 1. connect once, reuse the session for the whole task\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. run a command\nEID=$(curl -s -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -X POST \"https://ssh-proxy.example/$SID/exec\" \\\n -d '{\"command\": \"docker ps --format \\\"{{.Names}}\\\"\", \"timeout\": 120}' | jq -r .exec_id)\n\n# 3. poll the result\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Rules of Engagement\n\n1. **Reuse sessions.** Connecting per command wastes resources and trips\n rate limits. Store the `session_id` (e.g. `/tmp/vps1_sid`) and heartbeat\n it before reuse.\n2. **Name targets, don't discover them.** Targets are pre-registered\n (`vps1`, `pi`, …). The proxy is the single source of truth — never hardcode\n IP addresses in agent code.\n3. **Prefer SFTP over shell cat/heredoc for files.** Escaping binary data\n through `exec` corrupts payloads. Use the dedicated upload/download\n endpoints.\n4. **Quote your commands.** The JSON body is parsed twice (HTTP + shell).\n Wrap remote commands in single quotes and keep them one-liners.\n5. **Assume auditing.** Every exec lands in the proxy's audit log — behave\n as if the human reads everything (they can).\n\n## When NOT to use exec\n\n- Reading structured state that has an API (Docker, databases, the Synapse\n Mind API) — always prefer the API over parsing CLI output.\n- Long-running interactive processes. `exec` is fire-and-forget with a\n timeout; use `nohup` + a status file on the target instead.\n- Anything destructive without an explicit instruction. The proxy gives you\n the power — the human gives you the permission.\n\n## Error Recovery\n\n| Symptom | Fix |\n|---|---|\n| 401 on connect | token expired — re-read it from memory/settings, never from a transcript |\n| session 404 | session expired (24h cap) — reconnect |\n| exec timeout | raise `timeout` or split the command; check load on the target |\n| garbled file content | you used `exec` instead of SFTP — switch to the SFTP endpoints |\n","contentHtml":"

SSH Access via Proxy

\n

Agents need to run commands on remote machines — deploy a container, read a\nlog, fix a config. Handing raw SSH private keys to an LLM is a bad idea:\nkeys end up in context windows, logs and transcripts. An SSH-Proxy solves\nthis: it owns the credentials, the agent only speaks HTTP.

\n

The Model

\n
LLM ──HTTPS──► SSH-Proxy ──SSH──► target machines\n                (owns keys,\n                 audit log,\n                 rate limits)

The proxy exposes persistent sessions with a simple REST surface:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointPurpose
POST /connect?target=vps1open a session → session_id
POST /<sid>/exec {command, timeout}run a command (async) → exec_id
GET /<sid>/exec/<exec_id>poll for output
SFTP endpointsfile up-/download, ls, mkdir, rm
\n

Auth is a Bearer token — the same pattern as every other API you use.

\n

The Execution Pattern

\n
# 1. connect once, reuse the session for the whole task\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. run a command\nEID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \\\n  -X POST "https://ssh-proxy.example/$SID/exec" \\\n  -d '{"command": "docker ps --format \\"{{.Names}}\\"", "timeout": 120}' | jq -r .exec_id)\n\n# 3. poll the result\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Rules of Engagement

\n
    \n
  1. Reuse sessions. Connecting per command wastes resources and trips\nrate limits. Store the session_id (e.g. /tmp/vps1_sid) and heartbeat\nit before reuse.
    2. \n
  2. Name targets, don't discover them. Targets are pre-registered\n(vps1, pi, …). The proxy is the single source of truth — never hardcode\nIP addresses in agent code.
    3. \n
  3. Prefer SFTP over shell cat/heredoc for files. Escaping binary data\nthrough exec corrupts payloads. Use the dedicated upload/download\nendpoints.
    4. \n
  4. Quote your commands. The JSON body is parsed twice (HTTP + shell).\nWrap remote commands in single quotes and keep them one-liners.
    5. \n
  5. Assume auditing. Every exec lands in the proxy's audit log — behave\nas if the human reads everything (they can).
    6. \n
\n

When NOT to use exec

\n
    \n
  • Reading structured state that has an API (Docker, databases, the Synapse\nMind API) — always prefer the API over parsing CLI output.
    • \n
  • Long-running interactive processes. exec is fire-and-forget with a\ntimeout; use nohup + a status file on the target instead.
    • \n
  • Anything destructive without an explicit instruction. The proxy gives you\nthe power — the human gives you the permission.
    • \n
\n

Error Recovery

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptomFix
401 on connecttoken expired — re-read it from memory/settings, never from a transcript
session 404session expired (24h cap) — reconnect
exec timeoutraise timeout or split the command; check load on the target
garbled file contentyou used exec instead of SFTP — switch to the SFTP endpoints
\n","translationsAvailable":["en","de"]}