Servonaut

Servonaut

你的服务器。你的终端。你的 AI Agent。一个 TUI。

在一个终端中管理 AWS、Hetzner、OVH 和自定义服务器 — 内置 AI 助手和 MCP 服务。

快速安装

Linux / macOS：

curl -fsSL https://github.com/zb-ss/servonaut/releases/latest/download/install.sh | bash

Windows（PowerShell）：

irm https://github.com/zb-ss/servonaut/releases/latest/download/install.ps1 | iex

这些脚本来自最新的稳定版，并使用 pipx 从 PyPI 安装 Servonaut。每个版本 都附带 install-scripts_SHA256SUMS，可在运行前校验下载的副本。

或者通过 pipx / pip 直接安装：

pipx install servonaut

桌面应用（预览版），Linux： 从 servonaut.dev/download 下载 .deb，并在安装前查看 Linux 桌面预览版 说明。

试用候选版本

每个版本都会在稳定版发布前几天以候选版本的形式发布（例如 2.28.0rc1）。 候选版本面向希望提前体验下一个版本并愿意报告问题的用户。只有在你明确要求时，pip 和 pipx 才会安装候选版本。

# The newest candidate, with the install script
curl -fsSL https://github.com/zb-ss/servonaut/releases/latest/download/install.sh | bash -s -- --pre

# With pipx: a specific candidate, or the newest one
pipx install --force 'servonaut==2.28.0rc1'
pipx install --force 'servonaut>=0rc0'

# With pip
pip install --upgrade 'servonaut>=0rc0'

# Try one without changing your installation
pipx run --spec 'servonaut==2.28.0rc1' servonaut

# Go back to the newest stable release (your configuration is kept)
pipx install --force servonaut

在 Windows 上，请在运行 PowerShell 安装程序前执行 $env:SERVONAUT_PRE = "1"。请避免使用 pip install --pre 和 pipx install --pip-args=--pre：它们还会安装 Servonaut 依赖项的预发布版本，其中有些无法与 Servonaut 正常配合。

使用候选版本期间，更新检查会提供更新的候选版本，随后提供稳定版。稳定版安装始终只会收到稳定版更新。请在 GitHub issues 中报告问题。详情请参阅： 候选版本。

独立 CLI 预览版

目前正在验证适用于 Windows x64、macOS Intel 和 Apple Silicon，以及 Ubuntu x64 的独立纯控制台压缩包。它们尚未发布，也无法下载。在提供带签名的发布安装程序之前，请使用 pipx 或 pip 安装 Servonaut。

从源代码手动安装：

git clone https://github.com/zb-ss/servonaut.git
cd servonaut
pipx install .

使用 AI Agent 设置

想让 AI Agent 全程代劳？将此提示词粘贴到 Claude Code、Cursor 或任何编码助手中 — 它会安装 Servonaut、生成配置，并引导你完成 AWS / SSH / 堡垒机 / 自定义服务器 / AI 提供商设置以及 MCP 服务设置。

Install and configure Servonaut, a TUI for managing servers (AWS EC2, OVHcloud, Hetzner Cloud, and custom SSH servers).

1. Install with all optional features: `pipx install 'servonaut[all]'`
   (bundles the MCP server + OVH/Hetzner SDKs + keyring; AI log analysis needs no extra. Use plain `pipx install servonaut` for a minimal install.)
2. Run `servonaut` once to generate ~/.servonaut/config.json
3. (Optional) If I have a Servonaut account, run `servonaut login` to unlock the hosted features: Servonaut AI (chat with my fleet, no local API key), config sync across machines, Memory Sync, and proactive monitoring (Findings). Servonaut works fully offline against my own credentials if I skip this.
4. Read ~/.servonaut/config.json and help me configure:
   - AWS regions to scan (default scans all, set `regions` array to limit)
   - Default SSH username (`default_username`, default "ec2-user")
   - Cache TTL (`cache_ttl_seconds`, default 3600)
   - Terminal emulator if not auto-detected (`terminal_emulator`)
