主机台 HostConsole

Let AI operate SSH, but keep the keys in your own hands.

English · 简体中文

Features · Screenshots · Quick Start · Connect Your AI · Security Model · How It Works · FAQ

Why HostConsole

You've probably run into this dilemma: you want AI to help you look after your NAS, server, or router, but handing SSH keys and passwords directly to an AI client just doesn't feel right——

• Once a key is pasted into an AI config, you've handed over the entire machine, and you can't be sure where it will be recorded;

• Generating a temporary public key for AI and installing it into authorized_keys means remembering to clean it up afterward—annoying and easy to forget;

• When AI runs sudo, you can't see what command it's about to execute, let alone approve it;

• Switch to a different AI client (Codex, OpenCode, ZCode...), and the whole authorization flow has to be redone from scratch.

HostConsole's answer: keys never leave your computer.

You manually connect SSH in HostConsole (password / private key, encrypted at the system level), then hand the "authorized session" to AI through a local MCP bridge. AI only ever sees the session alias (e.g., "Home NAS"), can operate the terminal, and can be paused and disconnected by you at any time—but it never gets the address, port, username, or private key.

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

Related MCP server: SSH MCP Server

Use Cases

• 🏠 Home NAS / home server: Let AI check SMART status, clean up Docker, fix RAID alerts—without handing over root access

• 🖥️ Personal VPS / dev machine: Deploy, check logs, tweak nginx configs—AI does the work, you approve

• 🌐 Router / network devices: Occasionally need AI to help diagnose, but device credentials must never leak

• 🔁 Multi-AI-client users: Codex, OpenCode, ZCode, WorkBuddy share the same set of authorized SSH sessions—no re-authorization when switching tools

• 🛡️ Audit-minded people: Every sudo command must pass an approval dialog that pops up in front of you, with the full command text clearly visible

Screenshots

Core Features

• 🔐 Credential isolation: SSH address, port, and username exist only in local config; passwords and private keys are encrypted via Electron safeStorage (Windows system credential protection) into a separate vault. Through MCP, AI can only get the session alias and authorization status—nothing else is visible, and this is guaranteed by dedicated test assertions.

• 🚦 Dual permission modes: Relatively safe (AI can only run seven fixed categories of read-only checks: identity / system / storage / process / container / service / log) and fully open (full terminal access for the current SSH account), switchable at any time with one click.

• 💳 sudo approval flow: When AI needs elevated privileges, it calls a separate exec_sudo; HostConsole automatically pops up a dialog showing the raw command text, and it only executes after you approve. Optional 30-minute (default, adjustable 0–240 minutes) no-prompt window; the sudo password is delivered from the local vault to the remote end directly via SSH standard input—it never enters the command text, the terminal history, or the AI context.

• 🟢 Agent Hub: All connected AI agents are shown in real time as status lights (online / offline / controlling), each with its own connection toggle—turning one off immediately releases its SSH control and sudo authorization without affecting other agents or disconnecting SSH.

• 🧙 One-click setup wizard: Automatically detects and writes six MCP config formats—Codex TOML, OpenCode JSONC, ZCode, WorkBuddy, and generic JSON/JSONC—with preview before writing and automatic timestamped backups.

• ✍️ Single-write lease: Only one agent can write to the terminal at a time; other agents can see the occupied status but cannot inject commands. Control only transfers when you explicitly say "take over / force take over."

• 🫸 Instant circuit breaker: "Pause AI" immediately blocks operations while keeping the SSH connection; "Disconnect" revokes authorization, lease, and sudo authorization all at once.

• 🖥️ Local manual command fallback: When AI refuses to execute or interactive input is needed, the UI has a built-in command input box so you can type it yourself.

• 🇨🇳 Fully Chinese UI: Built for Chinese users—from permission modes to error messages, not a single English term needs looking up.

• ✅ 29 security tests: Credential isolation, lease exclusivity, sudo lifecycle, config redaction, and other core security claims are all backed by automated tests (npm test).

Quick Start

Requirements

• Windows 10/11

• Node.js 20+ (with npm)

Launch

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

After the app window closes, it stays in the system tray; SSH sessions are not disconnected.

Three Steps to Get Started

1. Connect: Click "New Connection," choose SSH password / paste private key / select key file; on first connection, verify and pin the host SHA-256 fingerprint (TOFU).

2. Authorize: After connecting, choose "Relatively Safe" or "Fully Open" on the right.

3. Summon AI: Tell any AI already connected to HostConsole—

   This machine is connected to "Home NAS" via SSH, please check the disk and Docker container status.

   AI will automatically discover the authorized session via MCP, acquire control, and get to work.

Connect Your AI

HostConsole provides the MCP service over a local named pipe (\\.\pipe\host-console-mcp), listening on no TCP port, unreachable by cloud agents.

The easiest way is to click the "Connect Agent" button in HostConsole and let the built-in wizard write the config automatically (with automatic backup and preview). Below is the manual configuration reference:

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's mcp.servers), WorkBuddy (~/.codebuddy/.mcp.json's mcpServers), and any generic JSON/JSONC can be connected using the same structure, or simply use the built-in wizard.

After writing the config, you must fully quit and restart the corresponding AI client (MCP clients only load config at startup). Once connected, a green status light appears in HostConsole's "Agent Hub," and the authorized session's alias and permission mode are synced to AI.

Security Model

What AI Can and Cannot See

Multiple Lines of Defense

1. Pipe-level isolation: MCP binds only to a local named pipe—no network egress, no open ports; no one outside this computer can connect.

2. Single-write lease: Among concurrent agents, only one can operate the terminal; takeover requires explicit user action.

3. Two-factor confirmation: In multi-session scenarios, AI must provide both the session ID and the exact alias to acquire control; mismatches are rejected.

4. sudo lifecycle: Temporary authorization is bound only to the current session and the currently controlling agent; it expires immediately on pause / disconnect / takeover / privilege downgrade / timeout, and can also be manually ended early at any time.

5. Irreversible credentials: Changing credentials requires disconnecting SSH first; old credentials are never echoed, and new credentials overwrite the encrypted vault.

Known Limitations

• A malicious local process running under the same Windows user as HostConsole could theoretically still connect to the named pipe—please do not use "Fully Open" mode on untrusted local machines.

• Currently an MVP; no signed installer or auto-update yet.

MCP Tools at a Glance

9 tools callable from the AI side:

How It Works

主机台 (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: How does AI know to call HostConsole? After MCP is connected, HostConsole proactively syncs the authorized session aliases and permission modes to AI in the initialization message. You just give tasks as usual: "This machine is connected to Home NAS via SSH, please..."

Q: Can I switch to a different AI client? Yes. Authorization is bound to the SSH session, not to any agent. Any local AI connected to HostConsole's MCP can discover and (when the lease is free) take over the same session.

Q: What happens when multiple SSH sessions are connected at once? AI must provide both the session ID and the exact alias as dual confirmation, preventing operations on the wrong host.

Q: Can AI see the sudo password? No. The password is decrypted from the local vault and delivered directly to the remote sudo via SSH standard input—it never passes through AI, never enters the command text or terminal history (guaranteed by dedicated test assertions).

Q: Will credentials be lost on power failure / shutdown? No. The vault file persists in the Windows user data directory, encrypted with system credential protection; but please don't copy the vault file to an untrusted machine.

Q: Does it support Linux / macOS? The UI and logic have no platform assumptions, but development and validation are currently done on Windows; safeStorage on other platforms relies on their respective system keychains. Test feedback is welcome.

Development

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

For development, please read AGENTS.md to understand the project's product decision conventions.

License

MIT © 2026 host-console contributors