Servonaut

Servonaut

あなたのサーバー。あなたのターミナル。あなたの AI エージェント。ひとつの 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 の依存関係もプレリリース版がインストールされ、その一部は正常に動作しません。

リリース候補を使用している間、更新チェックでは新しいリリース候補、その後に安定版リリースが提示されます。安定版のインストール環境には、安定版リリースのみが提示されます。問題はGitHub のイシューで報告してください。詳細：リリース候補。

スタンドアロン 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 エージェントを使ったセットアップ

AI エージェントにすべて任せたいですか？このプロンプトを Claude Code、Cursor、または任意のコーディングアシスタントに貼り付けると、Servonaut をインストールして設定を生成し、AWS / SSH / bastion / カスタムサーバー / 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／パブリッククラウド）、Hetzner Cloud、および任意のプロバイダー（DigitalOcean、オンプレミスなど）のカスタムサーバーを、すべてのリージョンにわたって1つの画面で一覧表示・検索できます。
• プロバイダーごとの複数アカウント — 同じサーバー群で複数の AWS アカウント（名前付きプロファイル）、Hetzner プロジェクト、OVH アカウントを利用できます。サーバーは account/name として表示され、各アクションはサーバー自身のアカウントで実行されます。→ ドキュメント
• インスタンスごとのダッシュボード — サーバーをクリックすると、サーバーアクション画面が開きます。メモリースナップショット（OS、ディスク、Web スタック、データベース、ランタイム、コンテナー）と、オプトイン方式のライブリソースモニター（L — CPU／RAM／負荷／ディスク／稼働時間。画面を開いている間のみポーリング）を表示します。
• SSH と SCP — キーを1回押すだけで新しいターミナルウィンドウから 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 …）も利用できます。新しいサーバーは自動登録されます。→ ドキュメント

オブザーバビリティとセキュリティ

• プロアクティブ監視 — 検出項目 (Solo 以上) — クラウド側の検出機能でサーバー群の問題（ディスク、サービスの異常終了、低速なクエリー、fail2ban と照合した認証情報スキャン、コンテナーの健全性、TLS の有効期限、保留中の更新）を、トリアージ可能なカードとして表示します。ワンクリックでの修復は、段階的な承認フローを経て実行されます（サーバー署名付きのプレビュー → 人による確認 → 許可リストに登録された動詞のみを実行する実行機能。IP のブロックや証明書の更新など）。→ ガイド
• CloudWatch Logs ブラウザー — Top-IP 分析、IP ジオロケーション、AbuseIPDB 検索を備えたロググループを表示します。
• CloudTrail ブラウザー — リージョン／時間／イベント／ユーザーで絞り込める AWS CloudTrail イベントを表示します。
• IP 禁止管理機能 — AWS WAF、セキュリティグループ、NACL を使って IP を禁止し、監査証跡を記録します。
• キーワードによるサーバースキャン — インスタンス間でファイルの内容を検索します。

AI

• Servonaut AI (Solo+) — ホスト型 AI ゲートウェイです。ローカルの API キーなしで、フリートとチャットできます。モデルはリレー経由でログの追跡やコマンドの実行（確認あり）、インシデントのトリアージを行えます。認証情報と SSH キーが CLI の外に出ることはありません。クォータはインラインまたは servonaut ai quota で確認できます。
• 自分のキーを使用 — OpenAI ／ Anthropic ／ Gemini ／ Ollama のキーを、Settings → AI Provider でプロバイダーごとに設定できます（ローカルの Ollama にはキーは不要です）。Servonaut AI と併用でき、セッションごとに切り替えられます。
• 組み込み AI チャット — インスタンスに対してツール呼び出しを行う LLM アシスタントです（以下の MCP ツールと同じインターフェースを使用します）。
• AI ログ分析 — OpenAI、Anthropic、Gemini、Ollama を使って、コストを見積もりながらログを分析できます。
• 音声 — ctrl+t でチャットパネルに音声入力し、返信を読み上げさせるか、会話モード（ctrl+n）で完全なハンズフリー操作ができます。会話モードではターン間もマイクがオンのままになり、返信が音声で読み上げられます。また、オプションの割り込み機能（ヘッドフォンモード）を使えば、返信中に話しかけて中断できます。文字起こしと音声合成はすべてお使いのマシン上で実行されるため、音声がワークステーションの外に出ることはありません。利用はオプトイン方式です。Settings で有効にするまで、何もダウンロードされません。→ ドキュメント

メモリとシークレット

