porterminal v1.2.0

एक एजेंट को कंप्यूटर सौंपें, पूरा नियंत्रण दें, और उसे काम करते देखें।
एक कमांड, एक URL। (आपके अपने फ़ोन के लिए भी एक शानदार टर्मिनल।)

1. uvx ptn
2. URL को किसी AI एजेंट को सौंपें, या खुद QR स्कैन करें
3. किसी भी ब्राउज़र में इसे काम करते देखें, और कभी भी नियंत्रण ले लें

[!WARNING] वह पूरा URL इस कंप्यूटर तक पूरी पहुँच है। इसमें हर लॉन्च के लिए एक रैंडम एक्सेस कोड होता है, और जिसे भी (या किसी भी AI एजेंट को) आप इसे सौंपते हैं, उसे आपकी मशीन पर असली शेल मिल जाता है। URL और QR कोड को एक रहस्य की तरह मानें, इन्हें केवल उन लोगों और एजेंटों के साथ साझा करें जिन पर आप भरोसा करते हैं, और Porterminal को किसी महत्वपूर्ण चीज़ पर इस्तेमाल करने से पहले Security पढ़ें।

क्यों

मुझे किसी कंप्यूटर तक रिमोट एक्सेस के लिए कुछ खतरनाक रूप से आसान चाहिए।

ngrok के लिए रजिस्ट्रेशन चाहिए और फ्री टियर बेकार है। Cloudflare Tunnel बेहतरीन प्लंबिंग है, लेकिन अपने आप में यह केवल एक टनल देता है, फ़ोन-फ्रेंडली टर्मिनल नहीं। Tailscale तब शानदार है जब दोनों सिरे आपके पास हों, लेकिन फिर भी इसका मतलब है डिवाइसों को एक प्राइवेट नेटवर्क से जोड़ना। Termius के लिए जटिल सेटअप चाहिए: पोर्ट फ़ॉरवर्डिंग, फ़ायरवॉल नियम, की मैनेजमेंट...

तो मैंने कुछ आसान बनाया: एक कमांड चलाएँ, QR स्कैन करें, टाइप करना शुरू करें।

फिर समझ आया: वही तरकीब (एक कमांड, एक URL) किसी AI एजेंट को किसी भी कंप्यूटर पर असली टर्मिनल देने का सबसे आसान तरीका है। न कोई MCP सर्वर लिखना, न SSH कीज़, न Docker, न कॉन्फ़िग। uvx ptn चलाएँ, URL सौंपें, और एजेंट उस मशीन पर कमांड चलाता है, स्क्रीन पढ़ता है, और प्रॉम्प्ट का जवाब देता है। और चूँकि यह एक वेब टर्मिनल है, आप उसी सेशन को किसी भी ब्राउज़र में खोलकर इसे लाइव काम करते देख सकते हैं, या कीबोर्ड पकड़कर नियंत्रण ले सकते हैं।

विशेषताएँ

• एक एजेंट को कंप्यूटर सौंपें, पूरा नियंत्रण दें, और उसे काम करते देखें - किसी AI एजेंट को URL दें और उसे MCP या सादे REST के ज़रिए मशीन पर असली टर्मिनल मिल जाता है। उसी सेशन को किसी भी ब्राउज़र में खोलकर इसे लाइव काम करते देखें, और जब चाहें कीबोर्ड पकड़ लें। न कीज़, न Docker। एजेंट <url>/llms.txt और <url>/.well-known/mcp.json से सीखता है कि कैसे करना है। देखें Agent access।
• एक कमांड, तुरंत एक्सेस - uvx ptn और आपको (या किसी एजेंट को) इस मशीन पर असली टर्मिनल मिल जाता है। न SSH, न पोर्ट फ़ॉरवर्डिंग, न कॉन्फ़िग फ़ाइलें। Cloudflare टनल + QR कोड।
• मोबाइल पर वाकई उपयोगी - टच-ऑप्टिमाइज़्ड, मोमेंटम स्क्रॉलिंग, पिंच-टू-ज़ूम, स्वाइप जेस्चर, और मॉडिफ़ायर कीज़ (Ctrl, Alt) के साथ।
• पूर्ण टर्मिनल ऐप्स - vim, htop, less, tmux सब सही तरीके से काम करते हैं, उचित alt-screen बफ़र हैंडलिंग के साथ।
• पर्सिस्टेंट मल्टी-टैब सेशन - सेशन डिस्कनेक्ट के बाद भी बने रहते हैं। ब्राउज़र बंद करें, नेटवर्क बदलें, किसी दूसरे डिवाइस से दोबारा कनेक्ट करें, और आपका शेल और चल रही प्रोसेस अब भी वहीं हैं। आप और एक एजेंट एक सेशन साझा कर सकते हैं: इसे काम करते देखें, या नियंत्रण ले लें।
• क्रॉस-प्लेटफ़ॉर्म - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell, और $SHELL के ज़रिए कोई भी शेल)। आपके शेल्स को ऑटो-डिटेक्ट करता है।
• डिफ़ॉल्ट रूप से अनुमान लगाना मुश्किल - हर लॉन्च एक स्वतंत्र 128-बिट रैंडम एक्सेस पाथ जोड़ता है। सादा टनल होस्टनेम और हर गलत पाथ 404 लौटाते हैं। URL स्क्रीन पर छिपा रहता है, लेकिन QR में पूरा क्रेडेंशियल होता है, इसलिए दोनों को निजी रखें। एजेंट निर्देश और URL कॉपी करने के लिए c दबाएँ, या केवल URL कॉपी करने के लिए u दबाएँ।

