# SSH Access via Proxy
SUMMARY: How an LLM agent runs commands on remote machines safely through an SSH-Proxy API instead of raw SSH keys.

KEY CONTEXT:
NEVER hold raw SSH private keys as an LLM. Use an SSH-Proxy HTTP API:
1) POST /connect?target=<name> → session_id (persistent, survives hours).
2) POST /<session_id>/exec {command, timeout} → exec_id.
3) GET /<session_id>/exec/<exec_id> → output when done.
4) Use SFTP endpoints for file up/download instead of cat/heredoc.
Targets are pre-registered names (e.g. "vps1"), not IPs — the proxy is the
only place where credentials live.

SSH Access via Proxy
Agents need to run commands on remote machines — deploy a container, read a
log, fix a config. Handing raw SSH private keys to an LLM is a bad idea:
keys end up in context windows, logs and transcripts. An SSH-Proxy solves
this: it owns the credentials, the agent only speaks HTTP.
The Model
[CODE BLOCK]
The proxy exposes persistent sessions with a simple REST surface:
| Endpoint | Purpose |
|---|---|
|  | open a session →  |
|   | run a command (async) →  |
|  | poll for output |
| SFTP endpoints | file up-/download, , ,  |
Auth is a Bearer token — the same pattern as every other API you use.
The Execution Pattern
[CODE BLOCK]
Rules of Engagement
1. Reuse sessions. Connecting per command wastes resources and trips
   rate limits. Store the  (e.g. ) and heartbeat
   it before reuse.
2. Name targets, don't discover them. Targets are pre-registered
   (, , …). The proxy is the single source of truth — never hardcode
   IP addresses in agent code.
3. Prefer SFTP over shell cat/heredoc for files. Escaping binary data
   through  corrupts payloads. Use the dedicated upload/download
   endpoints.
4. Quote your commands. The JSON body is parsed twice (HTTP + shell).
   Wrap remote commands in single quotes and keep them one-liners.
5. Assume auditing. Every exec lands in the proxy's audit log — behave
   as if the human reads everything (they can).
When NOT to use exec
- Reading structured state that has an API (Docker, databases, the Synapse
  Mind API) — always prefer the API over parsing CLI output.
- Long-running interactive processes.  is fire-and-forget with a
  timeout; use  + a status file on the target instead.
- Anything destructive without an explicit instruction. The proxy gives you
  the power — the human gives you the permission.
Error Recovery
| Symptom | Fix |
|---|---|
| 401 on connect | token expired — re-read it from memory/settings, never from a transcript |
| session 404 | session expired (24h cap) — reconnect |
| exec timeout | raise  or split the command; check load on the target |
| garbled file content | you used  instead of SFTP — switch to the SFTP endpoints |