porterminal v1.0.6
スマホとPCのためのクイック＆ダーティなWeb/MCPターミナルトンネリング
エージェントにコンピュータを渡し、完全な制御権を与えて、その様子を見守ろう。
コマンド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のみをコピーします。
インストール
| 方法 | インストール | 更新 |
|---|---|---|
| uvx (インストール不要) | uvx ptn | uvx ptn@latest |
| uv tool | uv tool install ptn | uv tool upgrade ptn |
| pipx | pipx install ptn | pipx upgrade ptn |
| pip | pip install ptn | pip install -U ptn |
ワンラインインストール (uv + ptn):
| OS | コマンド |
|---|---|
| Windows | powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/lyehe/porterminal/master/install.ps1 | iex" |
| macOS/Linux | curl -LsSf https://raw.githubusercontent.com/lyehe/porterminal/master/install.sh | sh |
Python 3.12+ と cloudflared が必要です(なければ自動インストールされます)。
使い方
ptn # Start in current directory
ptn ~/projects/myapp # Start in specific folder
| フラグ | 説明 |
|---|---|
-n, --no-tunnel | ローカルネットワークのみ(Cloudflareトンネルなし) |
--mcp-only | QRコード、ブラウザターミナル、REST APIなしでMCPシェル制御 |
-p, --password | このセッションを保護するパスワードを入力 |
-sp, --save-password | パスワードを設定に保存またはクリア |
-tp, --toggle-password | パスワード要件を設定(on/off/toggle) |
-v, --verbose | 詳細な起動ログを表示 |
-i, --init | 自動検出したプロジェクトスクリプトをボタンとして .ptn/ptn.yaml を作成 |
-if, --init-from URL/PATH | URLまたはローカルファイルから .ptn/ptn.yaml を作成 |
-c, --compose | デフォルトでコンポーズモードを有効化 |
-k, --keep-qr | 最初の接続後もQRコードを表示し続ける |
-u, --check-update | 新しいバージョンが利用可能か確認 |
-V, --version | バージョンを表示 |
実行中: トンネルが有効な場合、プライバシーのため接続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を参照してください。
モバイルジェスチャー
| ジェスチャー | アクション |
|---|---|
| タップ | ターミナルにフォーカス、選択をクリア |
| 長押し | テキスト選択を開始 |
| ダブルタップ | 単語を選択 |
| 左/右スワイプ | 矢印キー (← →) |
| スクロール | 物理演算による慣性スクロール |
| ピンチ | テキストをズーム (10-24px) |
修飾キー (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: []