Conning

Conning

人間とエージェントのための、軽量なローカル SSH コントローラーです。 Conning は、お使いのマシン上で動作する小さな CLI と MCP サーバーです。標準の OpenSSH を使って、テストマシンでコマンドを実行し、長時間のジョブやファイルのコピーを行います。ターミナルから操作でき、エージェント（Claude Code、Codex、Cursor など）は同じ 4 つのコマンドを MCP ツールとして利用でき、出力も同一です。Conning が鍵を保持するため、エージェントにパスワードが見えることはなく、リスクのある操作はユーザーが承認します。

conn targets add lab --host 10.0.0.5 --user tester   # asks for the rest, pins the host key
conn run lab uname -a                                 # exit code first, then the output
conn run -t lab apt upgrade                           # you, at a terminal: live, like ssh -t
conn ssh lab                                          # you: a shell there, same login and jump hosts
conn targets mode lab auto                            # optional: let the agent run anything there

ステータス：初期段階（0.6）です。 Linux、macOS、Windows のターゲットに対応しており、長時間のジョブ、転送、ジャンプホスト、承認機能を利用できます。これまでのすべての決定事項については、docs/design.md をご覧ください。

概要

• 軽量です。 Python パッケージ 1 つで動作し、デーモンは不要です。エージェントの起動時に、MCP サーバーが stdio で実行されます。4 つのツールの消費量は 1 ターンあたり約 1k トークンです。結果には終了コードが先頭に表示され、デフォルトでは 8 KB に制限されます。残りをページ単位で取得するためのハンドルも用意されており、複数のターゲットへのファンアウトでは同一の結果がまとめられます。
• ローカルで動作します。 ユーザーとエージェントのそばで実行されます。ターゲット側に必要なのは受信 SSH 接続だけで、何もインストールされません。シークレットは元の場所（OS キーチェーン、op://、ssh-agent）にとどまります。ターゲットファイルには参照情報だけが保存され、ツールがシークレットを返すことはありません。
• SSH を使用します。 内部では標準の OpenSSH を使いますが、~/.ssh/config は使用しません。ターゲットごとに設定を生成し、ホスト鍵を固定して、フォワーディングを無効にし、ジャンプホストに対応します。Windows ターゲットには OpenSSH と PowerShell 7 が必要です。
• 人間とエージェントの両方に対応します。 各ターゲットには ask または auto のモードがあります。ask では読み取り専用コマンドと許可ルールが実行され、それ以外はユーザーの承認を待ちます。「常に許可」では 2 つの単語を記憶するため、systemctl status を許可しても systemctl stop が通ることはありません。信頼を付与できるのはユーザーだけです。エージェントクライアントのプロンプト、conn watch、またはターミナルから許可できます。

インストール

uv tool install conning        # or: pipx install conning
conn mcp install claude        # or codex, cursor, opencode, pi: adds the server, its skill, and denies raw ssh/scp

ターゲット（そのファイル、コマンド、シェル履歴）を読み取るタブ補完を使うには、conn completion install を一度実行してください。bash、zsh、または fish の rc ファイルに 1 行が追加されます。設定がない場合は conn doctor が通知します。シェル履歴を含めないようにするには、ターゲットで history = false を設定してください（D53）。

MCP サーバーはインストール不要で、そのまま利用できます。

claude mcp add conning -- uvx conning mcp

または Docker でサーバーを実行する

docker run -i --rm --network host \
  -v ~/.config/conning:/conning \
  -v "$SSH_AUTH_SOCK":/ssh-agent -e SSH_AUTH_SOCK=/ssh-agent \
  ghcr.io/eranyonai/conning:latest

イメージには Python、OpenSSH クライアント、Conning のみが含まれます。ターゲット、固定されたホスト鍵、ジョブの出力は /conning ボリュームに保存され、conn はそのフォルダーの所有者として実行されるため、そこに書き込まれるファイルはホスト上でもユーザーの所有物になります。Mac の Docker Desktop では、代わりに -v /run/host-services/ssh-auth.sock:/ssh-agent を使ってエージェントをフォワードしてください。2 つの機能はお使いのマシン上で引き続き実行する必要があります（D46）。

• 承認。 conn targets add、conn approve、conn allow、auto への切り替えには、ユーザーのターミナルが必要です。ホストに CLI をインストールし、同じフォルダーを指定してください：CONNING_HOME=~/.config/conning conn approve a:1。エージェントクライアントからの承認は、通常どおりコンテナ内で行えます。
• シークレット。 コンテナから OS キーチェーンにはアクセスできないため、env: または op:// の参照を使うか、上記のように ssh-agent をフォワードして鍵を使用してください。docker run --rm ... conning doctor でその他の項目を確認できます。

