Tucano Proxy

Um proxy. Escolha onde trabalhar.

Use comandos, inspecione no terminal ou abra a interface web local. A CLI independente dispensa o desktop; o app nativo tem download separado.

CLI

Automatize capturas e consulte sessões nomeadas com saída JSON estruturada.

TUI

Inspecione requisições no terminal. Fechar o inspector mantém o serviço em execução.

Inspector web

Abra a interface autenticada no Maestri, no Orca ou no navegador do sistema.

App desktop

Instale o app nativo Tauri separadamente para usar uma janela dedicada no desktop.

Escolha um canal de instalação

Confira a disponibilidade dos canais e os arquivos publicados na página de instalação. Os comandos abaixo são exemplos de cada canal, não uma promessa de que o pacote já foi publicado.

CLI nativa: macOS, Linux e Windows

Use o instalador shell no macOS/Linux ou PowerShell no Windows somente após a publicação do instalador e do arquivo da CLI compatível. Revise ou baixe o script antes. O instalador confere SHA-256 antes de substituir o executável; não altera PATH, confiança do sistema nem proxy do sistema.

Alvos da release: macOS Apple Silicon e Intel; Linux glibc x64 (Ubuntu 22.04+) e arm64 (Ubuntu 24.04+); Windows x64. Use apenas arquivos listados na release, nunca instaladores desktop ou arquivos de outra arquitetura.

Disponível

curl -fsSL https://github.com/plscabral/tucano-proxy/releases/latest/download/install.sh | sh

irm https://github.com/plscabral/tucano-proxy/releases/latest/download/install.ps1 | iex

Download manual

Na instalação manual, baixe o arquivo da CLI e seu .sha256, confira o checksum, extraia e adicione a pasta ao PATH. A CLI nativa instalada dispensa Node e o app desktop.

Catálogos de pacotes

npm exige Node.js/npm e o pacote tucano-proxy publicado. Homebrew exige a fórmula publicada em plscabral/tap. WinGet exige a aprovação de PauloCabral.TucanoProxy.CLI no catálogo. Canais pendentes continuam indisponíveis até a confirmação na página de instalação.

npm install -g tucano-proxy

brew install plscabral/tap/tucano-proxy

winget install --id PauloCabral.TucanoProxy.CLI --exact

Download separado do desktop

Para o app desktop Tauri, use o instalador próprio: abra o .dmg no macOS e arraste para Aplicativos; execute .msi ou setup .exe no Windows; use .AppImage ou .deb no Linux. Esses pacotes são separados da CLI independente.

Primeiro uso e sessões nomeadas

Execute setup para o primeiro uso guiado. Ele oferece confiança no certificado, captura e interface separadamente; você pode recusar confiança ou captura. O setup nunca altera o proxy do sistema. Use uma sessão nomeada por projeto.

tucano-proxy --session demo setup
tucano-proxy --session demo start
tucano-proxy --session demo tui
tucano-proxy --session demo web --open

Todos os comandos usam a sessão demo. Troque demo pelo nome do seu projeto em toda a sequência. Outros comandos e --json não iniciam o assistente automaticamente.

tucano-proxy --session demo setup
tucano-proxy --session demo setup --status --json
tucano-proxy --session demo status
tucano-proxy session list
tucano-proxy --session demo stop

start executa um serviço em segundo plano e inicia o listener do proxy. A TUI e a interface web são clientes desse serviço. Mantenha --session demo nos comandos relacionados; fechar qualquer interface mantém o serviço ativo. Use stop para encerrá-lo.

Sessões simultâneas exigem portas distintas de proxy/API — é assim que dois agentes capturam alvos diferentes sem misturar evidência. O setup pode escolher portas livres; status informa as portas reais. session list mostra cada sessão com portas, captura, flows retidos e proxy do SO, e sinaliza duas disputando a mesma porta; stop --all encerra todas de uma vez. --data-dir define a raiz de armazenamento; o nome da sessão não é um caminho de arquivo. Estado, material da CA e capturas ficam locais.

setup --status --json lê o estado existente do setup e do certificado sem reparar nem regenerar certificados. Repetir o setup preserva as capturas e a CA da sessão.

Capture apenas o tráfego encaminhado

Um listener em 127.0.0.1:8888 não captura todo o tráfego do computador. Configure o aplicativo ou runtime para usar esse proxy. Alguns apps ignoram as opções do sistema ou desviam endereços de loopback. Use a porta indicada por status se for diferente.

