# 프록시를 통한 SSH 접근
SUMMARY: LLM 에이전트가 날 것의 SSH 키 대신 SSH 프록시 API를 통해 원격 기기에서 안전하게 명령을 실행하는 방법.

KEY CONTEXT:
LLM으로서 날 것의 SSH 개인 키를 절대 보관하지 않는다. SSH 프록시 HTTP API를 사용한다:
1) POST /connect?target=<name> → session_id(지속, 수시간 생존).
2) POST /<session_id>/exec {command, timeout} → exec_id.
3) GET /<session_id>/exec/<exec_id> → 완료 시 출력.
4) 파일 업/다운로드에는 cat/heredoc 대신 SFTP 엔드포인트를 사용.
타깃은 사전 등록된 이름(예: "vps1")이지 IP가 아니다 — 자격 증명이 사는
유일한 곳은 프록시다.

프록시를 통한 SSH 접근
에이전트는 원격 기기에서 명령을 실행해야 합니다 — 컨테이너 배포, 로그 읽기, 설정 수정. 날 것의 SSH 개인 키를 LLM에게 넘기는 것은 나쁜 생각입니다: 키는 컨텍스트 창, 로그, 전사 기록으로 흘러 들어갑니다. SSH 프록시는 이것을 해결합니다: 자격 증명을 소유한 것은 프록시이고, 에이전트는 HTTP만 말합니다.
모델
[CODE BLOCK]
프록시는 단순한 REST 표면으로 지속 세션을 노출합니다:
| 엔드포인트 | 목적 |
|---|---|
|  | 세션 열기 →  |
|   | 명령 실행(비동기) →  |
|  | 출력 폴링 |
| SFTP 엔드포인트 | 파일 업/다운로드, , ,  |
인증은 Bearer 토큰입니다 — 당신이 쓰는 다른 모든 API와 같은 패턴입니다.
실행 패턴
[CODE BLOCK]
운용 규칙
1. 세션을 재사용하십시오. 명령마다 연결하면 자원을 낭비하고 속도 제한에 걸립니다. 를 저장하고(예: ), 재사용 전에 하트비트를 보내십시오.
2. 타깃에 이름을 붙이고, 발견하지 마십시오. 타깃은 사전 등록되어 있습니다(, , …). 프록시가 유일한 진실 원천입니다 — 에이전트 코드에 IP 주소를 하드코딩하지 마십시오.
3. 파일에는 셸의 cat/heredoc보다 SFTP를 선호하십시오. 를 통한 이진 데이터 이스케이프는 페이로드를 손상시킵니다. 전용 업/다운로드 엔드포인트를 사용하십시오.
4. 명령에 따옴표를 붙이십시오. JSON 본문은 두 번 파싱됩니다(HTTP + 셸). 원격 명령은 작은따옴표로 감싸고 한 줄로 유지하십시오.
5. 감사를 가정하십시오. 모든 exec는 프록시의 감사 로그에 남습니다 — 인간이 전부 읽는 것처럼 행동하십시오(그렇게 할 수 있습니다).
exec를 쓰지 말아야 할 때
- API가 있는 구조화된 상태 읽기(Docker, 데이터베이스, Synapse의 Mind API) — CLI 출력 파싱보다 항상 API를 선호하십시오.
- 오래 걸리는 대화형 프로세스. 는 타임아웃이 있는 fire-and-forget입니다; 대신 타깃에서  + 상태 파일을 사용하십시오.
- 명시적 지시 없이 파괴적인 모든 것. 프록시가 당신에게 힘을 줍니다 — 인간이 당신에게 허가를 줍니다.
오류 복구
| 증상 | 해결 |
|---|---|
| connect에서 401 | 토큰 만료 — memory/settings에서 다시 읽고, 전사 기록에서는 절대 아님 |
| 세션 404 | 세션 만료(24h 한도) — 재접속 |
| exec 타임아웃 | 을 올리거나 명령을 나누기; 타깃의 부하 확인 |
| 깨진 파일 내용 | SFTP 대신 를 썼음 — SFTP 엔드포인트로 전환 |