5. If I use bastion/jump hosts, help me set up `connection_profiles` and `connection_rules`
6. If I have non-AWS servers, help me add them to `custom_servers`
7. If I use OVHcloud or Hetzner Cloud, help me add the API credentials so those instances merge into the fleet
8. For AI log analysis or chat with my own model (instead of Servonaut AI), help me configure `ai_provider` (openai/anthropic/gemini/ollama)
   - Each provider has its own key field (`openai_api_key`, `anthropic_api_key`, `gemini_api_key`, `ollama_api_key`); local Ollama needs none
   - Key fields support `$ENV_VAR` and `file:~/.secrets/key` syntax so secrets stay out of the config file
9. Install the MCP server into my coding agent: `servonaut --mcp-install claude` (or `cursor`, `windsurf`, `opencode`, `vscode`, `codex`, `agy`, `gemini`, `all`)
10. (Optional) To let AI agents/teammates reach this machine over the relay — and to run proactive Findings scans — start it with `servonaut connect`

After setup, launch with `servonaut` and walk me through the key features, including the Findings inbox if I enabled the hosted features.

截图

功能

徽章：Solo+ = 包含在付费 Solo / Teams 计划中。

核心功能与连接

• 交互式 TUI — 支持鼠标和键盘，由 Textual 驱动。
• 多服务商资源池 — 支持 AWS EC2、OVHcloud（专用服务器 / VPS / Public Cloud）、Hetzner Cloud，以及任意服务商的自定义服务器（DigitalOcean、本地部署等）；所有区域的服务器均汇总在一个视图中，可搜索。
• 每个服务商支持多个账户 — 同一资源池中可使用多个 AWS 账户（命名配置文件）、Hetzner 项目和 OVH 账户；服务器显示为 account/name，每项操作均在该服务器所属账户中执行。→ 文档
• 单实例仪表板 — 点击服务器即可打开 Server Actions 视图：查看内存快照（操作系统、磁盘、Web 技术栈、数据库、运行时、容器），以及可选启用的实时资源监控（L — CPU / RAM / 负载 / 磁盘 / 运行时间，仅在视图打开时轮询）。
• SSH 和 SCP — 按一个键即可在新终端窗口中启动 SSH（自动检测终端模拟器）；上传和下载文件及目录。
• 运行远程命令 — 覆盖面板提供实时流式输出、历史记录和已保存的常用命令。
• 远程文件浏览器 — 交互式文件树导航，可在仪表板内嵌显示，也可全屏显示。
• 实时日志查看器 — 通过 tail -f 流式查看日志，支持暂停、搜索和切换日志。
• 稳健的 SSH — 支持堡垒机 / 跳板服务器（ProxyJump / ProxyCommand），默认启用保活（可调整），可按主机设置 extra_ssh_options 以兼容旧设备，并自动发现密钥。
• SSH 主机密钥检查 — 首次使用时信任：首次连接会记录服务器的主机密钥；后续连接若提供不同密钥，则会被拒绝，并在确认密钥变更后提供用于删除旧密钥的准确命令。→ 文档

云服务商管理

• OVHcloud — OVH → ⚙ Manage：创建 / 启动 / 停止 / 重启 / 删除（Cloud / VPS / 专用服务器）；提供区域优先的创建向导和基于 API 的定价，以及 DNS、IP 网段和故障转移 IP、快照、块存储和账单管理。
• Hetzner Cloud — Hetzner → ⚙ Manage：完整生命周期管理和项目 SSH 密钥注册表，并提供功能相当的 CLI（servonaut hetzner …）。新服务器会自动注册。→ 文档

可观测性与安全

• 主动监控 — Findings （Solo+） — 云端检测器会将资源池问题（磁盘、服务故障、慢查询、与 fail2ban 交叉比对的凭据扫描、容器运行状况、TLS 过期、待处理更新）显示为可分诊卡片，并提供受控的一键修复（服务器签名预览 → 人工确认 → 仅允许指定动词的执行器；封禁 IP 或续期证书）。→ 指南
• CloudWatch Logs 浏览器 — 查看日志组，提供热门 IP 分析、IP 地理位置查询和 AbuseIPDB 查询。
• CloudTrail 浏览器 — 查看 AWS CloudTrail 事件，支持按区域 / 时间 / 事件 / 用户筛选。
• IP 封禁管理器 — 通过 AWS WAF、安全组或 NACL 封禁 IP，并提供审计记录。
• 关键词服务器扫描 — 搜索各实例中的文件内容。

AI