• サーバーメモリ — OS ／ ランタイム ／ サービス ／ ウェブスタック ／ ログ ／ データベース ／ コンテナ ／ git ／ ディスクの情報をサーバーごとにキャッシュし、永続的に保存します。オプションでフリート全体のバックグラウンド自動スキャンも利用できます。→ ドキュメント
• メモリ同期 (Solo+) — フリートのメモリを servonaut.dev にエンドツーエンド暗号化でバックアップします（X25519 + AES-256-GCM、お客様のパスフレーズを使用）。ドリフト検出、デバイス間の履歴、オプションの自動同期を備えています。サイドバーの ☁ Memory Sync から利用できます。
• データベース認証情報の保管庫 (Solo+) — サーバーをスキャンして、アプリがすでに使用している DB 認証情報を見つけ、パスワードをサイトごとのラベルでシークレット保管庫に保存できます。db_* ツールは名前を指定して認証情報を取得できるため、設定やエージェントのコンテキストにパスワードを含める必要はありません。→ ドキュメント

エージェントと自動化（MCP）

• MCP サーバー — Claude Code、Cursor、Windsurf などで使える約 80 個のツールを提供します。インスタンス操作、AWS ／ Hetzner ／ OVH のライフサイクル管理、S3、ログ分析と IP のブロック、Docker の調査、システムヘルスのプローブ、SSH キーの CRUD、メモリクエリ、認証付き REST プロキシに対応しています。3 段階のガード（readonly ／ standard ／ dangerous）と JSONL 監査証跡を備えています。→ 詳細は以下
• MCP リレー — servonaut connect（または TUI の自動起動）で Mercure SSE 接続を維持し、エージェントやチームメイトがこのマシンにツール呼び出しを送れるようにします。トークンが CLI の外に出ることはありません。
• チームのエージェントルール (Teams プラン) — チームのオーナーと管理者は、メンバーの AI エージェントがチーム共有サーバーで実行できる操作を決定できます。ロールとサーバーごとのレベル、許可するコマンド、ブロックするパターンを設定できます。ルールは servonaut.dev によって署名され、各メンバーの Servonaut で検証されます。これは、あらゆるプロバイダーを使う AI チャット、リレー経由の Servonaut AI ツール呼び出し、すべての MCP エージェントに適用されます。検証できないルールがある場合、チームのサーバーは読み取り専用になります。→ ドキュメント
• Servonaut Cloud アカウント — オプションの servonaut login で、マシン間の設定同期と MCP リレーを利用できます。
• 設定同期 — お客様が管理するパスフレーズと組み合わせて、config.json のスナップショットをクライアント側で暗号化し、servonaut.dev 経由で同期します。

便利な機能

• インスタンスのキャッシュ — stale-while-revalidate により、起動を高速化します。
• 自動更新 — 起動時に確認し、ワンクリックで更新できます（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 エージェントを接続しますか？AI エージェント向け MCP サーバーをご覧ください。

キーボードショートカット

できること

TUI を開くと、統合インスタンス一覧が表示されます（AWS、OVH、Hetzner、カスタムサーバーを、検索可能なひとつのテーブルにまとめています）。折りたたみ可能な左サイドバーでは、その他の項目を目的別に分類しています。

コア

• 📋 Instances — 統合フリートを検索して SSH 接続します
• 💻 Custom Servers — AWS 以外のサーバー（DigitalOcean、オンプレミスなど）を追加／編集／削除します
• 🔑 SSH Keys — デフォルトキーとインスタンスごとのキーを設定します

ログとセキュリティ

• 📊 CloudWatch — トップ IP 分析、アクションフィルター（すべて／許可／ブロック）、IP の位置情報、AbuseIPDB 照会を使って、AWS のロググループを閲覧します
• 🔒 IP Ban Manager — WAF、Security Groups、NACLs を使って IP を BAN します
• 🔍 CloudTrail — フィルターを使って AWS API のアクティビティを監査します

ツール

• 🧠 Fleet Memory — AI が照会できるファクトキャッシュをスキャン／更新／確認します。オプションで、スケジュール設定されたバックグラウンド自動スキャンも利用できます（一括スキャンはバックグラウンドで実行され、パネルを離れても継続します）
• ☁ Memory Sync — デバイス間でフリートメモリを暗号化してバックアップします（Solo+）
• 🛡 Findings — プロアクティブ監視の受信トレイです。サーバーが検出した問題をフリート全体でスキャン、確認、トリアージします（Solo+。Free ではアップグレードカードが表示されます）
• 🔄 Sync Config — 暗号化された設定スナップショットです（Solo+）
• 🔧 Settings — 設定、スキャンルール、AI プロバイダー、AbuseIPDB キー

