porterminal v1.0.5

コンピュータをエージェントに渡し、完全なコントロールを与えて、その動きを見守る。
コマンド1つ、URL1つ。(自分のスマホ用の洗練されたターミナルにもなる。)

1. uvx ptn
2. URLをAIエージェントに渡すか、自分でQRコードをスキャンする
3. あらゆるブラウザで動作を確認し、いつでも操作を引き継ぐ

[!WARNING] その完全なURLは、このコンピュータへの完全なアクセス権です。 起動のたびに生成されるランダムなアクセスコードが含まれており、URLを渡した人(またはAIエージェント)は誰でも、あなたのマシンで本物のシェルを取得できます。URLとQRコードは秘密情報として扱い、信頼できる人とエージェントにのみ共有してください。Porterminalを重要なものに使用する前に、セキュリティ をお読みください。

なぜ

コンピュータにリモートアクセスするための、とてつもなく簡単な方法が必要だった。

ngrok は登録が必要で、無料枠は使い物にならない。Cloudflare Tunnel は優れた基盤だが、単体ではトンネルを提供するだけで、スマホに最適化されたターミナルにはならない。Tailscale は両端を自分で管理するなら素晴らしいが、それでもデバイスをプライベートネットワークに参加させる必要がある。Termius はポートフォワーディング、ファイアウォール設定、キー管理など、複雑なセットアップが必要だ……

そこで、もっとシンプルなものを作った:コマンドを実行して、QRをスキャンして、入力するだけ。

そして気づいた:同じやり方(コマンド1つ、URL1つ)が、あらゆるコンピュータでAIエージェントに本物のターミナルを与える最も簡単な方法だと。MCPサーバーの作成も、SSHキーも、Dockerも、設定も不要。uvx ptn を実行してURLを渡すだけで、エージェントはそのマシン上でコマンドを実行し、画面を読み取り、プロンプトに応答する。しかもWebターミナルなので、同じセッションをどのブラウザでも開いてライブで動作を確認したり、キーボードを掴んで操作を引き継いだりできる。

特徴

• コンピュータをエージェントに渡し、完全なコントロールを与えて、見守る - AIエージェントにURLを渡すと、MCPまたは素のREST経由でマシン上の本物のターミナルを取得できます。同じセッションをどのブラウザでも開いてライブで動作を確認でき、いつでもキーボードを掴んで操作を引き継げます。キーもDockerも不要。エージェントは <url>/llms.txt と <url>/.well-known/mcp.json から使い方を学びます。エージェントアクセス を参照。
• コマンド1つ、即時アクセス - uvx ptn を実行するだけで、あなた(またはエージェント)はこのマシン上の本物のターミナルを取得できます。SSHも、ポートフォワーディングも、設定ファイルも不要。Cloudflareトンネル + QRコード。
• モバイルで本当に使える - 慣性スクロール、ピンチズーム、スワイプジェスチャー、修飾キー(Ctrl、Alt)に対応したタッチ最適化。
• 本格的なターミナルアプリ - vim、htop、less、tmuxはすべて、alt-screenバッファを正しく処理して動作します。
• 永続的なマルチタブセッション - セッションは切断後も維持されます。ブラウザを閉じても、ネットワークを切り替えても、別のデバイスから再接続しても、シェルと実行中のプロセスはそのまま残っています。あなたとエージェントで1つのセッションを共有し、動作を見守ることも、操作を引き継ぐこともできます。
• クロスプラットフォーム - Windows (PowerShell、CMD、WSL)、Linux/macOS (Bash、Zsh、Fish、Nushell、および $SHELL 経由の任意のシェル)。シェルを自動検出します。
• デフォルトで推測困難 - 起動のたびに独立した128ビットのランダムなアクセスパスが追加されます。素のトンネルホスト名や誤ったパスはすべて404を返します。画面上ではURLが隠されますが、QRコードには完全な資格情報が含まれているため、両方とも秘密にしてください。c を押すとエージェントの説明とURLをコピーでき、u を押すとURLのみをコピーできます。

インストール

ワンラインインストール (uv + ptn):

Python 3.12+ と cloudflared が必要です(ない場合は自動インストールされます)。

使い方

ptn                    # Start in current directory
ptn ~/projects/myapp   # Start in specific folder

実行中: トンネルがアクティブな場合、プライバシー保護のため接続URLは画面上では隠されます。c を押すと /mcp、/api/agent/run、/llms.txt を含むエージェントの説明とURLをコピーできます。u を押すとURLのみをコピーでき、QRコードをスキャンして接続することもできます。Ctrl+C でサーバーを停止します。

エージェントアクセス (MCP + REST)

同じURLはAIエージェントでも利用できます。MCP対応クライアントは <url>/mcp (Streamable HTTP) をネイティブな型付きツールとして使用できます。MCPサーバーを登録できないエージェントは、<url>/api/agent/run のRESTフォールバックを通常のHTTPリクエストで使用できます。どちらの経路でも永続的なエージェントシェルが作成され、スマホから監視・操作引き継ぎができる🤖タブとして表示されます。

エージェントには、アクセスコードを含む生成された完全なURLを渡してください。MCPクライアントは <url>/.well-known/mcp.json (MCPの server.json ディスクリプタ) からサーバーを自動検出でき、使用方法を示す人間/エージェントが読める <url>/llms.txt もあります。ベースページにはブラウザ操作エージェント向けのアクセシビリティ可視のヒントも含まれていますが、人間向けUIはコンパクトなままです。クライアント設定の例:

{
  "mcpServers": {
    "porterminal": { "url": "https://<your-tunnel>.trycloudflare.com/<access-code>/mcp" }
  }
}

MCPツール: run_command (クリーンな出力 + 終了コード)、read_screen、send_keys、send_signal (Ctrl-C / EOF)。

RESTフォールバック:

curl -s -X POST https://<your-tunnel>.trycloudflare.com/<access-code>/api/agent/run \
  -H "content-type: application/json" \
  -d '{"command":"echo hello","timeout":30}'

レスポンスには session_id が含まれます。これを <url>/api/agent/screen、<url>/api/agent/keys、<url>/api/agent/signal、DELETE <url>/api/agent/session で再利用します。

スマホでPorterminalを開くと、右上のコピーボタンで同じエージェント対応の共有テキストをコピーできます。ブラウザ限定のエージェント向けには、ベースページにもフォールバックがあります:DOMから読み取り可能な ターミナル画面 ミラーと、明確にラベル付けされた ターミナル入力 です。

セキュリティ: <url> は、ランダムなアクセスコードを含む生成された完全なURLを意味します。素のトンネルホスト名は何も公開しませんが、完全なURLを入手した人(またはエージェント)は、昇格されていない完全なシェルアクセスを取得できます。docs/agent-access.md を参照してください。

モバイルジェスチャー

修飾キー (Ctrl、Alt、Shift): 1回タップでスティッキー(1回のキー入力のみ)、ダブルタップでロック。

コンポーズモード (▤ ボタン): 入力または音声入力できるテキスト入力フィールドを切り替えます。モバイルのフル編集機能(自動修正、候補表示、カーソル位置操作)でテキストを編集してからターミナルに送信します。長いコマンドや音声入力に便利です。

設定

ptn --init を実行するとスターター設定が作成されます。package.json、pyproject.toml、Makefile からプロジェクトスクリプトを自動検出し、ボタンとして追加します:

ptn -i
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

または ptn.yaml を手動で作成:

# Terminal settings
terminal:
  default_shell: nu              # Default shell ID
  shells:                        # Custom shell definitions
    - id: nu
      name: Nushell
      command: nu
      args: []

# Custom buttons (appear in toolbar)
# row: 1 = default row, 2+ = additional rows
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # delay in ms
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # second button row

# Update checker settings
update:
  notify_on_startup: true   # Show update notification
  check_interval: 86400     # Seconds between checks (default: 24h)

# Security settings
security:
  require_password: true    # Always require password at startup
  password_hash: ""         # Saved password hash (use ptn -sp to set)
  max_auth_attempts: 5      # Max failed attempts before disconnect

設定は次の順序で検索されます: $PORTERMINAL_CONFIG_PATH、./ptn.yaml、./.ptn/ptn.yaml、~/.ptn/ptn.yaml。

セキュリティ

起動のたびに https://<tunnel>.trycloudflare.com/<access-code>/ のような新しい128ビットのランダムパスが作成されます。ブラウザ、WebSocket、MCP、REST、ヘルスチェック、静的ルートはすべて、その正確なプレフィックスを必要とします。素のホスト名や誤ったパスは404を返します。これにより、発見されたトンネルホスト名へのブルートフォース攻撃は非現実的になります。

生成された完全なURLは依然としてベアラ資格情報です:入手した人は誰でもシェルアクセスを取得できます。コードが漏洩した場合は、Porterminalを再起動してコードをローテーションしてください。オプションのパスワードはブラウザのWebSocketに認証を追加しますが、MCPとRESTは引き続き完全なURLを信頼するため、エージェントはワンリンクのワークフローを使用できます。

ブラウザは、成功したパスワードを、その完全な起動URLにスコープされた平文ストレージに記憶します。同じオリジンで新しい起動のパスワードを保存すると、古いPorterminalのパスワードエントリは無効になります。記憶されたパスワードをクリアまたは拒否すると、他のブラウザストレージには触れずにすべて削除されます。その結果、同じオリジンでの同時起動では再度パスワードを求められる場合がありますが、すでに認証済みの接続は維持されます。

UIから: 設定(歯車アイコン)を開き、セキュリティセクションでパスワードの設定/変更とパスワード要求の切り替えができます。変更にはサーバーの再起動が必要です。

CLIから:

# One-time password (prompt each session)
ptn -p

# Save password to config (no prompt needed)
ptn -sp
# Password: ****
# Confirm password: ****

# Clear saved password (enter empty password)
ptn -sp
# Password: [press Enter]

# Set or toggle password requirement
ptn -tp          # Toggle on/off

詳細は docs/security.md を参照してください。

トラブルシューティング

接続できない場合? アクセスコードを含む生成された完全なURLを使用してください。Cloudflareトンネルの問題は、サーバーを再起動(Ctrl+C の後に ptn)して新しいトンネルとアクセスパスを取得することで解決できることもあります。

uvx ptn がまだ古いバージョンを実行する場合? 既存の uv tool インストールが優先されることがあります。uv tool upgrade ptn を実行するか、uvx --isolated ptn@latest でインストール済みツールをバイパスしてください。

シェルが検出されない場合? $SHELL 環境変数を設定するか、ptn.yaml でシェルを設定してください。

貢献

このプロジェクトはセキュリティ上の理由から、外部からの貢献(プルリクエストやコード変更)を受け付けていません (CONTRIBUTING.md を参照)。フォークして AGPL-3.0 の下でご自身のコピーを実行することは歓迎します。

ソースから実行:

git clone https://github.com/lyehe/porterminal
cd porterminal
uv sync --frozen
uv run --frozen ptn

ライセンス

AGPL-3.0