porterminal v1.2.0

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

1. uvx ptn
2. URLをAIエージェントに渡すか、自分でQRコードをスキャンする
3. 任意のブラウザで作業の様子を見守り、いつでも引き継ぐ

[!WARNING] その完全な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がすべて、適切なオルトスクリーンバッファ処理で正しく動作します。
• 永続的なマルチタブセッション - セッションは切断後も存続します。ブラウザを閉じ、ネットワークを切り替え、別のデバイスから再接続しても、シェルと実行中のプロセスはそのままです。あなたとエージェントが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 を押すとエージェント向けの指示とURL(/mcp、/api/agent/run、/llms.txt を含む)をコピーし、u を押すとURLのみをコピーします。またはQRをスキャンして接続します。Ctrl+C でサーバーを停止します。

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

完全にバックグラウンドでシェルを制御するには、ptn --mcp-only を実行します。 ローカルターミナルUIは開いたままです。c を押すとエージェントプロンプトとMCP アドレスをコピーし、u を押すとMCPアドレスのみをコピーします。これらのキーは --no-tunnel でも機能します。 MCPクライアントを生成された <url>/mcp エンドポイントに接続します。このモードではQRコードが表示されず、Webターミナル、 ブラウザWebSocket、REST APIが無効になるため、コマンドをブラウザ経由で 見たり入力したりすることはできません。MCPディスカバリと /llms.txt は引き続き利用可能です。 完全なMCP URLは依然としてコンピュータのシェル制御を許可します。

同じ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で読み取り可能な Terminal screen ミラーと、明確にラベル付けされた Terminal input です。

セキュリティ: <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。

セキュリティ

起動ごとに、次のような新しい128ビットのランダムパスが作成されます: https://<tunnel>.trycloudflare.com/<access-code>/。すべてのブラウザ、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