porterminal v1.2.0

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

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

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

Uso

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

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.

A mesma URL também funciona para agentes de IA. Clientes compatíveis com MCP podem usar <url>/mcp (Streamable HTTP) para ferramentas tipadas nativas. Agentes que não podem registrar um servidor MCP podem usar o fallback REST em <url>/api/agent/run com requisições HTTP comuns. Qualquer um dos caminhos cria um shell de agente persistente, mostrado como uma aba 🤖 que você pode observar e assumir do seu celular.

Entregue ao agente a URL completa gerada, incluindo seu código de acesso. Clientes MCP podem descobrir o servidor automaticamente em <url>/.well-known/mcp.json (o descritor server.json do MCP), e há um <url>/llms.txt legível por humanos/agentes com instruções de uso. A página base também inclui dicas visíveis para acessibilidade para agentes que controlam navegadores, enquanto a interface humana permanece compacta. Exemplo de configuração de cliente:

{
  "mcpServers": {
    "porterminal": { "url": "https://<your-tunnel>.trycloudflare.com/<access-code>/mcp" }
  }
}

Ferramentas MCP: run_command (saída limpa + código de saída), read_screen, send_keys, send_signal (Ctrl-C / EOF).

Fallback 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}'

A resposta inclui um session_id; reutilize-o com <url>/api/agent/screen, <url>/api/agent/keys, <url>/api/agent/signal, e DELETE <url>/api/agent/session.

Quando você abre o Porterminal no seu celular, o botão de copiar no canto superior direito copia o mesmo texto de compartilhamento pronto para o agente. Agentes apenas de navegador também recebem um fallback na página base: um espelho Terminal screen legível pelo DOM e uma Terminal input claramente rotulada.

Segurança: <url> significa a URL completa gerada, incluindo seu código de acesso aleatório. O hostname puro do túnel não expõe nada, mas qualquer pessoa (ou qualquer agente) com a URL completa obtém acesso total ao shell, sem elevação. Veja docs/agent-access.md.

Gestos no celular

Teclas modificadoras (Ctrl, Alt, Shift): Toque uma vez para fixar (uma tecla), toque duplo para travar.

Modo de composição (botão ▤): Alterna um campo de entrada de texto onde você pode digitar ou ditar, editar seu texto com recursos completos de edição móvel (autocorreção, sugestões, posicionamento do cursor), e então enviar ao terminal. Útil para comandos mais longos ou entrada de voz.

Configuração

Execute ptn --init para criar uma configuração inicial. Ele descobre automaticamente scripts de projeto em package.json, pyproject.toml ou Makefile e os adiciona como botões:

ptn -i
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

Ou crie ptn.yaml manualmente:

# 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

A configuração é buscada na ordem: $PORTERMINAL_CONFIG_PATH, ./ptn.yaml, ./.ptn/ptn.yaml, ~/.ptn/ptn.yaml.

Segurança

Cada execução cria um novo caminho aleatório de 128 bits, como https://<tunnel>.trycloudflare.com/<access-code>/. Todas as rotas de navegador, WebSocket, MCP, REST, health e estáticas exigem exatamente esse prefixo; o host puro e caminhos errados retornam 404. Isso torna a força bruta em um hostname de túnel descoberto impraticável.

A URL completa gerada ainda é uma credencial do tipo bearer: qualquer um que a obtenha tem acesso ao shell. Reinicie o Porterminal para rotacionar o código se ele vazar. A senha opcional adiciona autenticação aos WebSockets do navegador, mas MCP e REST continuam confiando na URL completa para que os agentes possam usar o fluxo de trabalho de um único link.

Um navegador lembra uma senha bem-sucedida em armazenamento de texto simples restrito àquela URL completa de execução. Salvar uma senha para uma execução mais recente na mesma origem aposenta entradas de senha mais antigas do Porterminal; limpar ou rejeitar uma senha lembrada remove todas elas sem tocar em outro armazenamento do navegador. Consequentemente, execuções simultâneas na mesma origem podem solicitar novamente, enquanto uma conexão já autenticada permanece conectada.

Pela interface: Abra Configurações (ícone de engrenagem) e use a seção Segurança para definir/alterar a senha e alternar a exigência de senha. As alterações exigem reinício do servidor.

Pela 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

Veja docs/security.md para detalhes.

Solução de problemas

A conexão falha? Use a URL completa gerada, incluindo seu código de acesso. Problemas com o túnel Cloudflare também podem ser resolvidos reiniciando o servidor (Ctrl+C, depois ptn) para um novo túnel e caminho de acesso.

uvx ptn ainda executa uma versão mais antiga? Uma instalação existente de uv tool pode ter precedência. Execute uv tool upgrade ptn, ou ignore as ferramentas instaladas com uvx --isolated ptn@latest.

Shell não detectado? Defina sua variável de ambiente $SHELL ou configure os shells em ptn.yaml.

Contribuindo

Este projeto não aceita contribuições externas (pull requests ou alterações de código) por razões de segurança (veja CONTRIBUTING.md). Você é bem-vindo a fazer um fork e executar sua própria cópia sob AGPL-3.0.

Executar a partir do código-fonte:

git clone https://github.com/lyehe/porterminal
cd porterminal
uv sync --frozen
uv run --frozen ptn

Licença

AGPL-3.0