호스트 콘솔 HostConsole

SSH를 AI에게 맡기되, 키는 내 손에.

English · 简体中文

특징 · 스크린샷 · 빠른 시작 · AI 연동 · 보안 모델 · 작동 원리 · FAQ

호스트 콘솔이 필요한 이유

아마 이런 고민을 해본 적이 있을 것이다. AI에게 NAS, 서버, 라우터 관리를 맡기고 싶은데 SSH 키나 비밀번호를 AI 클라이언트에 직접 넘기는 게 왠지 불안하다——

• 키를 AI 설정에 붙여넣는 순간, 그대로 기기 전체를 넘겨주는 셈이고, 어디에 기록될지 알 수 없다;

• AI용 임시 공개키를 만들어 authorized_keys에 넣고, 다 쓰면 정리해야 하는데 번거롭고 잊어버리기 쉽다;

• AI가 sudo를 실행할 때 어떤 명령을 실행하는지 전혀 볼 수 없고, 승인 절차도 없다;

• AI 클라이언트를 바꾸면(Codex, OpenCode, ZCode……) 인증 절차 전체를 다시 해야 한다.

호스트 콘솔의 해답: 키는 절대 내 컴퓨터를 떠나지 않는다.

호스트 콘솔에서 SSH를 수동으로 연결하고(비밀번호 / 개인키, 시스템 수준 암호화 저장), "승인된 세션"을 로컬 MCP 브리지를 통해 AI에 넘긴다. AI는 세션 별칭(예: 「집 NAS」)만 볼 수 있고, 터미널을 조작할 수 있으며, 언제든 일시 중지·연결 해제할 수 있다——하지만 주소, 포트, 사용자 이름, 개인키는 절대 얻을 수 없다.

┌─────────────┐   SSH 凭据只到这里，加密保存    ┌──────────────┐
│   你本人     │ ────────────────────────────▶ │  你的 NAS /  │
│  (主机台 UI) │ ◀──────────────────────────── │   服务器      │
└──────┬──────┘        已建立的 SSH 会话        └──────────────┘
       │ 授权（相对安全 / 完全开放）
       ▼
┌──────────────┐  本机命名管道（不出网、不开端口） ┌─────────────┐
│  主机台 MCP   │ ◀──────────────────────────▶ │  AI Agent   │
│   桥接器      │      只传命令与输出、别名        │ Codex 等     │
└──────────────┘                                └─────────────┘

Related MCP server: SSH MCP Server

활용 시나리오

• 🏠 가정용 NAS / 홈 서버: AI에게 SMART 상태 확인, Docker 정리, RAID 경고 수리를 맡기되 root 권한은 넘기고 싶지 않을 때

• 🖥️ 개인 VPS / 개발 머신: 배포, 로그 확인, nginx 설정 수정 — AI가 작업하고 내가 승인

• 🌐 라우터 / 네트워크 장비: 가끔 AI 진단이 필요하지만 장비 자격 증명은 절대 외부로 유출할 수 없을 때

• 🔁 여러 AI 클라이언트 사용자: Codex, OpenCode, ZCode, WorkBuddy가 동일한 승인된 SSH 세션을 공유 — 도구를 바꿔도 재인증 불필요

• 🛡️ 감사(audit)를 중시하는 사람: 모든 sudo 명령은 눈앞에 뜨는 승인 창을 거쳐야 하고, 명령 원문이 명확하게 표시된다

스크린샷

핵심 기능

• 🔐 자격 증명 격리: SSH 주소, 포트, 사용자 이름은 로컬 구성에만 저장; 비밀번호와 개인키는 Electron safeStorage(Windows 시스템 자격 증명 보호)로 암호화하여 별도 금고에 저장. AI는 MCP를 통해 세션 별칭과 승인 상태만 얻을 수 있고, 나머지는 전혀 볼 수 없다 — 이 점은 전용 테스트 단언으로 보장된다.

• 🚦 이중 권한 모드: 상대적 안전(AI는 신원 / 시스템 / 저장소 / 프로세스 / 컨테이너 / 서비스 / 로그 7가지 고정 읽기 전용 검사만 실행 가능)과 완전 개방(현재 SSH 계정의 전체 터미널 권한), 언제든 원클릭 전환.

• 💳 sudo 승인 흐름: AI가 권한 상승이 필요하면 별도의 exec_sudo를 호출하고, 호스트 콘솔이 자동으로 명령 원문을 팝업으로 표시하며, 승인 후에만 실행. 선택적으로 30분(기본값, 0–240분 조절 가능) 동안 재확인 없는 창을 설정 가능; sudo 비밀번호는 로컬 금고에서 SSH 표준 입력을 통해 직접 원격으로 전달되며, 명령 텍스트에 들어가지 않고, 터미널 기록에 남지 않고, AI 컨텍스트에 포함되지 않는다.