• Servonaut AI (Solo+) — 托管式 AI 网关；无需本地 API 密钥，即可与机群对话。模型可以查看日志、运行命令（需确认），并通过中继排查故障 — 凭据和 SSH 密钥绝不会离开命令行。可在行内查看配额 / servonaut ai quota。
• 使用自己的密钥 — 在 Settings → AI Provider 中按提供商配置 OpenAI / Anthropic / Gemini / Ollama 密钥（本地 Ollama 无需密钥）。这些提供商均可与 Servonaut AI 共存，并可按会话切换。
• 内置 AI 聊天 — 可针对你的实例调用工具的大模型助手（与下文所述 MCP 工具接口相同）。
• AI 日志分析 — 使用 OpenAI、Anthropic、Gemini 或 Ollama 分析日志，并估算费用。
• 语音 — 按 ctrl+t 即可在聊天面板中口述，让助手朗读回复，或通过对话模式（ctrl+n）实现完全免提操作：麦克风会在轮次之间保持开启，回复也会以语音播报；还可选择开启插话功能（耳机模式），通过说话打断回复。转录和语音合成完全在你的设备上运行，因此音频不会离开工作站。需主动启用 — 在 Settings 中启用前不会下载任何内容。→ 文档

记忆与密钥

• 服务器记忆 — 按服务器持久缓存 OS / 运行时 / 服务 / Web 技术栈 / 日志 / 数据库 / 容器 / git / 磁盘信息；可选后台自动扫描整个机群。→ 文档
• 记忆同步 (Solo+) — 将机群记忆端到端加密备份到 servonaut.dev（X25519 + AES-256-GCM，使用你的密码短语），支持偏差检测、跨设备历史记录和可选自动同步。在侧边栏中选择 ☁ Memory Sync。
• 数据库凭据库 (Solo+) — 扫描服务器，查找应用已在使用的数据库凭据；将密码按站点标签存入密钥库，并让 db_* 工具按名称解析凭据 — 配置或 Agent 上下文中均无需包含密码。→ 文档

Agent 与自动化（MCP）

• MCP 服务 — 为 Claude Code、Cursor、Windsurf 等提供约 80 种工具：实例运维、AWS / Hetzner / OVH 生命周期管理、S3、日志分析与 IP 封禁、Docker 检查、系统健康探测、SSH 密钥增删改查、记忆查询，以及经过身份验证的 REST 代理 — 由三层防护机制（readonly / standard / dangerous）保护，并记录 JSONL 审计日志。→ 详情见下文
• MCP 中继 — servonaut connect（或通过 TUI 自动启动）会保持 Mercure SSE 连接开启，让 Agent 和团队成员能够向此设备发送工具调用。令牌绝不会离开命令行。
• 团队 Agent 规则 (Teams 计划) — 团队所有者和管理员可决定成员的 AI Agent 在团队共享服务器上能够执行哪些操作：按角色和服务器设定权限级别，并配置允许的命令和屏蔽模式。规则由 servonaut.dev 签名，并由每位成员的 Servonaut 校验，适用于任何提供商的 AI 聊天、通过中继发送的 Servonaut AI 工具调用，以及所有 MCP Agent；若无法校验规则，团队服务器将保持只读。→ 文档
• Servonaut Cloud 账户 — 可选运行 servonaut login，以解锁跨设备配置同步和 MCP 中继。
• 配置同步 — 通过 servonaut.dev 同步客户端加密的 config.json 快照，并使用由你掌控的密码短语进行保护。

便捷功能

• 实例缓存 — 采用过期时重新验证机制，快速启动。
• 自动更新 — 启动时检查并支持一键更新（servonaut --update）。稳定版安装仅会收到稳定版发布；请参阅候选版本。
• 终端快捷方式 — servonaut --install-desktop 会添加一个在终端中打开 TUI 的启动器：Linux 上为 Servonaut (terminal)，macOS 上为 ~/Applications 中的 Servonaut Terminal。
• 完全可配置 — 所有设置均位于 ~/.servonaut/config.json。

前置条件

• Python 3.10+
• 已配置 AWS CLI（~/.aws/credentials 和 ~/.aws/config）
• SSH 客户端（Linux/macOS 上为标准组件，Windows 上为 OpenSSH）
• 用于隔离安装的 pipx（推荐）