ラボ LAN または VPN 上のターゲットを使用するには、--network host（Linux）を指定するか、コンテナから利用できるルートを設定してください。

エージェントの4つのツール

ツール	機能
targets(filter?, check?)	ターゲットごとに1行で、名前、OS、シェル、ホスト、ユーザー、タグ、モードを表示します。秘密情報は含まれません。
run(target, cmd | argv, wait=30, max_bytes=8192, ...)	1つのターゲット、ターゲットのリスト、または tag:<tag> で指定したターゲット上で実行します。最初に終了コードを返します。wait 秒後も実行中の場合はジョブ ID を返します（wait=0 は非同期です）。
read(id, wait?, range?, grep?, signal?)	新しい行が届くまでジョブをロングポーリングするか、保存された出力をページ単位で取得するか、リモートファイルを読み取ります。
transfer(source, dest)	sha256 で確認しながら、local:<path> と <target>:<path> の間でファイルをコピーします。

MCP を使わないエージェントも、conn CLI から同じコマンドを使用できます。出力は同一です。

エージェント向け：CLI リファレンス

このブロックは conn help --markdown によって生成されるため、--help を呼び出す必要はありません。テストによって、コードとの同期が保たれます。

# Agent commands (same output as the MCP tools)

conn targets [--check] [filter]
    List targets: name, OS, shell, host, user, tags, mode. Never secrets.

conn run [--wait WAIT] [--timeout TIMEOUT] [--cwd CWD] [--shell] [-t]
                [--max-bytes MAX_BYTES] [--grep GREP]
                target [argv ...]
    Run a command on one target, a list, or tag:<tag>. Exit code first.

conn read [--wait WAIT] [--range RANGE] [--grep GREP] [--signal {INT,TERM,KILL}]
                 [--max-bytes MAX_BYTES]
                 id
    Page a job (new lines only), a saved output, an approval, or a remote file.

conn transfer source dest
    Copy files: local:<path> to <target>:<path>, or back. sha256 checked.

# At a terminal

conn ssh target
    Human only: an interactive shell on a target, with its login, key, port and jump hosts.

# Targets (conn targets <verb>)

conn targets add [--host HOST] [--user USER] [--like TARGET] [--port PORT]
                        [--jump TARGET] [--auth {ssh-agent,key,password}] [--secret SECRET]
                        [--key KEY] [--os {linux,windows,darwin}] [--mode {ask,auto}] [--tag TAG]
                        name
    Add a target. Without a terminal it is saved as pending until a human approves it.

conn targets import [--match MATCH]
    Import hosts from ~/.ssh/config as pending targets (unsafe options dropped).

conn targets test name
    Probe a target: reachability, OS, shell, pinned host key.

conn targets mode target [{ask,auto}]
    Show or set ask or auto; auto runs anything without asking and needs a human.

conn targets rename old new
    Human only: rename a target; its host keys, password and pending work follow.

conn targets rm name
    Remove a target and its pinned host key.

# Trust

conn approve [--always] what
    Human only: make a target live, or allow a pending command a:<id>.

conn allow target [words ...]
    Human only: let a command run without asking (no words: list the rules).

conn deny target words [words ...]
    Remove an allow rule, so the command asks again (no terminal needed).

# This machine

conn watch [--history HISTORY] [--no-prompt]
    Live control room: every command on every target, job output, approval prompts.

conn doctor
    Check this machine's setup: config and state dirs, ssh, keychain, targets.

conn mcp [--approve-in-client | --no-approve-in-client] <serve|install> ...
    Run the MCP server on stdio, or install it into an agent client.

conn completion {bash,zsh,fish,install}
    Tab completion that reads the target; conn completion install turns it on in your shell.

conn help [--markdown]
    Show this help; --markdown prints the block cached in README.md.

ターゲットは、1台のマシンに対する1つのログイン情報です。同じマシンを別のユーザーとして使うには、そのユーザー用のターゲットを追加します。 conn targets add lab-tester --like lab --user tester はホスト、ポート、OS、タグをコピーし、新しいユーザーのパスワードを求めます。conn targets には、各ターゲットがどのユーザーを使うかが表示されます。

踏み台の背後にあるターゲットでは、その踏み台をジャンプホストとして指定します。まず踏み台をターゲットとして追加し、その後 conn targets add lab --host 10.0.0.5 --user tester --jump gw を実行します。各ホップにはそれぞれのログイン情報と固定されたホストキーが設定されます。また、conn targets import はインポートした別のホストへの ProxyJump 設定を保持します。踏み台もエージェントから見えるターゲットです。ask モードでは、ユーザーの承認なしにそこで実行できるのは読み取り専用コマンドのみです。