OVH（設定済みの場合に表示）

• ⚙ Manage — 状態に応じたライフサイクルツールバー（Create／Start／Stop／Reboot／Delete）を備えた OVH インスタンスのテーブルです
• 🔑 SSH Keys — プロジェクトレベルの SSH キーレジストリです（作成ウィザードがキーを登録する場所です）
• DNS ゾーン · IP 管理 · ブロックストレージ · 請求

Hetzner（設定済みの場合に表示）

• ⚙ Manage — ライフサイクルツールバー（Create／Power on／Shutdown／Reboot／Delete）を備えた Hetzner サーバーのテーブルです
• 🔑 SSH Keys — Hetzner Cloud プロジェクトの SSH キーレジストリです

アカウント

• ログイン · チーム · バグ報告

サーバーアクション — インスタンスの行をクリックすると、インスタンスごとのダッシュボードが開きます。詳細ペインには、サーバーの識別情報、メモリスナップショット、オプトイン式のライブリソースモニター（L）が表示され、アクションレールには以下の操作が表示されます。

• ファイルを閲覧（インライン） · コマンドを実行 · SSH 接続 · SCP 転送
• スキャン結果を表示 · ログを表示（tail -f） · AI 分析 · Findings（F）
• IP を BAN · SSH Ref を管理／検証

SSH Ref エディターは Bitwarden の保管庫と連携します。UUID を貼り付けずにリストから SSH キーを選ぶか、~/.ssh からキーを直接インポートできます（パスフレーズで保護されたキーも含みます）。そのため、ローカルにキーがないマシンからでも接続できます。TUI、CLI、MCP エージェントは、いずれも接続時に保管庫からキーを取得します（Solo+）。→ ドキュメント

コマンド履歴はセッション間で保持されます。Ctrl+R で履歴と保存済みコマンドを検索し、Ctrl+S でお気に入りを保存できます。

インスタンスキャッシュ

設定

すべての設定は ~/.servonaut/config.json に保存され、初回実行時に自動作成されます。

接続プロファイル、カスタムサーバー、スキャンルール、マッチ条件などの詳細については、Configuration Guide をご覧ください。

SSH キープアライブ： 長時間のセッションや、エージェント主導のセッションがアイドル状態になっても切断されないよう、すべての接続でデフォルトでキープアライブを送信します。config.json の ssh ブロック（server_alive_interval、server_alive_count_max、tcp_keepalive、connect_timeout）で全体設定を調整できます。

古い SSH ホスト／特殊な SSH ホスト： 接続プロファイルとカスタムサーバーのどちらでも、ホストごとに任意の -o KEY=VALUE フラグを追加する extra_ssh_options 配列を指定できます。これを使うと、古い OpenSSH サーバーへの接続（HostKeyAlgorithms=+ssh-rsa）、キープアライブの上書き、グローバルな SSH のデフォルト設定を弱めずに接続タイムアウトを設定できます。ホストごとの SSH 調整 をご覧ください。

シークレット： config.json 内の API キーでは、$ENV_VAR と file:~/.secrets/key の構文を使用できるため、設定ファイルにシークレットを記載せずに済みます。また、KEY=value のペアを記述した ~/.secrets/servonaut.env を作成すると、起動時に自動で読み込まれます。

オプションの依存関係

# 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）と、初回のみ必要なモデルのダウンロードも必要です。これらは「設定」→「AI」→「音声入力」に表示されます。詳しくは docs/voice.md をご覧ください。

AI によるログ分析（OpenAI、Anthropic、Gemini、Ollama）に追加のインストールは不要です。 httpx は基本依存関係に含まれています。

AI エージェント向け MCP サーバー

このセクションは、AI エージェント（Claude Code、Cursor、Windsurf、…）との連携設定を対象としています。 日常的な対話操作向けではありません。フリートを操作する人間の方には、 上記の TUI が推奨インターフェースです。

Servonaut には、Claude Code などの AI エージェントにツールを公開する MCP サーバーが統合されています。

# 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 サーバーや、タイムアウト、信頼設定、ツールフィルター、カスタム環境変数など、ユーザーが所有する設定は保持されます。シークレット値がエージェントの設定にコピーされることはありません。対応クライアントでは、参照、変数名の許可リスト、または継承した環境変数を使って、SSH／Bitwarden の状態、AWS の認証情報、Servonaut エンドポイント、およびローカルの Servonaut 設定にある $ENV_VAR 参照を指定します。エージェントの JSON が無効な場合は上書きせずに処理を拒否し、設定ファイルへの書き込みは、シンボリックリンクされたドットファイルを置き換えずにアトミックに行われます。