AWS 凭证需要具备 ec2:DescribeInstances 和 ec2:DescribeRegions 权限。可选功能还需要其他权限：

开始使用

servonaut

这就是全部界面。TUI 是使用 Servonaut 的主要且推荐的方式 — 每项功能（舰队视图、SSH、远程命令、日志、IP 封禁、AI 聊天、服务器记忆、提供商管理）都可从侧边栏访问，并全面支持鼠标和键盘操作。

以下是一些你可能一开始就会用到的标志：

servonaut --update                # Check for updates and upgrade
servonaut --install-desktop       # Add a launcher that opens the TUI in a terminal (Linux/macOS)
servonaut --setup-ovh             # Guided OVHcloud credential setup
servonaut --debug                 # Verbose logging to stderr

**无头模式与自动化：**每项主要功能也都提供可脚本化的 CLI（servonaut connect、servonaut memory、servonaut ai、servonaut hetzner、servonaut secrets），适用于 CI 运行器、cron 作业以及没有交互式会话的机器 — 请参阅 CLI 参考。想要接入 AI Agent？请跳转至 面向 AI Agent 的 MCP 服务。

键盘快捷键

可以做什么

TUI 打开后会显示统一实例列表（AWS、OVH、Hetzner 和自定义服务器都在一个可搜索的表格中）。可折叠的左侧边栏按用途对其他内容进行分组：

核心

• 📋 实例 — 搜索统一的服务器集群并通过 SSH 连接
• 💻 自定义服务器 — 添加 / 编辑 / 移除非 AWS 服务器（DigitalOcean、本地部署等）
• 🔑 SSH 密钥 — 配置默认密钥和每个实例的密钥

日志与安全

• 📊 CloudWatch — 浏览 AWS 日志组，支持 Top IP 分析、操作筛选（全部/允许/阻止）、IP 地理位置查询和 AbuseIPDB 查询
• 🔒 IP 封禁管理器 — 通过 WAF、安全组或 NACL 封禁 IP
• 🔍 CloudTrail — 使用筛选条件审计 AWS API 活动

工具

• 🧠 Fleet Memory — 扫描 / 刷新 / 检查可供 AI 查询的事实缓存，并可选择定时后台自动扫描（批量扫描在后台运行，即使离开面板也会继续）
• ☁ Memory Sync — 在设备间加密备份服务器集群记忆（Solo+）
• 🛡 Findings — 主动监控收件箱：扫描、审核并分类整个服务器集群中检测到的问题（Solo+；Free 显示升级卡片）
• 🔄 Sync Config — 加密配置快照（Solo+）
• 🔧 设置 — 配置、扫描规则、AI 提供商、AbuseIPDB 密钥

OVH（配置后显示）

• ⚙ 管理 — OVH 实例表格，提供可感知状态的生命周期工具栏（创建 / 启动 / 停止 / 重启 / 删除）
• 🔑 SSH 密钥 — 项目级 SSH 密钥注册表（创建向导会从中注入密钥）
• DNS 区域 · IP 管理 · 块存储 · 账单

Hetzner（配置后显示）

• ⚙ 管理 — Hetzner 服务器表格，提供完整的生命周期工具栏（创建 / 开机 / 关机 / 重启 / 删除）
• 🔑 SSH 密钥 — Hetzner Cloud 项目 SSH 密钥注册表

账户

• 登录 · 团队 · 错误报告

服务器操作 — 点击任意实例行都会打开该实例的控制面板：详情窗格显示服务器身份信息、记忆快照和可选的实时资源监控（L），操作栏则包含：

• 浏览文件（内嵌）· 运行命令 · SSH 连接 · SCP 传输
• 查看扫描结果 · 查看日志（tail -f）· AI 分析 · Findings（F）
• 封禁 IP · 管理 / 验证 SSH Ref

SSH Ref 编辑器可与 Bitwarden 密钥库配合使用——从列表中选择 SSH 密钥，无需粘贴 UUID；也可直接从 ~/.ssh 导入密钥（包括受密码短语保护的密钥），因此即使机器上没有本地密钥，也能建立连接。TUI、CLI 和 MCP Agent 都会在连接时从密钥库解析密钥 (Solo+)。→ 文档

