<p align="center">
<img src="https://raw.githubusercontent.com/shaguocgl/buff-term/HEAD/src/assets/buffterm-logo.png" width="128" alt="buffTerm logo" />
</p>
buffTerm
简体中文 | English
AI를 위한 SSH 도구 및 MCP 서버
An AI-first SSH tool and MCP server
License
Platform
Rust
React
Agent
Website
buffTerm은 AI를 위한 SSH 도구 및 MCP 서버이며, 자체 개발 AI Agent 오케스트레이션 레이어가 내장되어 있어 DeepSeek, Qwen, Kimi 등 임의의 OpenAI 호환 프로토콜 대규모 언어 모델(LLM)에 연결하여 자연어로 상태 조회, 문제 진단, 프로그램 설치, 운영 및 유지보수 작업을 수행할 수 있습니다.
또한 여러 호스트를 동시에 MCP 서비스로 노출하여 다른 AI 도구가 호출할 수 있도록 지원하며, 보안 수준은 사용자가 직접 관리합니다. 위험도가 높은 명령어 차단, AI 작업 승인 및 감사 추적(audit)이 전 과정에 걸쳐 안전망 역할을 합니다. 설정, 자격 증명(credentials), 감사 데이터는 로컬에만 저장되며, AI 대화 및 점검 내용은 설정한 모델 플랫폼으로 전송됩니다.
🤖 Agent 오케스트레이션 레이어 완전 자체 개발: 핵심 도구 호출 루프(SSE 스트리밍 파싱 → 도구 실행 → 결과 채우기)는 본 프로젝트가 직접 구현하여, LangChain / OpenAI Agents SDK / Vercel AI SDK 등 프레임워크에 의존하지 않습니다 — 승인 차단, 보안 정책, 감사 기록은 모두 사용자가 통제합니다.
<p align="center">
<img src="https://raw.githubusercontent.com/shaguocgl/buff-term/HEAD/images/ai-agent.webp" alt="AI Agent 대화 및 터미널" width="100%" />
</p>
<p align="center">
<a href="https://shaguocgl.github.io/buff-term-site">
<img src="https://raw.githubusercontent.com/shaguocgl/buff-term/HEAD/images/desc.webp" alt="buffTerm 기능 소개 (공식 웹사이트 방문)" width="100%" />
</a>
</p>
📥 다운로드
최신 설치 패키지는 GitHub Releases에서 다운로드하세요:
- macOS:
.dmg 다운로드 (Universal, Apple Silicon 및 Intel 모두 지원)
- Windows:
.exe 다운로드
⚠️ macOS 버전은 현재 Apple 공증을 받지 않았습니다. 자격 증명은 AES-256-GCM으로 암호화되어 로컬 SQLite에 저장되며, 마스터 키는 시스템 키체인(Keychain)에 저장됩니다. 서명이 없는 개발판이 처음 키체인을 접근할 때 시스템 승인 팝업이 한 번 나타날 수 있으며, 이는 macOS의 정상적인 동작입니다.
✨ 기능 특징
AI Agent
- 자체 개발 Agent 오케스트레이션 레이어: SSE 스트리밍 파싱, 도구 호출 루프, 승인 및 감사 모두 직접 구현하여 프레임워크 의존성 없음
- russh 프로토콜 수준 실행: AI 도구 호출은 통합 SSH 연결 풀을 사용합니다 (연결 재사용, 채널 동시성, known_hosts 검증)
- 다중 플랫폼 구성: DeepSeek / OpenAI / 通义千问 / Kimi / Ollama. 단일 벤더에서 여러 모델 구성 가능
- 도구 호출:
exec_command, read_file, list_dir, resource_usage, query_history (과거 지표 추세, 분/시간/일 세 가지 집계 수준 지원, AI가 분석 목적에 따라 선택), update_task_plan (로컬 작업 대장, 승인 불필요)
- 컨텍스트 전송 시 모델 창 크기 예산 책정: 이전 라운드는 자동 압축 요약되며, 작업 대장은 항상 보존됨
- 각 호스트별 독립 세션 기록을 가지며, 언제든지 중단/비울 수 있음
MCP 서비스
- buffTerm으로서의 MCP 서버: Streamable HTTP + JSON-RPC + 토큰 인증을 기반으로, 선택된 서버 기능을 Codex, Claude Desktop 등 외부 AI 도구에 개방합니다.
- 세 가지 권한 모드: 읽기 전용(쓰기 작업 금지) / 통제(위험 명령 확인 필요) / 전체 허용
- 시작 후 외부 AI를 위한 MCP 설정 JSON을 자동으로 생성하며, 토큰 갱신 및 취소(revocation)를 지원합니다.
SSH와 SFTP
- 프로토콜 레벨 SSH: 대화형 터미널, AI, MCP, 모니터링, 순찰 점검 및 SFTP 모두
russh / russh-sftp 기반이며, 시스템의 ssh / sftp 명령을 호출하지 않습니다.
- 다양한 인증 방식: 비밀번호, keyboard-interactive 폴백(fallback), 일반/암호화된 개인 키, Unix ssh-agent를 지원합니다. RSA는 SHA-2 핸드셰이크로 자동 협상됩니다.
- 엄격한 호스트 지문 검증: 최초 연결 시 SHA-256 지문을 표시하고 확인을 기다리며, 지문 변화가 감지되면 즉시 거부하고 신구 지문을 표시합니다.
- 동시 연결 재사용: AI, MCP, 모니터링, 순찰 점검 및 SFTP는 호스트별로 SSH 연결을 재사용하며, 채널 레벨의 동시성을 가지며, 유휴 연결은 자동으로 회수됩니다.
- 구조화된 SFTP: 디렉토리 탐색, 업로드, 다운로드, 이름 변경, 삭제, 디렉토리 생성, 덮어쓰기 확인, 진행률 및 취소 지원; 심볼릭 링크와 공백이 포함된 파일명도 지원합니다.
- 대량 업로드: 파일 선택 시 다중 선택을 지원하며, 최대 3개의 동시 전송(각 항목별 독립적인 진행률 및 취소 가능, 원클릭 전체 취소 가능); 충돌 파일은 한 번의 덮어쓰기 확인으로 요약되며, '전체 덮어쓰기' 또는 '충돌 항목 건너뛰기'를 선택하여 나머지 파일만 업로드할 수 있습니다.
- 내장 파일 편집기: 파일 패널의 인라인 플로팅 버튼(또는 파일 행 더블클릭)을 통해 중앙 영역에서 탭으로 파일을 열고(CodeMirror 6, 확장자별 하이라이트), 편집 및 Ctrl/Cmd+S 저장 기능을 지원합니다. 저장은 '같은 디렉토리 임시 파일 + rename' 원자적 교체 방식을 사용하며 기존 권한을 유지하고, 쓰기 전에 mtime을 검증하여 타인의 변경 사항으로 인한 덮어쓰기를 방지합니다. 심볼릭 링크는 실제 목표에 쓰여지고 링크 자체는 대체되지 않습니다. 단일 파일은 2 MiB 제한이 있으며 바이너리/비-UTF-8 파일은 직접 거부됩니다;
~/.ssh, /etc/sudoers, /etc/shadow, cron, systemd, 로그인 셸 시작 스크립트 등 민감한 경로는 2차 확인이 필요하며, 매번 저장 및 쓰기 작업에 대한 감사(audit)가 기록됩니다.
터미널 보호
- 커서 전 위험 명령 가로채기: 터미널의 실제 명령어 라인 판별(Tab 자동 완성 / 방향키 히스토리 / 편집 키 기반)을 바탕으로, 규칙에 해당하면 팝업 확인 후 실행됩니다.
- 사전 설정 + 사용자 정의 위험 규칙:
rm -rf, mkfs, dd if=, systemctl stop, drop table, curl | sh 등을 커버하며, 삭제/수정 및 원클릭 복구 기능을 제공합니다.
- 전체 화면 애플리케이션(vim / htop 등) 내부에서도 자동으로 투과되어 편집 내용을 오판하지 않으며, 매번 가로채기된 쓰기 작업은 감사 로그에 기록됩니다.
보안 시스템
- 3단계 보안 레벨: 전체 검토 / 스마트 검토(읽기 전용 자동 실행, 위험 명령 승인 필요) / 전체 허용
- 자격 증명 암호화: SSH 비밀번호 / 개인 키 암호, AI API Key, MCP 토큰, SMTP 비밀번호는 모두 AES-256-GCM으로 로컬에 저장되며, 마스터 키는 시스템 키체인에 저장됩니다. 개인 키 암호는 로컬에서만 개인 키를 복호화하는 데 사용됩니다.
- 작업 감사: AI Agent, 터미널 보호, MCP 서비스, 수정 실행 및 파일 편집의 시간, 호스트, 출처, 명령어, 승인 방식 및 결과 요약이 기록됩니다.
- 출력 비식별화: 명령 출력은 모델에 들어가기 전에 AK/SK, 키, 비밀번호 등 민감한 정보를 필터링합니다. 개인 키와 API Key는 절대 모델 컨텍스트로 들어가지 않습니다.
모니터링, 순찰 점검 및 알림
- 모니터링 패널: CPU / 메모리 / 디스크 대시보드 + 부하 + TOP 프로세스가 자동 새로고침됩니다. 터미널 세션 연결 후 즉시 백그라운드에서 수집되며(세션 연결 재사용, 패널 열기 5초 / 백그라운드 무음 30초, 최근 30분 유지), 패널을 여는 것만으로 연결 이후의 추세를 볼 수 있으며, 다중 호스트 전환 시 데이터 손실이 없습니다.
- AI 순찰 점검: 읽기 전용 기준선 데이터를 수집하여 마크다운 보고서(중국어 / 영어는 인터페이스 언어에 따름)를 생성하며, 악성코드/채굴 위험 감지 기능을 포함합니다.
- 원클릭 수정: AI가 순찰 점검 보고서를 기반으로 수정 단계를 생성하고, 확인 후 자동으로 실행되며, 단계 편집 및 실패 재시도를 지원합니다.
- 이메일 알림: 순찰 점검 보고서와 수정 결과를 설정된 수신자에게 자동으로 전송할 수 있습니다.
🧱 기술 스택
| 계층 | 기술 |
|---|
| 데스크톱 프레임워크 | Tauri 2 (Rust 백엔드) |
| ... | |
🏗 아키텍처
flowchart LR
UI[
- Node.js 20 이상
- Rust stable (1.97 이상)
- macOS는 Xcode Command Line Tools 필요; Windows는 WebView2 필요 (일반적으로 내장됨)
### 개발 및 실행
```bash
npm install
npm run tauri dev
검증
npm run build
cd src-tauri
cargo check
...
패키징
자주 사용하는 설치 패키지 단축 명령어:
산출물 위치:
src-tauri/target/release/bundle/dmg/
src-tauri/target/release/bundle/nsis/
DMG는 macOS에서, EXE는 Windows에서 빌드해야 합니다. 패키징 전에 프론트엔드 빌드와 Rust 컴파일이 먼저 실행됩니다. 코드 서명을 구성하지 않아도 패키징은 가능하지만, 시스템에서 보안 알림이 표시될 수 있습니다.
📚 문서
📁 프로젝트 구조
src/ 프론트엔드 (React + xterm.js)
i18n/ 인터페이스 다국어 (zh / en 사전, Provider, useT hook)
components/ 채팅 패널 / 터미널 / 파일 에디터 / 팝업 / 드롭다운 등
...
📄 라이선스
MIT