SSH を使用する MCP ツールは、まず設定済みのローカルキーまたは保管庫のキーを使用します。そのキーで認証できず、SSH_AUTH_SOCK が転送されている場合、Servonaut は設定済みの ID を強制せずにエージェントを使って一度だけ再試行します。認証の失敗は失敗として返され、監査ログにも失敗として記録されます。成功したツール呼び出しとして扱われることはありません。

エージェント専用／ヘッドレスインストール

Servonaut をエージェント用ツールボックスとして使うのに、TUI は必要ありません。MCP サーバーは完全にヘッドレスで動作します。servonaut --mcp はターミナル UI を読み込みません（回帰テストで保証されています）。そのため、サーバーや CI 環境にインストールして、コーディングエージェント向けの 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: シークレット構文。詳しくは Configuration Guide をご覧ください）。Servonaut Cloud の機能（リレー、設定の同期、ホスト型 AI）を利用する場合、servonaut login を実行すると、デバイスフローによるサインインが完全にヘッドレスで行われます。任意のデバイスのブラウザーから承認できます。エージェントの操作はすべて同じガードレベルを経由し、~/.servonaut/mcp_audit.jsonl に記録されます。 Bitwarden の SSH 鍵（サーバー上に鍵を置かない）。 インスタンスに Bitwarden SSH ref が保存されている場合、SSH を使用するツール （run_command、get_logs、transfer_file、…）は、~/.ssh に鍵を置かなくても、 接続時にボールトから秘密鍵を取得します。そのため、新しいサーバーや CI サーバー上の エージェントは、ローカルに鍵がまったくなくても接続できます。ヘッドレスプロセスでは マスターパスワードを入力できないため、ボールトのロックを一度解除し、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_ban_* ツールは IP ブロック対象が 1 つ以上定義されている場合に限り表示されます。また、*_server_memory* ツールは メモリサブシステムが有効な場合に限り表示されます。CloudWatch／CloudTrail とコアの インスタンスツールは常に利用可能です（AWS が基本プロバイダーです）。

• cloudwatch_top_ips は WAF／ALB の構造化ログを解析し、許可／ブロックされた件数とともにクライアント IP を順位付けします。cloudtrail_lookup_events と組み合わせて照合し、その後 ip_ban_set で WAF、セキュリティグループ、または NACL を使ってブロックできます。
• whoami はセッションメタデータを返します。OAuth ベアラーが公開されることはありません。
• api_request を使うと、エージェントは servonaut.dev に対して、401 の自動更新と CLI 側のレート制限（30 回／分）を備えた認証済み REST 呼び出しを実行できます。ベアラーは CLI 上に保持されます。
• mcp_tool_call は、ホストされた mcp.servonaut.dev 上で JSON-RPC 2.0 の tools/call エンベロープを実行するラッパーです。プランに含まれるプレミアムツールに使用します。
• get_server_memory(id) はキャッシュされた事実のスナップショットを返します。エージェントは SSH で接続する前にこのツールを呼び出すことで、run_command を使わずに、OS／ランタイム／サービスに関する質問のほとんどに回答できます。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）を含みます）。危険なシェルコマンド（rm -rf、shutdown、reboot など）は、ガードレベルにかかわらず常にブロックされます。変更を伴うツールの説明には、「呼び出す前にユーザーに確認する」旨が明記されています。MCP のトップレベルの指示には、3 段階の手順（要約 → 引数を明示 → 肯定的な返答を待つ）が記載されています。すべての操作は ~/.servonaut/mcp_audit.jsonl に記録されます。

Servonaut Cloud アカウント

任意です。Servonaut は、お客様自身の AWS／OVH 認証情報を使って完全にオフラインで動作します。servonaut.dev にサインインすると、次の機能を利用できます。