命令历史会跨会话保留——按 Ctrl+R 搜索历史记录和已保存的命令，按 Ctrl+S 收藏常用命令。

实例缓存

配置

所有配置都存放在 ~/.servonaut/config.json 中，首次运行时会自动创建。

完整参考文档请参阅配置指南，其中包括连接配置文件、自定义服务、扫描规则和匹配条件。

**SSH 保活：**默认情况下，所有连接都会发送保活信号，避免由 Agent 驱动的长时间或空闲会话断开。可通过 config.json 中的 ssh 块全局调整（server_alive_interval、server_alive_count_max、tcp_keepalive、connect_timeout）。

**旧版 / 特殊情况 SSH 主机：**连接配置文件和自定义服务都支持 extra_ssh_options 数组，可为每台主机追加任意 -o KEY=VALUE 标志——可用它连接较旧的 OpenSSH 主机（HostKeyAlgorithms=+ssh-rsa）、覆盖保活设置，或设置连接超时，而不必削弱全局 SSH 默认设置。请参阅按主机调整 SSH 设置。

机密信息：config.json 中的 API 密钥支持 $ENV_VAR 和 file:~/.secrets/key 语法，使配置文件不包含机密信息。你也可以创建 ~/.secrets/servonaut.env 并写入 KEY=value 键值对——启动时会自动加载。

可选依赖

# MCP server for AI agents
pipx inject servonaut mcp
# or: pip install 'servonaut[mcp]'

# Hetzner Cloud / OVHcloud provider SDKs
pip install 'servonaut[hetzner]'
pip install 'servonaut[ovh]'

# Voice — all processed locally, nothing sent to a speech service
pip install 'servonaut[voice]'            # voice input, batch engine
pip install 'servonaut[voice-streaming]'  # voice input, live text as you speak
pip install 'servonaut[voice-output]'     # spoken replies / conversation mode

# Install everything
pip install 'servonaut[all]'

语音功能还需要 PortAudio 系统库（sudo apt install libportaudio2、brew install portaudio）以及一次性模型下载，这些都可以在 Settings → AI → Voice Input 中进行。请参阅 docs/voice.md。

AI 日志分析（OpenAI、Anthropic、Gemini、Ollama）无需额外安装—— httpx 已包含在基础依赖中。

面向 AI Agent 的 MCP 服务

本节介绍如何为 AI Agent（Claude Code、Cursor、Windsurf、……）配置连接，

而非日常交互使用。如果你是管理服务器集群的用户， 推荐使用上文的 TUI。

Servonaut 内置了 MCP 服务，可向 Claude Code 等 AI Agent 提供工具：

# Auto-install into a coding agent
servonaut --mcp-install claude     # Claude Code
servonaut --mcp-install cursor     # Cursor
servonaut --mcp-install windsurf   # Windsurf
servonaut --mcp-install opencode   # OpenCode
servonaut --mcp-install vscode     # VS Code Copilot
servonaut --mcp-install codex      # Codex CLI
servonaut --mcp-install agy        # Antigravity CLI
servonaut --mcp-install gemini     # Gemini CLI
servonaut --mcp-install all        # All of the above

# Run MCP server manually (stdio transport)
servonaut --mcp

重新运行安装程序时，只会更新 Servonaut 的启动命令和必需的环境变量转发。 其他 MCP 服务和用户自有设置（例如超时、信任设置、工具筛选器和自定义环境变量）都会保留。 机密值绝不会复制到 Agent 配置中：受支持的客户端会使用引用、变量名允许列表或继承的环境变量，来提供 SSH/Bitwarden 状态、AWS 凭证、Servonaut 端点，以及本地 Servonaut 配置中找到的 $ENV_VAR 引用。遇到无效的 Agent JSON 配置时，程序会拒绝写入，而不是覆盖文件；配置写入采用原子操作，不会替换符号链接的点文件。

SSH 支持的 MCP 工具会优先使用配置的本地密钥或保险库密钥。如果该密钥无法通过身份验证，且已转发 SSH_AUTH_SOCK，Servonaut 会在不强制使用已配置身份的情况下，改用 Agent 重试一次。身份验证失败会作为失败返回并记录审计，不会被当作成功的工具调用。

仅用于 Agent / 无头安装