エージェントセッションから conn targets add で追加したターゲットは、保留中として保存されます。人間が conn approve <name> を実行するまで何も行われません。このコマンドでは、ホスト、固定されたホストキーのフィンガープリント、秘密情報の取得元が表示されます。

ターゲットの許可リストにないコマンドを実行すると、status=pending_approval id=a:<id> が返され、デスクトップ通知で人間に知らせます。人間は次の3か所のいずれかで応答します（一度だけ許可する、最初の2語が同じコマンドを常に許可する、または拒否する）。エージェントは read a:<id> で結果を取得します。

• エージェントクライアント内：ユーザー入力の要求に対応するMCPクライアントでは、コマンドがキューに追加される前に質問が表示され、承認されたコマンドは同じ呼び出し内で実行されます。対応していないクライアントでは、以下の2つの方法を使用できます。クライアントが質問をユーザーに尋ねず自動で回答してしまう場合は、サーバーを conn mcp --no-approve-in-client として実行してください。
• conn watch 内：コマンドとその出力が、実行されるたびに表示されます。
• 任意のターミナルで conn approve a:<id> を実行：ターミナルで自分で conn run を実行した場合は、その場で確認を求められ、結果が表示されます。

uname、hostname、df、ps、ls、ip addr、systemctl status、journalctl などの読み取り専用コマンドは、どのターゲットでも毎回の確認なしで実行できます。変更を伴う形式（hostname x、ip addr add など）は引き続き確認を求めるよう、各コマンドが検証されます。ターゲットの設定で safe = false にすると、このリストは無効になります。 conn allow <target> make test を実行すると、以後、別のコマンドを確認なしで実行できるようになります。conn deny で許可を取り消せます。すべてのコマンド、応答、ルールの変更はハッシュチェーン監査ログに記録されます。何かがうまく動作しない場合は、conn doctor で設定を確認できます。

安全モデル

モード	エージェントが実行できること	デフォルトの対象
ask	組み込みの読み取り専用リストにあるコマンドと、許可リストに登録されたコマンドは実行されます。それ以外はすべて、承認を待ちます。	新しいすべてのターゲット
auto	モードを ask に戻すまで、確認なしですべてのコマンドが実行されます。conn doctor はこの設定について警告します。	デフォルトでは使用しません

• ツールがシークレットを返したり、稼働中のターゲットを追加したり、ポリシーを変更したりすることはありません。
• シークレットは stdin または SSH チャネルの env を通じて送信され、argv を通じて送信されることはありません。出力は保存前にマスキングされます。
• リモート出力は信頼できないものとしてマークされます。シェルラッパー（sh -c、python -c、sudo...）やシェル構文 （;、|、$(...)）は、必ず確認を求めます。
• conn mcp install は、エージェントに生の ssh／scp と conn ssh を実行させないため、それらも拒否します。Conning を回避できないようにするためです（pi には権限ルールがないため、サーバーを追加するだけです）。
• 監査ログはハッシュチェーンで保護されています。ユーザー権限で実行されるため、改ざんを検知できますが、改ざんを防止するものではありません。

開発

uv sync
uv run pytest --cov=conning      # CI requires 95% coverage on Linux
uv run ruff check && uv run ruff format --check

エンドツーエンドテストでは、使い捨てのローカル sshd に対して、実際の conn と MCP サーバーを実行します（Linux が必要です。起動には root 権限が必要です。CI の e2e ジョブでは、プッシュのたびに実行されます）。

eval "$(sudo sh tests/e2e/start-sshd.sh /tmp/conning-sshd | sed 's/^/export /')"
uv run --with keyrings.alt pytest -m e2e   # keyrings.alt: a file keychain for typed passwords

CLI を変更した後は、uv run conn help --markdown を使って README の該当ブロックを更新してください。

ドキュメント

• docs/design.md：設計と、ステータスを含むすべての決定事項。
• docs/blog.html：最初のアイデアから現在までの開発ブログ。
• docs/manual-test.md：使い捨てのターゲットを使って、すべての機能を10分で確認する手順。
• docs/field-test.md：実際の作業での使い方と、支障となる点の報告方法。

なぜ Python なのか

Python は開発者のマシンに最も簡単にインストールできる言語であり、その周辺の AI ツールの多くも Python で書かれています。uvx conning mcp を使えば事前のインストールなしで実行でき、pip／pipx／uv もすでに利用できます。また、MCP SDK、キーチェーンバインディング、エージェントクライアントはすべて同じエコシステムにあります。Go や Rust なら単一のバイナリを提供できますが、Conning は実際の OpenSSH バイナリを実行し、処理の大半はネットワーク待ちです。そのため、速度の利点はここではあまり役立ちません。

ライセンス

Apache-2.0