Code Remote

🚀 Code Remote

任意のMCP互換AIクライアントから、あなたのマシン上でコマンドを実行できます。

Code Remoteは、MCP（Model Context Protocol）とローカルマシンを橋渡しし、AIアシスタントがシェルコマンドの実行、ファイルの読み書き、ファイルシステムの探索を、携帯電話や任意のウェブブラウザから行えるようにします。

✨ 主な機能

• AIクライアントからローカルマシン上でコマンドを実行できる。
• ファイルの読み書きやファイルシステムの探索が可能。
• 複数のデプロイメント方法を提供。

📦 インストール

前提条件

• uv - 高速なPythonパッケージマネージャ（エージェントに必要）

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Python 3.10以上 - エージェントを実行するために必要
• Docker - セルフホスト型サーバーのデプロイに必要（オプションAとB）
• Fly.io CLI - マネージドデプロイに必要（オプションCのみ）

デプロイメント方法の選択

オプションA: ngrokを使ったローカルデプロイ（最も簡単）

ngrokを使ってHTTPSトンネリングを行い、すべてをローカルで実行します。クラウドデプロイは不要です。

# ターミナル1: サーバーを起動
export AUTH_TOKEN=$(openssl rand -hex 32)
echo "AUTH_TOKEN=$AUTH_TOKEN" > .env
docker-compose up -d

# ターミナル2: ngrokトンネルを起動
ngrok http 8080
# https://xxx.ngrok-free.appのURLをメモしておく

# ターミナル3: エージェントを起動（ローカルで接続）
cd agent
uv venv && uv pip install -r requirements.txt
source .venv/bin/activate
export AUTH_TOKEN=$(cat ../.env | cut -d= -f2)
export RELAY_URL=ws://localhost:8080/ws/agent
python agent.py

MCPクライアントに追加する:

• URL: https://xxx.ngrok-free.app/sse（あなたのngrok URL）

注意: 無料のngrokプランでは、再起動するとランダムなURLに変更されます。有料プランでは安定したサブドメインが提供されます。

オプションB: Docker + リバースプロキシ（セルフホスト）

適切なドメインを持つ独自のインフラストラクチャ上でサーバーを実行します。

# 1. 認証トークンを生成
export AUTH_TOKEN=$(openssl rand -hex 32)
echo "AUTH_TOKEN=$AUTH_TOKEN" > .env

# 2. サーバーを起動
docker-compose up -d

# 3. HTTPSを設定（下記のHTTPS設定セクションを参照）

オプションC: Fly.io（マネージド）

Fly.ioにデプロイして、自動的なHTTPSとグローバルな可用性を得ます。

cd server

# fly.tomlを編集してアプリ名を設定
# 変更前: app = "YOUR-APP-NAME"
# 変更後: app = "yourname-code-remote"

fly launch --name YOUR-APP-NAME --region dfw --no-deploy
fly volumes create code_remote_data --size 1 --region dfw
fly secrets set AUTH_TOKEN=$(openssl rand -hex 32)
fly deploy

あなたのURLは以下の通りになります:

• MCPエンドポイント: https://YOUR-APP-NAME.fly.dev/sse
• WebSocket: wss://YOUR-APP-NAME.fly.dev/ws/agent

エージェントのインストール（オプションBとC）

ネイティブエージェント（マシン上で直接実行）

cd agent
./setup.sh
# リレーURL（例: wss://your-server.example.com/ws/agent）を入力
# 認証トークンを入力
./run.sh

サンドボックス化されたエージェント（Dockerコンテナ内で実行）

# コンテナ化されたエージェントでフルスタックを実行
docker-compose --profile full up -d

サンドボックス化されたエージェントは、一般的な開発ツール（git、curl、vim、ripgrepなど）がインストールされた分離されたLinux環境で非ルートユーザーとして実行されます。ファイルはコンテナ内の/home/agent/workspaceに制限されます。

AIクライアントの接続

MCPクライアントの設定に以下を追加します:

• URL: https://your-server.example.com/sse

Claude.aiの場合: 設定 > コネクタ > MCP

💻 使用例

基本的な使用法

MCP互換のAIクライアントから、以下のようなコマンドを実行できます。

# シェルコマンドを実行
run_shell_command("ls -l")

# ファイルを読み取る
read_file("example.txt")

# ファイルに内容を書き込む
write_file("example.txt", "Hello, World!")

# ディレクトリの内容を一覧表示
list_directory("/path/to/directory")

# エージェントの接続状態を確認
check_agent_status()

📚 ドキュメント

• セットアップガイド - 完全なインストール手順
• デプロイメント - Fly.ioのデプロイと管理
• アーキテクチャ - システム設計とセキュリティ

🔧 技術詳細

アーキテクチャ

クラウド/セルフホスト設定