无需使用 TUI，也能将 Servonaut 用作 Agent 工具箱。MCP 服务完全支持无头运行——servonaut --mcp 绝不会加载终端 UI（此行为由回归测试强制保证），因此你可以将它安装在服务器或 CI 环境中，纯粹作为编码 Agent 的 MCP 后端：

pipx install 'servonaut[mcp]'
servonaut --mcp-install claude   # or cursor, windsurf, opencode, vscode, codex, agy, gemini, all

凭证和服务器的配置方式与安装 TUI 时相同（ ~/.servonaut/config.json、$ENV_VAR / file: 机密信息语法——请参阅 配置指南）。使用 Servonaut Cloud 功能 （中继、配置同步、托管 AI）时，servonaut login 会以完全无头的方式运行设备授权流程——可在任意设备的浏览器中批准登录。Agent 的所有操作都会经过相同的防护级别，并记录到 ~/.servonaut/mcp_audit.jsonl。 来自 Bitwarden 的 SSH 密钥（机器上无需存放密钥）。 如果你的实例已保存 Bitwarden SSH ref，SSH 工具（run_command、get_logs、transfer_file 等）会在连接时从你的保管库中解析私钥，无需将密钥存放在 ~/.ssh 中——因此，在全新服务器或 CI 机器上运行的 Agent 无需任何本地密钥也能连接。无头进程无法提示你输入主密码，因此请先解锁保管库一次，并将会话导出到运行 MCP 服务（或 servonaut connect）的环境中：

export BW_SESSION=$(bw unlock --raw)   # unlock once; stays valid until you `bw lock` or the shell exits
servonaut --mcp                         # child inherits BW_SESSION

每条命令执行期间，密钥都会写入一个权限为 0600 的私有临时文件，并在命令结束后立即删除。如果保管库已锁定或未安装 bw，工具会回退到本地密钥——不会影响正常工作的本地配置。

可用工具：

工具列表会筛选出实际可用的工具：只有配置了 OVH 和 Hetzner 时才会显示对应工具；只有定义了至少一个 IP 封禁目标时才会显示 ip_ban_* 工具；只有启用了记忆子系统时才会显示 *_server_memory* 工具。CloudWatch/CloudTrail 和核心实例工具始终可用（AWS 是基础提供商）。

• cloudwatch_top_ips 会解析 WAF/ALB 结构化日志，按允许 / 封禁次数对客户端 IP 排名——可将它与 cloudtrail_lookup_events 配合使用以交叉验证，然后通过 ip_ban_set 使用 WAF、安全组或 NACL 封禁 IP。
• whoami 会返回会话元数据——绝不会暴露 OAuth bearer。
• api_request 允许 Agent 向 servonaut.dev 发起经过身份验证的 REST 调用，并自动刷新 401 状态，同时受命令行端速率限制（30 次 / 分钟）。Bearer 保留在命令行端。
• mcp_tool_call 会针对托管 MCP mcp.servonaut.dev 封装 JSON-RPC 2.0 tools/call 信封——当你的套餐包含高级工具时，可用它调用这些工具。
• get_server_memory(id) 会返回缓存的事实快照——Agent 会在任何 SSH 往返之前调用此工具，无需运行 run_command，即可回答大多数操作系统 / 运行时 / 服务相关问题。传入 format='context_block' 可获取 <CONTEXT> 信封，用于直接注入提示词。 保护级别： readonly（仅限列表、状态和内省操作——包括 CloudWatch/CloudTrail 和 ip_ban_list_* 查询）、standard（读取 + 安全命令 + 已认证的 REST + 电源管理——启动 / 停止 / 重启 / 关机 + S3 下载）、dangerous（所有操作，包括 create_server / delete_server / transfer_file / ip_ban_set / aws_terminate_instance / aws_run_instances / S3 变更操作（s3_create_bucket、s3_delete_bucket、s3_upload_object、s3_delete_object、s3_copy_object、s3_move_object、s3_generate_presigned_url））。无论保护级别如何，危险的 shell 命令（rm -rf、shutdown、reboot 等）始终会被拦截。变更类工具的描述中明确提示“调用前请先向用户确认”；顶层 MCP 指令说明了三步协议（总结 → 说明参数 → 等待肯定回复）。所有操作都会记录到 ~/.servonaut/mcp_audit.jsonl。

