# Truy cập SSH qua proxy
SUMMARY: Tác nhân LLM chạy lệnh trên máy từ xa an toàn qua API proxy SSH thay vì khóa SSH thô như thế nào.

KEY CONTEXT:
KHÔNG BAO GIỜ giữ khóa riêng SSH thô với tư cách LLM. Dùng HTTP API proxy SSH:
1) POST /connect?target=<name> → session_id (bền vững, sống qua hàng giờ).
2) POST /<session_id>/exec {command, timeout} → exec_id.
3) GET /<session_id>/exec/<exec_id> → đầu ra khi xong.
4) Dùng endpoint SFTP cho tải lên/xuống tệp thay vì cat/heredoc.
Mục tiêu là tên đăng ký trước (vd. "vps1"), không phải IP — proxy là nơi duy
nhất chứa thông tin xác thực.

Truy cập SSH qua proxy
Tác nhân cần chạy lệnh trên máy từ xa — triển khai container, đọc log, sửa cấu hình. Giao khóa riêng SSH thô cho LLM là ý tồi: khóa lọt vào cửa sổ ngữ cảnh, log và bản ghi. Proxy SSH giải quyết điều này: nó giữ thông tin xác thực, tác nhân chỉ nói HTTP.
Mô hình
[CODE BLOCK]
Proxy cung cấp phiên bền vững qua mặt REST đơn giản:
| Endpoint | Mục đích |
|---|---|
|  | mở phiên →  |
|   | chạy lệnh (async) →  |
|  | thăm dò đầu ra |
| Endpoint SFTP | tải lên/xuống tệp, , ,  |
Xác thực là token Bearer — cùng mẫu với mọi API khác bạn dùng.
Mẫu thực thi
[CODE BLOCK]
Quy tắc thao tác
1. Tái sử dụng phiên. Kết nối cho từng lệnh lãng phí tài nguyên và đụng giới hạn tần suất. Lưu  (vd. ) và gửi heartbeat trước khi tái dùng.
2. Đặt tên mục tiêu, đừng dò tìm. Mục tiêu được đăng ký trước (, , …). Proxy là nguồn chân lý duy nhất — không bao giờ mã hóa cứng địa chỉ IP vào mã tác nhân.
3. Ưu tiên SFTP hơn cat/heredoc của shell cho tệp. Escape dữ liệu nhị phân qua  làm hỏng tải trọng. Dùng endpoint tải lên/xuống chuyên dụng.
4. Bọc lệnh của bạn trong dấu ngoặc. Thân JSON được phân tích hai lần (HTTP + shell). Bọc lệnh từ xa trong ngoặc đơn và giữ một dòng.
5. Giả định có kiểm toán. Mỗi lệnh exec vào nhật ký kiểm toán của proxy — hành xử như con người đọc mọi thứ (họ có thể).
Khi nào KHÔNG dùng exec
- Đọc trạng thái có cấu trúc đã có API (Docker, cơ sở dữ liệu, Mind API của Synapse) — luôn ưu tiên API hơn phân tích đầu ra CLI.
- Tiến trình tương tác dài hạn.  là fire-and-forget có thời hạn; thay vào đó dùng  + tệp trạng thái trên máy đích.
- Bất kỳ điều gì phá hoại mà không có chỉ thị rõ ràng. Proxy cho bạn quyền lực — con người cho bạn sự cho phép.
Khôi phục lỗi
| Triệu chứng | Cách xử lý |
|---|---|
| 401 khi connect | token hết hạn — đọc lại từ memory/settings, không bao giờ từ bản ghi |
| phiên 404 | phiên hết hạn (trần 24h) — kết nối lại |
| exec quá hạn | tăng  hoặc chia nhỏ lệnh; kiểm tra tải máy đích |
| nội dung tệp hỏng | bạn dùng  thay vì SFTP — chuyển sang endpoint SFTP |