• 設定の同期 — config.json の暗号化されたスナップショットをマシン間でプッシュ／プルできます。パスフレーズがクライアントの外に出ることはなく、サーバーに見えるのは暗号文のみです。サイドバーの 🔄 Sync Config を選ぶと、スナップショットマネージャー（Pull Latest／Push New／Restore／Rename／Delete）が直接開きます。
• MCP リレー — AI エージェントやチームメイトが、このマシンに MCP ツールの呼び出しを送信できる Mercure SSE チャネルです。リレーの接続中は、https://servonaut.dev/account に CLI がオンラインと表示され、ホストされたエージェントからアクセスできるようになります。
• メモリ同期（Solo+） — ドリフト検出機能を備えた、暗号化されたフリートメモリのバックアップです。サイドバーの ☁ Memory Sync を開き、Unlock Memory Sync をクリックしてパスフレーズを入力します。同じ画面で初回登録と再起動後のロック解除の両方を行えます。秘密鍵はパスフレーズでローカルにラップされるため、サーバーに渡ることはありません。ロック解除後、Sync now をクリックすると、キャッシュされたすべてのサーバーのメモリモジュールが暗号化されたエンベロープとしてプッシュされます。または、auto-sync をオンにして、バックグラウンドでキューを処理することで、サーバー側のコピー（および週次ダイジェスト）を最新の状態に保てます。ロック解除状態は再起動後も維持されます。Remember on this device にチェックを入れると、次回起動時に OS のキーチェーンから自動的にロックが解除されます（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 を参照してください。

トークンはモード 0600 で ~/.servonaut/auth.json に保存され、tmp と os.replace() を使用してアトミックに書き込まれます。古いビルドによってファイルが他のユーザーから読み取り可能な状態で残されていた場合、次回実行時に自動で修正されます。

プロアクティブな監視 — 検出事項（Solo+）

サーバー側の検出器がフリートをスキャンして問題を見つけ、それぞれを トリアージ可能な検出カードとして投稿します。カードには重要度、説明、証拠、 対処方法が記載されます。検出は Servonaut のクラウドで実行されます。このクライアントは リレー接続経由で読み取り専用のプローブを実行し、結果を表示するだけです。 ローカルで分析や判断が行われることはありません。

• フリートの受信トレイ／インスタンス別 — フリート全体についてはサイドバーの 🛡 Findings、個々のインスタンスについては任意のサーバーで F を押します。
• 今すぐスキャン（s） — リレー経由で読み取り専用のプローブを実行します （servonaut connect または TUI の自動起動が実行中である必要があります）。適用できない 検出器は、黙って失敗するのではなく理由を報告します。
• トリアージ — 確認（a）、解決（r）、または抑制（x）します。ステータスは サーバー側と同期されます。
• 承認制のワンクリック対処 — 自動化可能な修正は、サーバー署名付きプレビューから 明示的にクリックした場合にのみ実行され、動詞の許可リストを適用した実行ツールを 通じて行われます（状態変更時は入力による確認が必要で、最初にドライランを実行し、 すべて監査されます）。現在対応している修正：送信元 IP のブロック（AWS WAF／ セキュリティグループ／NACL、またはサーバー自体のファイアウォール — nftables／ufw／firewalld）と TLS 証明書の更新。

→ 詳細ガイド：docs/proactive-monitoring.md — 検出器、検出／プローブ／対処の仕組み、安全性と プライバシーに関する設計について説明します。Solo および Teams に含まれています （監視対象インスタンス数の上限あり）。Free ではアップグレードカードが表示されます。

シークレット管理（Solo+）

SSH キーやその他の名前付きシークレットを、プラグイン可能なプロバイダーバックエンドで 一元管理します。日常の利用時に意識する必要はありません。設定後は、接続のたびに SSH キーの解決でプロバイダーが自動的に確認されるため、TUI で SSH をクリックするだけで 使えます。以下のコマンドは初回設定時のみ実行します。MVP では 2 つのバックエンドに対応しています。

• 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 のインライン ドックストリングに記載されています。

データベース認証情報の保管庫

同じシークレットストアは、データベース認証情報の保管庫としても機能します。サーバーをスキャンし、 アプリがすでに使用している DB 認証情報を検出します — .env／DATABASE_URL（ DATABASE_URL_PROD／_STAGING 形式も含む）、wp-config.php、configuration.php、 Magento の env.php、および docker-compose の environment: ブロックを対象とします。 root 所有のファイルやコンテナ化されたスタックにも対応するため、読み取り専用の sudo -n フォールバックも使用します。パスワードをサイトごとのラベルで保存すると、 db_processlist／db_top_queries ツールが名前で認証情報を解決します — パスワードが 設定ファイルや AI エージェントのコンテキストに入ることはありません。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 に書き込まれます。詳細な stderr 出力には --debug を使用します。

SSH に失敗すると、エラーと終了コードが表示された状態でターミナルウィンドウが開いたままになります。

掲載先

公式のMCP Registryにも dev.servonaut/servonaut として公開されています。

ライセンス

このプロジェクトはMITライセンスのもとでライセンスされています。詳細はLICENSEファイルをご覧ください。