Servonaut Cloud 账号

可选——Servonaut 可完全离线运行，并使用你自己的 AWS / OVH 凭证。在 servonaut.dev 登录即可解锁：

• 配置同步——在多台机器之间推送 / 拉取加密后的 config.json 快照。密码短语不会离开你的 客户端；服务端只能看到密文。侧边栏中的 🔄 Sync Config 入口可直接打开快照管理器（拉取最新 / 推送新的 / 恢复 / 重命名 / 删除）。
• MCP 中继——Mercure SSE 通道，可让 AI Agent 和 队友向这台机器分派 MCP 工具调用。中继连接期间，https://servonaut.dev/account 会显示你的 CLI 在线，托管 Agent 也能连接到它。
• 记忆同步（Solo+）——带有漂移检测功能的加密集群记忆备份。打开侧边栏中的 ☁ Memory Sync，点击 Unlock Memory Sync，然后输入密码短语。首次注册和重启后解锁都在同一屏幕进行——你的私钥会在本地用密码短语加密，因此服务端永远无法看到它。 解锁后，点击 Sync now，即可将每台缓存服务器的记忆 模块作为加密信封推送；也可以开启 auto-sync，在后台清空 队列，确保服务端副本（及每周摘要）保持最新。解锁状态会在重启后保留：勾选 Remember on this device，下次启动时即可通过操作系统钥匙串静默重新解锁 （30 天后会再次提示；也可选择 Forget on this device 清除）。如果 你拒绝，记忆同步将保持休眠状态，直到你下次打开记忆 部分。每项功能的设置（摘要频率、Mercure 推送、AI 同意） 位于设置面板底部，并存储在你的 servonaut.dev 账号中。

在 TUI 的 Account / Login 屏幕登录。设备流程身份验证成功后， TUI 会自动启动进程内中继监听器，侧边栏指示器会变为 ● connected。

监听器与 TUI 窗口绑定——关闭 TUI 后，连接会在约 60 秒后断开。若要始终保持可访问（CI 运行器、 无头设备），请改用 servonaut connect --bg；CLI 和 TUI 通过 ~/.servonaut/relay.lock 协作，确保两者不会同时运行。若 --bg 监听器正占用连接，TUI 会显示 external listener (PID N)。

servonaut connect                 # Foreground relay (Ctrl+C to stop)
servonaut connect --bg            # Detach; writes ~/.servonaut/relay.pid
servonaut connect --status        # Local + backend view with divergence warning
servonaut connect --stop          # SIGTERM the background listener
servonaut connect --reconnect     # Heal a stale SSE socket (stop+start)
servonaut connect --force-bg      # Take over from a TUI's in-process listener

完整标志说明请参阅CLI 参考 → servonaut connect。

令牌存储在 ~/.servonaut/auth.json 中，权限模式为 0600，通过 tmp + os.replace() 原子写入。如果旧版本构建留下的文件对所有用户均可读，下次运行时会自动修正权限。

主动监控 — 发现项（Solo+）

服务端检测器会扫描你的服务器群，查找问题，并将每个问题作为可供分类处理的发现卡片发布：严重程度、说明、证据和修复选项。检测在 Servonaut 云端运行；此客户端只会通过中继连接运行只读探测并呈现结果——不会在本地分析或作出判断。

• 服务器群收件箱 / 单实例 — 在侧边栏中选择 🛡 Findings 查看整个服务器群，在任意服务器上按 F 查看该实例。
• 立即扫描（s）— 通过中继派发只读探测（必须运行 servonaut connect 或 TUI 自动启动）；不适用的检测器会说明原因，而不是静默失败。
• 分类处理 — 确认（a）、解决（r）或忽略（x）；状态会同步到服务端。
• 受控的一键修复 — 自动化修复仅会在明确点击后，通过服务端签名的预览和动词白名单执行器运行（状态变更需要输入确认，先进行试运行，全程审计）。当前支持的修复：阻止源 IP（AWS WAF / Security Group / NACL，或服务器自身的防火墙——nftables / ufw / firewalld）以及续订 TLS 证书。

→ 完整指南：docs/proactive-monitoring.md — 检测器、检测／探测／修复模型，以及安全与隐私设计。Solo 和 Teams 套餐均包含此功能（受监控实例数量受限）；Free 套餐会显示升级卡片。