Teste HTTP (sh/bash/zsh): execute curl pelo listener e confira a mesma sessão na TUI ou no inspector web. --noproxy remove a lista de exceções do curl para essa requisição. No Windows, use curl.exe e a sintaxe de argumento vazio aceita pelo seu shell.

curl --proxy http://127.0.0.1:8888 --noproxy '' http://httpbin.org/get

O roteamento opcional pelo sistema no macOS/Windows exige consentimento explícito. capture stop encerra a captura e restaura o proxy do sistema controlado pelo serviço. As capturas armazenadas permanecem.

tucano-proxy --session demo capture start --system-proxy --yes
tucano-proxy --session demo capture stop

Para inspecionar HTTPS, o cliente precisa confiar na CA pública desta sessão. Instalar confiança é uma decisão separada do roteamento. ca install --yes ainda exige terminal e pode pedir autorização do sistema; --yes não ignora esses pedidos. Em sistemas não suportados, exporte a CA pública e configure a confiança do runtime. Não desative a verificação TLS.

tucano-proxy --session demo ca status
tucano-proxy --session demo ca export --output demo-ca.pem
tucano-proxy --session demo ca install --yes

Para revogar a confiança depois, use ca uninstall --yes na mesma sessão. O comando remove a confiança do sistema, não os dados da sessão nem os arquivos da CA.

tucano-proxy --session demo ca uninstall --yes

Atalhos do inspector no terminal

Use a ajuda contextual para navegação, filtros, ordenação, seleção múltipla, inspeção, notas, replay e exportação. O teclado dispensa suporte a mouse ou fonte especial.

tucano-proxy --session demo tui --theme auto

Pausar o acompanhamento ao vivo congela a posição de leitura, não a captura. Use capture stop para parar de capturar e stop para encerrar o serviço.

Abra o inspector web autenticado

web --open abre a interface web local, nunca o app desktop nativo. Terminal e navegador mostram a mesma sessão selecionada. A saída de web sem --open ou um link localhost detectado pelo terminal não é uma abertura autenticada.

tucano-proxy --session demo web --open

auto é o padrão. Em um terminal interativo do Maestri ou Orca, escolha navegador integrado, navegador do sistema ou cancelar. Com --json ou entrada/saída redirecionada, auto não pergunta: escolhe o app detectado ou, na ausência dele, o navegador do sistema. Maestri tem prioridade quando ambos os ambientes são detectados.

Escolha o destino explicitamente

tucano-proxy --session demo web --open --target maestri
tucano-proxy --session demo web --open --target orca
tucano-proxy --session demo web --open --target browser

A detecção do Maestri exige MAESTRI_SOCKET e MAESTRI_TERMINAL_ID. Orca usa TERM_PROGRAM=Orca, ORCA_CLI_COMMAND ou ORCA_DEV_REPO_ROOT. A CLI do host escolhido precisa estar disponível. Maestri abre um Portal vinculado; Orca cria uma nova aba no workspace de origem. Destinos explícitos pulam a escolha.

Automação JSON e skill para agentes

Use o parâmetro global --json em scripts não interativos. O sucesso usa um envelope versionado apiVersion/result; falhas contêm error.code e error.message. Confira o código de saída do processo e o status HTTP separadamente. Limite as consultas de flows e busque só os bodies necessários.

tucano-proxy --session demo --json status
tucano-proxy --session demo --json flows list --filter 'status:>=400' --limit 20
tucano-proxy --session demo --json web --open --target auto

Skill para agentes

A skill contém instruções para o agente, não um binário CLI, app desktop ou permissões do sistema. Instale no agente que roda dentro do Maestri, Orca ou outro host. O canal npx exige Node.js e a fonte da skill publicada; confira a disponibilidade antes. A CLI instalada também gerencia a skill incluída.

Disponível

npx skills add plscabral/tucano-proxy --skill tucano-proxy

tucano-proxy skill install --agent agents
tucano-proxy skill status

skill install usa por padrão a pasta compartilhada de agents no seu diretório pessoal. Adicione --project para o projeto atual ou --agent para escolher um agente suportado. Use o mesmo escopo ao consultar ou desinstalar. Prefira acesso somente leitura para inspeção; possuir um token não autoriza mutações em produção.

MCP · CLI