• 🟢 Agent 연동 센터: 연동된 모든 AI가 상태 표시등으로 실시간 표시(온라인 / 오프라인 / 제어 중), 각 Agent마다 독립 연결 스위치 — 끄면 즉시 해당 Agent의 SSH 제어권과 sudo 권한이 해제되며, 다른 Agent에는 영향 없고 SSH도 끊기지 않는다.

• 🧙 원클릭 연동 마법사: Codex TOML, OpenCode JSONC, ZCode, WorkBuddy 및 범용 JSON/JSONC 6가지 MCP 구성 형식을 자동 인식·작성, 작성 전 미리보기 가능, 타임스탬프가 포함된 백업 자동 생성.

• ✍️ 단일 쓰기 임대: 동시에 하나의 Agent만 터미널에 쓸 수 있고, 다른 Agent는 점유 상태를 볼 수 있지만 명령을 삽입할 수 없다; 사용자가 명시적으로 "인수 / 강제 인수"를 말해야만 전환된다.

• 🫸 즉시 차단: 「AI 일시 중지」는 즉시 작업을 차단하지만 SSH 연결은 유지; 「연결 끊기」는 권한, 임대, sudo 권한을 동시에 해제.

• 🖥️ 로컬 수동 명령 대체: AI가 실행을 거부하거나 대화형 입력이 필요할 때, 인터페이스에 내장된 명령 입력창으로 직접 입력.

• 🇨🇳 전체 중국어 인터페이스: 중국어 사용자를 위해 설계, 권한 모드부터 오류 메시지까지 영어 용어 하나도 번역할 필요 없음.

• ✅ 29개 보안 테스트: 자격 증명 격리, 임대 독점, sudo 수명 주기, 구성 비식별화 등 핵심 보안 주장이 모두 자동화 테스트로 보장됨(npm test).

빠른 시작

환경 요구 사항

• Windows 10/11

• Node.js 20+(npm 포함)

시작

git clone https://github.com/tuweihuasheng/host-console.git
cd host-console
npm install
npm run desktop

앱 창을 닫아도 시스템 트레이에 상주하며, SSH 세션은 끊기지 않는다.

3단계 시작

1. 연결: 「새 연결」 클릭, SSH 비밀번호 / 개인키 붙여넣기 / 키 파일 선택; 첫 연결 시 호스트 SHA-256 지문을 확인하고 고정(TOFU).

2. 승인: 연결 후 오른쪽에서 「상대적 안전」 또는 「완전 개방」 선택.

3. AI 호출: 호스트 콘솔에 연동된 AI에게 말한다——

   이 컴퓨터에 「집 NAS」 SSH가 연결되어 있습니다. 디스크와 Docker 컨테이너 상태를 확인해 주세요.

   AI는 MCP를 통해 승인된 세션을 자동으로 발견하고, 제어권을 얻어 작업을 시작한다.

AI 연동

호스트 콘솔은 로컬 명명된 파이프(\\.\pipe\host-console-mcp)로 MCP 서비스를 제공하며, 어떤 TCP 포트도 수신하지 않으므로 클라우드 Agent는 접근할 수 없다.

가장 간단한 방법은 호스트 콘솔에서 「Agent 연동」 버튼을 클릭하고 내장 마법사로 구성을 자동 작성하는 것이다(자동 백업 및 미리보기 지원). 아래는 수동 구성 참고 자료:

Codex(~/.codex/config.toml)

[mcp_servers.host_console]
command = "node.exe 的完整路径"
args = ["C:\\path\\to\\host-console\\mcp\\server.mjs"]
startup_timeout_sec = 10
tool_timeout_sec = 60

OpenCode(~/.config/opencode/opencode.jsonc)

"mcp": {
  "host_console": {
    "type": "local",
    "command": ["node.exe 的完整路径", "C:\\path\\to\\host-console\\mcp\\server.mjs"],
    "enabled": true,
    "timeout": 60000,
    "environment": {
      "HOST_CONSOLE_AGENT_LABEL": "OpenCode",
      "HOST_CONSOLE_CLIENT_KIND": "opencode"
    }
  }
}

ZCode(~/.zcode/cli/config.json의 mcp.servers), WorkBuddy(~/.codebuddy/.mcp.json의 mcpServers) 및 임의의 범용 JSON/JSONC 모두 동일한 구조로 연동하거나, 내장 마법사를 사용해 작성할 수 있다.

구성 작성 후 해당 AI 클라이언트를 완전히 종료하고 재시작해야 한다(MCP 클라이언트는 시작 시에만 구성을 로드). 연동에 성공하면 호스트 콘솔 「Agent 연동 센터」에 녹색 상태 표시등이 나타나고, 승인된 세션의 별칭과 권한 모드를 AI에 동기화한다.