密钥管理（Solo+）

通过可插拔的后端提供程序集中管理 SSH 密钥和其他命名密钥。日常使用时，这个功能不会影响你的操作：配置完成后，每次连接时都会自动从提供程序解析 SSH 密钥——你仍然只需在 TUI 中点击 SSH，一切照常运行。以下命令用于一次性设置。MVP 支持两种后端：

• LocalProvider — 密钥存储在 ~/.servonaut/secrets.json 中（权限模式为 0600、原子写入，信任模型与 auth.json 相同）。Solo 和 Teams 套餐始终可用。
• BitwardenProvider（bws） — 密钥存储在团队的 Bitwarden Secrets Manager 项目中。团队管理员通过 https://servonaut.dev/account/teams/<slug>/secrets 配置项目；CLI 获取元数据，并通过本机 bws 二进制文件使用你自己的访问令牌进行读写。令牌不会离开你的机器——servonaut.dev 只存储项目 ID 和保存令牌的环境变量名称。

如需将 Bitwarden 用作团队的后端：

# 1. Install the bws CLI (one-time)
servonaut secrets install bws         # macOS: brew · Linux: cargo
# Windows / other → prints upstream install URL.

# 2. Mint a BWS access token (https://bitwarden.com/help/personal-access-tokens/)
#    and export it
export BWS_ACCESS_TOKEN=<your-token>

# 3. Verify wiring
servonaut secrets status              # your plan and where secrets are kept (--json for scripts)

# That's it — SSH key resolution now checks Bitwarden first, ~/.ssh as
# fallback. Push a key into BWS with `bws secret create`:
bws secret create "$(basename ~/.ssh/prod-server)" \
                  "$(cat ~/.ssh/prod-server)" \
                  --project-id <project-uuid-from-status>

每次 SSH 连接时，按以下顺序解析密钥：

1. 按密钥名称查询活动提供程序（如果已配置，则为 Bitwarden）。
2. 搜索 ~/.ssh（现有模式 + 模糊匹配）。
3. 使用 config.json::instance_keys[<id>] 或 config.default_key 中存储的路径。

Free 套餐用户继续使用仅基于 ~/.ssh 的旧流程，行为完全不变。通过提供程序获取的密钥会以 0600 权限存放在 ~/.servonaut/keys/<name> 中。

威胁模型和设计说明通过代码库中的内联文档字符串固定记录在 services/secret_provider.py、services/bitwarden_provider.py 和 services/secret_provider_resolver.py 中。

数据库凭据保管库

同一密钥存储还支持数据库凭据保管库：扫描服务器，查找其应用已在使用的数据库凭据——.env / DATABASE_URL（包括 DATABASE_URL_PROD / _STAGING 变体）、wp-config.php、configuration.php、Magento env.php 以及 docker-compose 的 environment: 块；同时提供只读的 sudo -n 回退方式，以覆盖 root 所有的文件和容器化堆栈。按站点标签保存密码，db_processlist / db_top_queries 工具即可按名称解析密码——密码不会写入你的配置，也不会进入 AI Agent 的上下文。Secrets → DB coverage视图会按站点列出哪些实例已覆盖，并支持直接编辑标签和移除。 完整文档

开发

# Run directly (primary dev workflow)
PYTHONPATH=src python3 -m servonaut.main

# Run with debug logging
PYTHONPATH=src python3 -m servonaut.main --debug

# Install editable
pip install -e .

# Update pipx installation after changes
pipx install . --force

# Run tests
pip install -e ".[test]"
pytest

有关代码库结构和设计模式，请参阅架构。

故障排除

如需有关 SSH 连接、主机密钥变更、堡垒主机、密钥管理、AWS 凭据以及如何从候选发布版本回退的帮助，请参阅 故障排除指南。

运行时文件

所有运行时文件都位于 ~/.servonaut/ 下：

日志记录

日志始终写入 ~/.servonaut/logs/servonaut.log。使用 --debug 可在 stderr 输出详细信息。

SSH 连接失败时，终端窗口会保持打开，并显示错误和退出代码。

收录于

也已发布到官方 MCP Registry，名称为 dev.servonaut/servonaut。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。