Para MCP pela CLI, habilite MCP em Configurações → MCP da sessão selecionada antes. mcp-stdio usa a configuração existente dessa sessão; não habilita MCP silenciosamente nem usa outra sessão desktop. Não combine mcp-stdio com --json: stdout pertence ao JSON-RPC.

tucano-proxy --session demo mcp-stdio

Atualize ou desinstale pelo canal original

Consulte releases explicitamente; os comandos comuns não atualizam a CLI em silêncio. A atualização substitui executáveis, não sessões, certificados, estado do setup ou capturas. Serviços ativos mantêm a versão carregada; pare e reinicie cada sessão quando puder interrompê-la.

Atualizar

Instalador nativo / Download manual

Instalador nativo/arquivo manual: use update --check e update (scripts exigem --yes), ou execute novamente o instalador revisado. O updater exige o arquivo independente correspondente e seu checksum; nunca usa um instalador desktop como substituto.

tucano-proxy update --check
tucano-proxy update
tucano-proxy update --yes --json

Em instalações por gerenciador de pacotes, use o gerenciador original. Não sobrescreva o executável gerenciado com o instalador nativo. Os comandos abaixo exigem que o pacote tenha sido instalado pelo respectivo canal disponível.

npm install -g tucano-proxy@latest

brew upgrade plscabral/tap/tucano-proxy

winget upgrade --id PauloCabral.TucanoProxy.CLI --exact

Desinstalar

Desinstalar um pacote não revoga a confiança na CA. Se também quiser revogá-la, execute ca uninstall --yes explicitamente em cada sessão confiável enquanto a CLI ainda está instalada. Essa opção é separada da remoção do programa.

Antes de remover o executável, pare a captura em cada sessão ativa para restaurar o roteamento controlado pelo serviço e depois encerre os serviços — stop --all faz isso em uma chamada. A desinstalação pelo gerenciador remove o pacote; na instalação nativa/manual, remova apenas o executável instalado e seu marcador de instalação dedicado, se existir. Preserve diretórios de sessão e arquivos de certificados.

tucano-proxy --session demo capture stop
tucano-proxy --session demo stop
tucano-proxy stop --all

npm uninstall -g tucano-proxy

brew uninstall tucano-proxy

winget uninstall --id PauloCabral.TucanoProxy.CLI --exact

Remova a skill com a mesma ferramenta e o mesmo escopo da instalação. Para skills gerenciadas pela CLI, o comando abaixo remove somente a skill Tucano; não desinstala o executável.

tucano-proxy skill uninstall --agent agents --yes

Para skills gerenciadas por npx, atualize ou remova somente tucano-proxy. Os exemplos abaixo usam o escopo do projeto; use --global em uma instalação global. Para atualizar a skill gerenciada pela CLI, reinstale a skill incluída após atualizar a CLI.

npx skills update tucano-proxy --project

npx skills remove tucano-proxy

Atualize o app desktop pelo instalador da própria release; remova pelo gerenciador de aplicativos do sistema. Comandos de pacotes da CLI não gerenciam o desktop.

Referência desktop e web

As seções abaixo descrevem o inspector gráfico. Atalhos desktop e integração com o sistema pertencem ao app desktop; o navegador usa upload/download para sessões portáveis. Os controles do terminal estão documentados separadamente acima.

Captura gráfica

Proxy MITM local HTTP/HTTPS; conexões WebSocket são encaminhadas, mas a inspeção de frames individuais está planejada. Configure a porta em Configurações → Proxy. Ative o roteamento do sistema explicitamente no macOS/Windows. O app desktop restaura o proxy que controla ao sair normalmente; fechar a TUI da CLI não faz isso. Listas SSL permitem pular a interceptação de hosts, incluindo apps com certificate pinning. A detecção do processo cliente está disponível no macOS/Windows.

Inspector

Inspecione headers, bodies e timing da requisição e resposta lado a lado. Viewers incluem JSON, XML, HTML, texto bruto, hex, imagens e formulários. Posicione o inspector à direita, embaixo ou oculte. Busque no body com ⌘F. O timing inclui DNS, conexão, TLS, TTFB e transferência.

Lista de capturas

A lista virtualizada permite configurar colunas: arraste para reordenar ou redimensionar e dê duplo clique para auto-fit. Use marcas de cor, notas e abas de HTTP, HTTPS, WebSocket, JSON, formulários, XML, JS, CSS, GraphQL, documentos e mídia. Defina um limite de retenção para sessões longas.

