lyehe/porterminalTúnel de terminal web/mcp rápido e simples para seu telefone e PC
<p align="center">
<a href="https://github.com/porterminal/porterminal">
<img src="https://raw.githubusercontent.com/porterminal/porterminal/master/assets/header.png?v=9" alt="PTN — Terminal Portátil com arte QR decorativa." width="800">
</a>
</p>
<h1 align="center">Dê ao seu agente qualquer computador</h1>
<p align="center">
Um comando. Uma URL. Um terminal real para o seu agente, uma visualização ao vivo para você.
</p>
<p align="center">
<a href="https://pypi.org/project/ptn/"><img src="https://img.shields.io/pypi/v/ptn?style=flat-square&logo=pypi&logoColor=white&label=PyPI" alt="PyPI"></a>
<a href="https://pypi.org/project/ptn/"><img src="https://img.shields.io/pypi/pyversions/ptn?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/porterminal/porterminal/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/porterminal/porterminal/ci.yml?branch=master&style=flat-square&logo=github&label=CI" alt="CI"></a>
<a href="https://github.com/porterminal/porterminal/blob/master/LICENSE"><img src="https://img.shields.io/github/license/porterminal/porterminal?style=flat-square" alt="License"></a>
</p>
Execute o Porterminal em um computador Windows, macOS ou Linux e forneça o
link gerado ao seu agente de IA. Ele recebe um shell real com os arquivos, ferramentas e projetos
naquela máquina. Abra o mesmo link no seu celular ou em qualquer navegador para acompanhar
o agente trabalhando e digitar no terminal dele.
## Comece aqui
No computador que você deseja dar ao seu agente:
```bash
uvx ptn
```
1. **Forneça o link ao agente.** Pressione **`c`** na janela local do Porterminal
para copiar a URL e as instruções de conexão. Cole-as no seu agente
com uma tarefa. O agente precisa de suporte a MCP remoto ou de uma forma de fazer requisições HTTP.
2. **Abra sua visualização.** Escaneie o código QR ou abra a URL completa em um navegador.
Selecione a **aba 🤖** do agente para ver seu terminal.
3. **Trabalhem juntos.** Acompanhe a saída, responda a um prompt interativo, digite um
comando ou feche a aba para encerrar esse shell.
4. **Acesse seu computador de qualquer celular.** Use o navegador do seu celular para
vibe coding, correções rápidas, execução de comandos e muito mais.
Para iniciar em um projeto específico, use `uvx ptn /path/to/project`.
Para opções de instalação, consulte [installation](https://github.com/porterminal/porterminal/blob/master/docs/installation.md), ou use um instalador abaixo.
> **O link é a chave para o computador.** A URL completa e o código QR concedem
> acesso ao shell. Compartilhe-os apenas com pessoas e agentes em quem você confia.
> [Leia o modelo de segurança](#security).
## O agente trabalha. Você fica no controle.
| Seu agente | Você |
|------------|-----|
| Executa comandos no shell real do computador | Acompanha a mesma saída ao vivo em um navegador |
| Lê telas de terminal e responde a prompts | Digita no mesmo terminal quando necessário |
| Mantém o estado do shell entre chamadas de ferramentas | Alterna entre abas do agente e pessoais |
| Usa MCP ou HTTP para conectar | Usa o código QR ou a URL de um celular ou desktop |
A entrada do terminal é compartilhada; coordene a digitação com seu agente. O Porterminal
suporta aplicativos de terminal interativos, múltiplas abas e reconexão a sessões
em execução enquanto o servidor e a sessão permanecem ativos.
A interface para celular inclui teclas Ctrl/Alt/Shift, seleção por toque, rolagem,
zoom por pinça e um campo de composição para editar ou ditar entradas mais longas.
Consulte [terminal controls](https://github.com/porterminal/porterminal/blob/master/docs/frontend_features.md).
## Experimente a demonstração
Dê a um agente um pequeno projeto de fatura com uma verificação falhando. Veja-o encontrar o
bug, editar o arquivo e deixar as verificações verdes. Depois responda ao prompt de rótulo do recibo
do seu celular e faça o agente ler o resultado.
O [demo guide](https://github.com/porterminal/porterminal/blob/master/docs/demo.md) inclui um projeto pronto para copiar, uma tarefa para o agente
e um plano de gravação de 60 segundos. Ele demonstra comandos, alterações de arquivos,
verificação e entrada humana em uma única sessão compartilhada.
## Conecte seu agente
Pressionar **`c`** copia as instruções para os métodos de conexão disponíveis.
O servidor em execução também as disponibiliza em `<url>/llms.txt`.
Aqui, **`<url>` é a URL completa gerada, incluindo seu código de acesso**.
| Capacidade do agente | Conexão |
|------------------|------------|
| MCP remoto | `<url>/mcp` — Streamable HTTP |
| Requisições HTTP | `<url>/api/agent/run` — REST |
| Automação de navegador | Abra `<url>/`; use **Terminal screen** e **Terminal input** |
O MCP expõe quatro ferramentas: `run_command`, `read_screen`, `send_keys` e
`send_signal`. O REST retorna um `session_id` que o agente reutiliza para comandos
e interação subsequentes. Os shells do agente aparecem como abas 🤖 no seu navegador.
Consulte [agent access](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md) para configuração do cliente, exemplos de requisições,
tempos de vida das sessões e comandos de longa duração.
## Instalação
Requer **Python 3.12+**. O Porterminal tenta instalar o `cloudflared`
automaticamente quando ele está ausente.
| Método | Executar ou instalar | Atualizar |
|--------|----------------|--------|
| uvx | `uvx ptn` | `uvx --isolated 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` |
**Instale uv e Porterminal juntos:**
Windows (PowerShell):
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/porterminal/porterminal/master/install.ps1 | iex"
```
macOS / Linux:
```bash
curl -LsSf https://raw.githubusercontent.com/porterminal/porterminal/master/install.sh | sh
```
## Uso
Após a instalação, execute `ptn` ou `ptn /path/to/project`.
| Opção | Finalidade |
|--------|---------|
| `--no-tunnel` | Executa sem um túnel Cloudflare |
| `--mcp-only` | Expõe apenas o MCP; desativa o código QR, o terminal no navegador e a API REST |
| `--compose` | Inicia com o campo de composição móvel habilitado |
| `--init` | Gera `.ptn/ptn.yaml` com botões descobertos a partir dos scripts do projeto |
| `--password` | Adiciona uma senha ao acesso do terminal no navegador |
| `--help` | Mostra todas as opções |
| `--version` | Mostra a versão instalada |
Durante a execução: **`c`** copia as instruções do agente, **`u`** copia apenas a
URL, e **`s`** mostra o texto de compartilhamento na tela (**`q`** fecha-o).
**Ctrl+C** encerra o Porterminal. No modo somente MCP, as teclas de compartilhamento usam a URL do MCP.
Shells personalizados, botões da barra de ferramentas e configurações de inicialização ficam em `ptn.yaml`.
Consulte [configuração](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md).
## Segurança
O Porterminal dá acesso a um shell real com as permissões do seu usuário. O
diretório inicial é uma conveniência, não um sandbox nem um limite de acesso a arquivos.
Cada inicialização cria um novo caminho de acesso aleatório de 128 bits. O hostname
puro do túnel e caminhos incorretos retornam 404, mas qualquer pessoa com a URL completa pode usar o shell.
Mantenha a URL e o código QR privados, pare o Porterminal quando terminar e reinicie-o
para rotacionar o código de acesso caso o link vaze.
**A senha opcional protege as conexões do navegador. O MCP e a REST usam a
URL completa como credencial e não exigem essa senha.**
Consulte [segurança](https://github.com/porterminal/porterminal/blob/master/docs/security.md) para o modelo completo e o comportamento da senha.
Relate vulnerabilidades por meio da [política de segurança](https://github.com/porterminal/porterminal/blob/master/.github/SECURITY.md).
## Documentação e desenvolvimento
- [Instalação](https://github.com/porterminal/porterminal/blob/master/docs/installation.md)
- [Acesso do agente: MCP, REST e fallback no navegador](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md)
- [Configuração e gravação da demonstração](https://github.com/porterminal/porterminal/blob/master/docs/demo.md)
- [Configuração](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md)
- [Arquitetura](https://github.com/porterminal/porterminal/blob/master/docs/architecture.md)
- [Processo de desenvolvimento e lançamento](https://github.com/porterminal/porterminal/blob/master/docs/development.md)
- [Changelog](https://github.com/porterminal/porterminal/blob/master/docs/CHANGELOG.md)
Relatos de bugs e solicitações de recursos são bem-vindos como
[issues](https://github.com/porterminal/porterminal/issues).
Pull requests externos e contribuições de código não são aceitos; consulte
[CONTRIBUTING.md](https://github.com/porterminal/porterminal/blob/master/CONTRIBUTING.md). Você pode fazer um fork e executar sua própria cópia.
## Licença
[AGPL-3.0](https://github.com/porterminal/porterminal/blob/master/LICENSE)