보안 모델

AI가 볼 수 있는 것과 볼 수 없는 것

다중 방어선

1. 파이프 수준 격리: MCP는 로컬 명명된 파이프에만 바인딩, 외부 네트워크 없음, 포트 개방 없음; 같은 컴퓨터 밖에서는 아무도 연결할 수 없다.

2. 단일 쓰기 임대: 동시 Agent 중 하나만 터미널을 조작할 수 있고, 인수는 사용자의 명시적 요청이 필요.

3. 이중 요소 확인: 다중 세션 시나리오에서 AI는 세션 ID 와 정확한 별칭을 동시에 제공해야 제어권을 얻을 수 있으며, 불일치 시 거부.

4. sudo 수명 주기: 임시 권한은 현재 세션과 현재 제어 Agent에만 바인딩되며, 일시 중지 / 연결 해제 / 인수 / 권한 하향 / 만료 시 즉시 무효화, 언제든 수동으로 조기 종료 가능.

5. 자격 증명 비가역성: 자격 증명 변경 시 먼저 SSH 연결을 끊어야 함; 이전 자격 증명은 절대 다시 표시되지 않고, 새 자격 증명은 암호화되어 덮어쓴다.

알려진 한계

• 호스트 콘솔과 동일한 Windows 사용자로 실행되는 악성 로컬 프로세스는 이론적으로 명명된 파이프에 연결할 수 있다 — 신뢰할 수 없는 로컬 환경에서는 「완전 개방」 모드를 사용하지 말 것.

• 현재 MVP 단계로, 서명된 설치 패키지와 자동 업데이트는 아직 제공되지 않는다.

MCP 도구 목록

AI 측에서 호출할 수 있는 9개 도구:

작동 원리

主机台 (Electron)
├── src/                    全中文桌面界面（React 19）
├── electron/
│   ├── main.cjs            窗口、托盘、命名管道服务、IPC
│   ├── session-manager.cjs 加密保险箱、SSH 连接池、授权与租约、sudo 审批
│   ├── agent-config.cjs    6 种格式的 Agent 配置向导（预览 + 备份 + 原子写入）
│   └── policy.cjs          只读命令白名单、公开信息脱敏
├── mcp/server.mjs          MCP 桥接服务（stdio → 命名管道）
└── tests/                  29 项安全与行为测试

FAQ

Q: AI가 호스트 콘솔을 호출해야 한다는 걸 어떻게 알까? MCP 연동 후, 호스트 콘솔은 초기화 설명에서 승인된 세션의 별칭과 권한 모드를 AI에 능동적으로 동기화한다. 평소처럼 작업을 지시하면 된다: "이 컴퓨터에 집 NAS SSH가 연결되어 있습니다. 확인해 주세요."

Q: AI 클라이언트를 바꿔도 사용할 수 있나? 가능하다. 승인은 SSH 세션에 바인딩되어 있고 Agent에 바인딩되지 않는다. 호스트 콘솔 MCP에 연동된 모든 로컬 AI는 동일한 세션을 발견하고(임대가 비어 있을 때) 인수할 수 있다.

Q: 여러 SSH에 동시에 연결하면 어떻게 되나? AI는 세션 ID와 정확한 별칭을 동시에 제공해야 이중 확인이 완료되어, 잘못된 호스트를 조작하는 것을 방지한다.

Q: sudo 비밀번호가 AI에게 노출되나? 아니다. 비밀번호는 로컬 금고에서 복호화된 후 SSH 표준 입력을 통해 직접 원격 sudo로 전달되며, AI를 거치지 않고, 명령 텍스트와 터미널 기록에도 들어가지 않는다(전용 테스트 단언 있음).

Q: 정전 / 종료 시 자격 증명이 유실되나? 아니다. 금고 파일은 Windows 사용자 데이터 디렉터리에 영구 저장되며, 시스템 자격 증명 보호 기능으로 암호화된다. 단, 금고 파일을 신뢰할 수 없는 컴퓨터로 복사하지 말 것.

Q: Linux / macOS를 지원하나? 인터페이스와 로직에는 플랫폼 가정이 없지만, 현재 Windows에서 개발·검증 중이다; safeStorage는 다른 플랫폼에서 각각의 시스템 키체인에 의존한다. 테스트 피드백 환영.

개발

npm run dev      # 浏览器开发预览
npm run desktop  # 构建并启动 Electron 桌面版
npm test         # 29 项测试

개발 참여 시 AGENTS.md를 읽고 프로젝트의 제품 결정 규칙을 확인하라.

라이선스

MIT © 2026 host-console contributors