porterminal

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

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

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

क्यों

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

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 से यह सीखता है। एजेंट पहुँच देखें।
• एक कमांड, तुरंत पहुँच - uvx ptn और आपको (या एजेंट को) इस मशीन पर असली टर्मिनल मिल जाता है। न SSH, न पोर्ट फ़ॉरवर्डिंग, न कॉन्फ़िग फ़ाइलें। Cloudflare tunnel + 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 गोपनीयता के लिए स्क्रीन पर छिपा रहता है। /mcp, /api/agent/run, और /llms.txt सहित एजेंट निर्देश और URL कॉपी करने के लिए c दबाएँ; केवल URL कॉपी करने के लिए u दबाएँ; या कनेक्ट करने के लिए QR स्कैन करें। Ctrl+C सर्वर रोकता है।

एजेंट पहुँच (MCP + REST)

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

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

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

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

पूरा जनरेट किया गया URL अब भी एक bearer क्रेडेंशियल है: जिसे भी यह मिल जाए, उसे शेल पहुँच मिल जाती है। अगर यह लीक हो जाए, तो कोड बदलने के लिए Porterminal को पुनः आरंभ करें। वैकल्पिक पासवर्ड ब्राउज़र WebSockets में प्रमाणीकरण जोड़ता है, लेकिन MCP और REST पूर्ण URL पर भरोसा करते रहते हैं ताकि एजेंट एक-लिंक वर्कफ़्लो का उपयोग कर सकें।

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

UI से: Settings (गियर आइकन) खोलें और पासवर्ड सेट/बदलने और पासवर्ड आवश्यकता टॉगल करने के लिए सुरक्षा अनुभाग का उपयोग करें। बदलावों के लिए सर्वर पुनः आरंभ करना आवश्यक है।

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