porterminal v1.2.0
スマホとPCのためのクイック＆ダーティなWeb/MCPターミナルトンネリング
エージェントにコンピュータを渡し、完全な制御権を与えて、その様子を見守る。
コマンド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が、適切なオルトスクリーンバッファ処理で正しく動作する。
- 永続的なマルチタブセッション - セッションは切断後も生き残る。ブラウザを閉じ、ネットワークを切り替え、別のデバイスから再接続しても、シェルと実行中のプロセスはそのまま残っている。あなたとエージェントが1つのセッションを共有できる。作業を眺めたり、引き継いだり。
- クロスプラットフォーム - Windows(PowerShell、CMD、WSL)、Linux/macOS(Bash、Zsh、Fish、Nushell、および
$SHELL経由の任意のシェル)。シェルを自動検出する。 - デフォルトで推測が困難 - 起動ごとに独立した128ビットのランダムアクセスパスが追加される。素のトンネルホスト名とすべての誤ったパスは404を返す。URLは画面上では隠されるが、QRには完全な認証情報が含まれるので、両方とも秘密にしておくこと。
cを押すとエージェント向けの指示とURLをコピー、uでURLのみをコピー、sでエージェントプロンプトを画面に表示(qで閉じる)。
インストール
| 方法 | インストール | 更新 |
|---|---|---|
| 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のみをコピー、s で完全なエージェントプロンプトを選択可能なテキストとして表示(q で閉じる)、またはQRをスキャンして接続する。Ctrl+C でサーバーを停止。
エージェントアクセス (MCP + REST)
完全に舞台裏でシェルを制御するには、ptn --mcp-only を実行する。
ローカルターミナルUIは開いたままになる。c を押すとエージェントプロンプトとMCP
アドレスをコピー、u でMCPアドレスのみをコピー、s でプロンプトを画面に表示
(q で閉じる)。これらのキーは --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: []