porterminal v1.0.6

Entregue um computador a um agente, com controle total, e observe-o.
Um comando, uma URL. (Também um terminal elegante para o seu próprio celular.)

1. uvx ptn
2. Entregue a URL a um agente de IA, ou escaneie o QR você mesmo
3. Observe-o trabalhar em qualquer navegador, e assuma o controle a qualquer momento

[!WARNING] Essa URL completa é acesso total a este computador. Ela contém um código de acesso aleatório por execução, e qualquer pessoa (ou qualquer agente de IA) a quem você entregá-la obtém um shell real na sua máquina. Trate a URL e o código QR como um segredo, compartilhe-os apenas com pessoas e agentes em quem você confia, e leia Segurança antes de apontar o Porterminal para qualquer coisa importante.

Por quê

Eu preciso de algo perigosamente fácil para acessar um computador remotamente.

ngrok exige registro e o plano gratuito é ruim. Cloudflare Tunnel é uma excelente infraestrutura, mas por si só fornece apenas um túnel, não um terminal amigável para celular. Tailscale é ótimo quando você possui ambas as pontas, mas ainda significa conectar dispositivos a uma rede privada. Termius exige configuração complicada: encaminhamento de portas, regras de firewall, gerenciamento de chaves...

Então eu construí algo mais simples: execute um comando, escaneie um QR, comece a digitar.

Então percebi: o mesmo truque (um comando, uma URL) é a maneira mais fácil de dar a um agente de IA um terminal real em qualquer computador. Sem servidor MCP para escrever, sem chaves SSH, sem Docker, sem configuração. Execute uvx ptn, entregue a URL, e o agente executa comandos, lê a tela e responde a prompts naquela máquina. E como é um terminal web, você pode abrir a mesma sessão em qualquer navegador para observá-lo trabalhar ao vivo, ou pegar o teclado e assumir o controle.

Recursos

• Entregue um computador a um agente, com controle total, e observe-o - Dê a URL a um agente de IA e ele obtém um terminal real na máquina via MCP ou REST simples. Abra a mesma sessão em qualquer navegador para observá-lo trabalhar ao vivo, e pegue o teclado quando quiser. Sem chaves, sem Docker. O agente aprende como fazer em <url>/llms.txt e <url>/.well-known/mcp.json. Veja Acesso do agente.
• Um comando, acesso instantâneo - uvx ptn e você (ou um agente) obtém um terminal real nesta máquina. Sem SSH, sem encaminhamento de portas, sem arquivos de configuração. Túnel Cloudflare + código QR.
• Realmente utilizável no celular - Otimizado para toque com rolagem com inércia, zoom por pinça, gestos de deslizar e teclas modificadoras (Ctrl, Alt).
• Aplicativos de terminal completos - vim, htop, less, tmux funcionam corretamente com tratamento adequado do buffer de tela alternativa.
• Sessões persistentes com múltiplas abas - As sessões sobrevivem a desconexões. Feche o navegador, troque de rede, reconecte de outro dispositivo, e seu shell e processos em execução ainda estarão lá. Você e um agente podem compartilhar uma sessão: observe-o trabalhar, ou assuma o controle.
• Multiplataforma - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell, e qualquer shell via $SHELL). Detecta seus shells automaticamente.
• Difícil de adivinhar por padrão - Cada execução adiciona um caminho de acesso aleatório independente de 128 bits. O hostname puro do túnel e qualquer caminho errado retornam 404. A URL fica oculta na tela, mas o QR contém a credencial completa, então mantenha ambos privados. Pressione c para copiar as instruções do agente e a URL, ou u para copiar apenas a URL.

Instalação

Método	Instalar	Atualizar
uvx (sem instalação)	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

Instalação em uma linha (uv + ptn):

SO	Comando
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

Requer Python 3.12+ e cloudflared (instalado automaticamente se ausente).

Uso

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

Flag	Descrição
-n, --no-tunnel	Apenas rede local (sem túnel Cloudflare)
--mcp-only	Controle de shell MCP sem código QR, terminal no navegador ou API REST
-p, --password	Solicitar senha para proteger esta sessão
-sp, --save-password	Salvar ou limpar senha na configuração
-tp, --toggle-password	Definir exigência de senha (on/off/toggle)
-v, --verbose	Mostrar logs detalhados de inicialização
-i, --init	Criar .ptn/ptn.yaml com scripts de projeto descobertos automaticamente como botões
-if, --init-from URL/PATH	Criar .ptn/ptn.yaml a partir de uma URL ou arquivo local
-c, --compose	Ativar modo de composição por padrão
-k, --keep-qr	Manter o código QR visível após a primeira conexão
-u, --check-update	Verificar se uma versão mais recente está disponível
-V, --version	Mostrar versão

Durante a execução: com um túnel ativo, a URL de conexão fica oculta na tela por privacidade. Pressione c para copiar as instruções do agente e a URL, incluindo /mcp, /api/agent/run e /llms.txt; pressione u para copiar apenas a URL; ou escaneie o QR para conectar. Ctrl+C para o servidor.

Acesso do agente (MCP + REST)

Para controle de shell inteiramente nos bastidores, execute ptn --mcp-only. A interface do terminal local permanece aberta: pressione c para copiar o prompt do agente e o endereço MCP, ou u para copiar apenas o endereço MCP. Essas teclas também funcionam com --no-tunnel. Conecte seu cliente MCP ao endpoint gerado <url>/mcp. Este modo não mostra código QR e desativa o terminal web, WebSockets do navegador e API REST, então os comandos não podem ser observados ou inseridos pelo navegador. A descoberta MCP e /llms.txt permanecem disponíveis. A URL MCP completa ainda concede controle de shell do computador.