इंस्टॉल

वन-लाइन इंस्टॉल (uv + ptn):

Python 3.12+ और cloudflared चाहिए (गायब होने पर ऑटो-इंस्टॉल हो जाता है)।

उपयोग

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

चलते समय: टनल सक्रिय होने पर, गोपनीयता के लिए कनेक्शन URL स्क्रीन पर छिपा रहता है। एजेंट निर्देश और URL कॉपी करने के लिए c दबाएँ, जिसमें /mcp, /api/agent/run, और /llms.txt शामिल हैं; केवल URL कॉपी करने के लिए u दबाएँ; या कनेक्ट करने के लिए QR स्कैन करें। Ctrl+C सर्वर बंद कर देता है।

एजेंट एक्सेस (MCP + REST)

पूरी तरह पर्दे के पीछे शेल नियंत्रण के लिए, ptn --mcp-only चलाएँ। लोकल टर्मिनल UI खुला रहता है: एजेंट प्रॉम्प्ट और MCP पता कॉपी करने के लिए c दबाएँ, या केवल MCP पता कॉपी करने के लिए u दबाएँ। ये कीज़ --no-tunnel के साथ भी काम करती हैं। अपने MCP क्लाइंट को जनरेट किए गए <url>/mcp एंडपॉइंट से कनेक्ट करें। यह मोड कोई QR कोड नहीं दिखाता और वेब टर्मिनल, ब्राउज़र WebSockets, और REST API को अक्षम कर देता है, इसलिए कमांड ब्राउज़र के ज़रिए देखे या दर्ज नहीं किए जा सकते। MCP डिस्कवरी और /llms.txt उपलब्ध रहते हैं। पूरा MCP URL अब भी कंप्यूटर पर शेल नियंत्रण देता है।

वही URL AI एजेंटों के लिए भी काम करता है। MCP-सक्षम क्लाइंट नेटिव टाइप्ड टूल्स के लिए <url>/mcp (Streamable HTTP) इस्तेमाल कर सकते हैं। जो एजेंट MCP सर्वर रजिस्टर नहीं कर सकते, वे साधारण HTTP रिक्वेस्ट के साथ <url>/api/agent/run पर REST फ़ॉलबैक इस्तेमाल कर सकते हैं। दोनों में से कोई भी रास्ता एक पर्सिस्टेंट एजेंट शेल बनाता है, जो 🤖 टैब के रूप में दिखता है जिसे आप अपने फ़ोन से देख और नियंत्रित कर सकते हैं।

एजेंट को पूरा जनरेट किया गया 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): स्टिकी के लिए एक बार टैप करें (एक कीस्ट्रोक), लॉक के लिए डबल-टैप करें।

Compose मोड (▤ बटन): एक टेक्स्ट इनपुट फ़ील्ड टॉगल करें जहाँ आप टाइप या डिक्टेट कर सकते हैं, पूर्ण मोबाइल एडिटिंग सुविधाओं (ऑटोकरेक्ट, सुझाव, कर्सर पोज़िशनिंग) के साथ अपना टेक्स्ट संपादित करें, फिर टर्मिनल पर भेजें। लंबे कमांड या वॉइस इनपुट के लिए उपयोगी।

कॉन्फ़िगरेशन

स्टार्टर कॉन्फ़िग बनाने के लिए 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, health, और static रूट्स को वही सटीक प्रीफ़िक्स चाहिए; सादा होस्ट और गलत पाथ 404 लौटाते हैं। यह किसी खोजे गए टनल होस्टनेम को ब्रूट-फ़ोर्स करना अव्यावहारिक बनाता है।

पूरा जनरेट किया गया URL अब भी एक बियरर क्रेडेंशियल है: जिसे भी यह मिलता है उसे शेल एक्सेस मिल जाता है। अगर यह लीक हो जाए तो कोड बदलने के लिए Porterminal रीस्टार्ट करें। वैकल्पिक पासवर्ड ब्राउज़र WebSockets में ऑथेंटिकेशन जोड़ता है, लेकिन MCP और REST पूरे URL पर भरोसा करना जारी रखते हैं ताकि एजेंट वन-लिंक वर्कफ़्लो इस्तेमाल कर सकें।

एक ब्राउज़र सफल पासवर्ड को उस पूरे लॉन्च URL तक सीमित प्लेनटेक्स्ट स्टोरेज में याद रखता है। उसी ओरिजिन पर नए लॉन्च के लिए पासवर्ड सहेजने पर पुरानी Porterminal पासवर्ड एंट्रीज़ हट जाती हैं; याद रखे गए पासवर्ड को साफ़ करने या अस्वीकार करने पर वे सब हट जाती हैं, बिना अन्य ब्राउज़र स्टोरेज को छुए। नतीजतन, उसी ओरिजिन पर समवर्ती लॉन्च फिर से प्रॉम्प्ट कर सकते हैं, जबकि पहले से ऑथेंटिकेटेड कनेक्शन जुड़ा रहता है।

UI से: Settings (गियर आइकन) खोलें और पासवर्ड सेट/बदलने तथा पासवर्ड आवश्यकता टॉगल करने के लिए Security सेक्शन इस्तेमाल करें। बदलावों के लिए सर्वर रीस्टार्ट चाहिए।

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