+----------------+          +-------------------+          +----------------+
|                |   SSE    |                   |    WS    |                |
|   AI Client    |<-------->|  Server (Cloud)   |<-------->|     Agent      |
|   (MCP)        |   MCP    |                   |  Relay   |   (Daemon)     |
+----------------+          +-------------------+          +----------------+

ngrokを使ったローカル設定（すべて1台のマシン上で）

+----------------+          +-------------------+          +---------------------------+
|                |  HTTPS   |                   |          |      Your Machine         |
|   AI Client    |--------->|   ngrok tunnel    |--------->| +-------+     +-------+   |
|   (MCP)        |          |                   |          | |Server |<--->| Agent |   |
+----------------+          +-------------------+          | +-------+     +-------+   |
                                                           +---------------------------+

データフロー

1. AIアシスタント（Claude.aiなど）とチャットする。
2. AIがMCPツール（run_shell_command、read_fileなど）を呼び出す。
3. サーバーがコマンドをキューに入れ、WebSocketを介して接続されたエージェントに送信する。
4. エージェントがマシン上でコマンドを実行し、結果を返す。
5. 結果がSSEを通じてAIに戻る。

HTTPS設定

MCPクライアントは通常、HTTPSを必要とします。Dockerでセルフホストする場合、リバースプロキシが必要です。以下はCaddyを使った簡単な例です。

# Caddyをインストール（https://caddyserver.com/docs/install）
# Caddyfileを作成:
cat > Caddyfile << 'EOF'
your-domain.com {
    reverse_proxy localhost:8080
}
EOF

# Caddyを実行（Let's Encryptを通じて自動的にTLSをプロビジョニング）
caddy run

他のオプション:

• nginx: Let's Encrypt証明書にcertbotを使用
• Traefik: 自動TLSのための組み込みACMEサポート
• Cloudflare Tunnel: TLSを自動的に処理する無料オプション

セキュリティ

• すべてのコンポーネント間でトークンベースの認証を行う。
• エージェントはファイルアクセスをホームディレクトリ、/tmp、/var/tmpに制限する。
• すべてのトラフィックはHTTPS/WSSを通じて暗号化される。
• コマンドはSQLiteにログ記録され、監査トレイルを残す。
• サンドボックスモード: エージェントをDockerコンテナ内で実行して完全な分離を実現する。
• Tailscale統合: エージェントの接続をあなたのプライベートTailscaleネットワークに制限する。

Tailscale設定（推奨）

追加のセキュリティのため、サーバーがTailscaleネットワークからのエージェント接続のみを受け付けるように設定できます。これにより、AUTH_TOKENが漏洩した場合でも、あなたのテイルネット上のデバイスのみがエージェントとして接続できます。

1. Tailscale認証キーを生成: 「https://login.tailscale.com/admin/settings/keys」にアクセスし、新しい認証キーを作成します。
   • 「Reusable」をチェック（サーバーが再起動後に再接続できるようにする）
   • 必要に応じて「Ephemeral」をチェック
   • 注意: キーは最大90日で期限切れになります
2. 認証キーをFly.ioのシークレットとして設定:

fly secrets set TAILSCALE_AUTHKEY=tskey-auth-xxxxx -a YOUR-APP-NAME

3. サーバーをデプロイ:

cd server
fly deploy

4. エージェントがTailscaleを介して接続するように設定: デプロイ後、Fly.ioのログからサーバーのTailscale IPを見つけます。

fly logs -a YOUR-APP-NAME | grep "peerapi: serving"
# 以下のような行を探す: peerapi: serving on http://100.x.x.x:xxxxx

エージェントの.envを更新します。

RELAY_URL=ws://100.x.x.x:8080/ws/agent

Tailscaleを使ったアーキテクチャ

+----------------+          +-------------------+          +----------------+
|                |   SSE    |                   |    WS    |                |
|   AI Client    |<-------->|  Server (Cloud)   |<-------->|     Agent      |
|   (MCP)        |  HTTPS   |  + Tailscale      | Tailscale|   (Daemon)     |
+----------------+          +-------------------+          +----------------+
                                    |
                            Only accepts agent
                            connections from
                            Tailscale IPs
                            (100.64.0.0/10)

注意: MCPエンドポイントは公開アクセス可能なままです（Claude.ai用）が、エージェントの接続はあなたのTailscaleネットワークに制限されます。

Tailscale要件の無効化

任意のIPからのエージェント接続を許可するには（セキュリティが低くなります）:

fly secrets set REQUIRE_PRIVATE_NETWORK=false -a YOUR-APP-NAME

📄 ライセンス

このプロジェクトはGNU Affero General Public License v3.0（AGPL - 3.0）の下でライセンスされています。詳細はLICENSEを参照してください。

作者

Drew Cain (@groksrc)