# 프록시를 통한 SSH 접근

에이전트는 원격 기기에서 명령을 실행해야 합니다 — 컨테이너 배포, 로그 읽기, 설정 수정. 날 것의 SSH 개인 키를 LLM에게 넘기는 것은 나쁜 생각입니다: 키는 컨텍스트 창, 로그, 전사 기록으로 흘러 들어갑니다. SSH 프록시는 이것을 해결합니다: 자격 증명을 소유한 것은 프록시이고, 에이전트는 HTTP만 말합니다.

## 모델

```
LLM ──HTTPS──► SSH 프록시 ──SSH──► 타깃 기기
                (키 소유,
                 감사 로그,
                 속도 제한)
```

프록시는 단순한 REST 표면으로 지속 세션을 노출합니다:

| 엔드포인트 | 목적 |
|---|---|
| `POST /connect?target=vps1` | 세션 열기 → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | 명령 실행(비동기) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | 출력 폴링 |
| SFTP 엔드포인트 | 파일 업/다운로드, `ls`, `mkdir`, `rm` |

인증은 Bearer 토큰입니다 — 당신이 쓰는 다른 모든 API와 같은 패턴입니다.

## 실행 패턴

```bash
# 1. 한 번만 연결하고, 작업 전체에서 세션을 재사용
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. 명령 실행
EID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -X POST "https://ssh-proxy.example/$SID/exec" \
  -d '{"command": "docker ps --format \"{{.Names}}\"", "timeout": 120}' | jq -r .exec_id)

# 3. 결과 폴링
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## 운용 규칙

1. **세션을 재사용하십시오.** 명령마다 연결하면 자원을 낭비하고 속도 제한에 걸립니다. `session_id`를 저장하고(예: `/tmp/vps1_sid`), 재사용 전에 하트비트를 보내십시오.
2. **타깃에 이름을 붙이고, 발견하지 마십시오.** 타깃은 사전 등록되어 있습니다(`vps1`, `pi`, …). 프록시가 유일한 진실 원천입니다 — 에이전트 코드에 IP 주소를 하드코딩하지 마십시오.
3. **파일에는 셸의 cat/heredoc보다 SFTP를 선호하십시오.** `exec`를 통한 이진 데이터 이스케이프는 페이로드를 손상시킵니다. 전용 업/다운로드 엔드포인트를 사용하십시오.
4. **명령에 따옴표를 붙이십시오.** JSON 본문은 두 번 파싱됩니다(HTTP + 셸). 원격 명령은 작은따옴표로 감싸고 한 줄로 유지하십시오.
5. **감사를 가정하십시오.** 모든 exec는 프록시의 감사 로그에 남습니다 — 인간이 전부 읽는 것처럼 행동하십시오(그렇게 할 수 있습니다).

## exec를 쓰지 말아야 할 때

- API가 있는 구조화된 상태 읽기(Docker, 데이터베이스, Synapse의 Mind API) — CLI 출력 파싱보다 항상 API를 선호하십시오.
- 오래 걸리는 대화형 프로세스. `exec`는 타임아웃이 있는 fire-and-forget입니다; 대신 타깃에서 `nohup` + 상태 파일을 사용하십시오.
- 명시적 지시 없이 파괴적인 모든 것. 프록시가 당신에게 힘을 줍니다 — 인간이 당신에게 허가를 줍니다.

## 오류 복구

| 증상 | 해결 |
|---|---|
| connect에서 401 | 토큰 만료 — memory/settings에서 다시 읽고, 전사 기록에서는 절대 아님 |
| 세션 404 | 세션 만료(24h 한도) — 재접속 |
| exec 타임아웃 | `timeout`을 올리거나 명령을 나누기; 타깃의 부하 확인 |
| 깨진 파일 내용 | SFTP 대신 `exec`를 썼음 — SFTP 엔드포인트로 전환 |