Composer e replay

Monte uma requisição HTTP com método, URL, headers e body ou refaça uma captura com sobrescritas. O resultado aparece como uma nova captura. Envie somente requisições autorizadas, principalmente mutações em produção.

Sessões .tucano portáveis

Salve capturas, bodies, notas e marcas como evidência SQLite portável. O desktop usa armazenamento local e Salvar/Abrir; o inspector web usa download/upload. Sessões nomeadas da CLI têm armazenamento local próprio. Revise credenciais e dados pessoais antes de compartilhar o arquivo. Não há sincronização na nuvem nem telemetria.

Compare e Find All

Selecione duas capturas e use ⌘D para comparar headers e bodies lado a lado. ⌘⇧F busca nas URLs, bodies, notas e headers capturados.

Filtros e exportações

Combine filtros chave:valor com AND. Use - antes da regra para negar e aspas em valores com espaços. Texto livre busca no conteúdo capturado.

host:api.example.com status:>=400
method:POST -host:cdn.example.com
header:"x-trace=abc" duration:>500

Exportações em lote

Por captura

• cURL (bash/zsh)
• cURL (Windows cmd)
• PowerShell (Invoke-WebRequest)
• JavaScript fetch
• Python requests
• HTTPie
• Raw HTTP/1.1

Exportações em lote

• Postman Collection v2.1 .postman_collection.json
• HAR 1.2 .har
• LLM Markdown .md

Exportação Markdown para LLM

Exporte tucano.llm.md com prompt personalizado, linguagem-alvo e passos estruturados. Headers sensíveis são mascarados; placeholders entre etapas carregam dicas de localização. Os alvos incluem C#/.NET, TypeScript, Python, Go, Java ou uma linguagem livre. Revise e remova dados sensíveis antes de compartilhar.

Servidor MCP · App desktop

Conecte o Tucano Proxy ao seu agente (Claude Desktop, Claude Code, Cursor, OpenCode, Codex) via Model Context Protocol. O Tucano fala MCP nativamente sobre Streamable HTTP — sem Node, sem npx. Com a bridge MCP do app ligada, o agente passa a enxergar suas capturas em tempo real — pode listar fluxos, ler corpos, refazer requisições com overrides e compor requisições novas.

Pré-requisitos

• Tucano Proxy aberto com a bridge MCP ligada (Configurações → MCP).
• Token de acesso copiado das Configurações do Tucano.

Instalação

O mais simples é o botão Install em Configurações → MCP — ele escreve a entrada automaticamente. Pra configurar na mão, use HTTP no Claude Code/Cursor/OpenCode/Codex, ou a ponte stdio no Claude Desktop:

{
  "mcpServers": {
    "tucano": {
      "type": "http",
      "url": "http://127.0.0.1:7878/mcp",
      "headers": {
        "Authorization": "Bearer paste-the-token-from-tucano-settings"
      }
    }
  }
}

{
  "mcpServers": {
    "tucano": {
      "command": "/Applications/Tucano Proxy.app/Contents/MacOS/tucano-proxy",
      "args": ["mcp-stdio"],
      "env": {
        "TUCANO_MCP_URL": "http://127.0.0.1:7878/mcp",
        "TUCANO_MCP_TOKEN": "paste-the-token-from-tucano-settings"
      }
    }
  }
}

Variáveis de ambiente (transporte stdio)

• TUCANO_MCP_TOKEN — obrigatório. Token de Bearer gerado pelo app.
• TUCANO_MCP_URL — opcional. URL do endpoint MCP (padrão http://127.0.0.1:7878/mcp). Só altere se você mudou a porta.

Ferramentas

Atalhos do desktop

Estes são atalhos do desktop. No Linux/Windows, troque ⌘ por Ctrl. Configurações → Atalhos mostra a lista completa.

Certificado raiz no app desktop

Gere a CA local e escolha Install CA em Configurações → Certificado explicitamente para confiar nela. Captura HTTP dispensa confiança no certificado. A CA do desktop não é reutilizada em silêncio como CA de uma sessão CLI.

macOS usa o keychain e pode pedir autorização de administrador. Windows usa o store ROOT do usuário atual. Configure separadamente os aplicativos com repositórios próprios de confiança.

Firefox

Firefox pode usar um repositório próprio. Importe o certificado público ou ative security.enterprise_roots.enabled em about:config se for adequado ao seu ambiente.

Roadmap

FAQ