Solução de problemas

Os três problemas que mais derrubam quem está usando o Vupt pela primeira vez, e como resolver cada um. Se o seu sintoma não estiver listado, abra uma issue em github.com/Riiquezz/vuptdev/issues com o comando que falhou, a saída e o seu SO — os mantenedores respondem em 24h nos dias úteis.

Falhas de instalação do agente PTY

Todo agente (Claude Code CLI, Codex CLI, Cursor CLI, Aider, Cline, OpenCode) roda dentro de um pseudo-terminal (PTY) que o Vupt aloca por tarefa. A alocação de PTY é a superfície de falha mais comum porque depende de APIs específicas do kernel de cada sistema operacional.

Windows 11

Sintoma: PTY allocation failed: ConPTY not available no diário da tarefa, agente não inicia.

Causa raiz: o ConPTY do Windows exige a build 17763 ou superior. O Windows 11 sempre atende esse requisito, mas a falha aparece quando o binário do Vupt não tem o co-host conhost.exe ou quando uma Group Policy desativa a alocação de console Win32.

Solução (tente nesta ordem):

1. Rode o instalador como Administrador uma vez — isso registra a associação do conhost.exe em HKLM em vez de HKCU, que algumas Group Policies corporativas exigem.

2. Verifique se o conhost.exe está no PATH:

   Get-Command conhost.exe

   Se estiver ausente, o TI da sua empresa desabilitou. Peça para liberarem %WINDIR%\System32\conhost.exe no allowlist para o processo do Vupt.

3. Plano B: ative o WSL2 e rode os agentes dentro do subsistema Linux. Defina defaults.pty_backend = "wsl" em ~/.vupt/config.toml e reinicie o Vupt.

macOS

Sintoma: o Gatekeeper bloqueia o binário do agente embutido no primeiro uso: "vupt-pty-helper não pode ser aberto porque o desenvolvedor não pode ser verificado".

Causa raiz: os agentes embutidos no Vupt são assinados e notarizados, mas o Gatekeeper mesmo assim mostra o aviso na primeira invocação de um binário fora de /Applications. O ticket de notarização às vezes não se propaga para binários aninhados dentro do bundle .app.

Solução:

1. Abra Configurações do Sistema → Privacidade e Segurança, role até a seção Segurança e clique em Abrir Mesmo Assim ao lado da mensagem do binário bloqueado.

2. Se nenhuma mensagem aparecer (o Gatekeeper matou o processo silenciosamente), invoque o helper manualmente uma vez pelo Terminal:

   /Applications/Vupt.app/Contents/Resources/agents/vupt-pty-helper --version

   O Gatekeeper vai pedir confirmação, e quando você aceitar, o binário fica liberado para todas as invocações futuras.

3. Se você está no macOS 15 (Sequoia) ou superior, talvez precise conceder ao Vupt Acesso Total ao Disco em Privacidade e Segurança → Acesso Total ao Disco para o PTY conseguir gravar os diários da tarefa em ~/.vupt/.

Linux

Sintoma: posix_openpt: Permission denied ou PTY allocation failed: locale not supported.

Causa raiz: ou /dev/ptmx não está com permissão de escrita para todos (incomum, mas acontece em distros hardened como Alpine), ou o locale solicitado está ausente.

Solução:

1. Confirme as permissões de /dev/ptmx:

   ls -l /dev/ptmx
   # esperado: crw-rw-rw- 1 root tty 5, 2

   Se não estiver crw-rw-rw-, sua distro está travada. Adicione seu usuário ao grupo tty:

   sudo usermod -aG tty $USER
   newgrp tty

2. Instale o locale que o Vupt pediu (padrão en_US.UTF-8; quem usa pt-BR pode precisar do pt_BR.UTF-8):

   sudo locale-gen en_US.UTF-8 pt_BR.UTF-8
   sudo update-locale

3. Se o binário do próprio agente (Codex CLI, Aider, etc.) foi instalado à parte via pip install ou npm install -g, refaça a instalação com o mesmo $PATH que o Vupt enxerga. A checagem mais simples:

   # no Linux:
   /opt/vupt/vupt --print-env | grep PATH

   Use esse mesmo PATH na hora de instalar o agente.

Problemas de conexão com o sandbox

O sandbox público em demo.vupt.dev está em manutenção no momento — o Vupt v1.3 entrega uma landing Solicitar acesso ao sandbox como caminho intermediário (veja /sandbox-request). As notas abaixo cobrem tanto o caminho do sandbox público (quando voltar no v1.4) quanto o caminho do sandbox local (já disponível pelo app desktop).

Sandbox público retorna 502 ou NXDOMAIN

Sintoma: demo.vupt.dev devolve Bad Gateway ou falha o DNS.

Solução:

1. Cheque a página de status em status.vupt.dev. Se o sandbox estiver marcado como em manutenção, use o formulário em /sandbox-request para solicitar acesso agendado.

2. Enquanto o sandbox público estiver indisponível, rode seu próprio sandbox local pelo app desktop: abra o Vupt, crie um novo projeto apontando para um repositório git de testes e use o template Experimente um esquadrão de exemplo (Configurações → Templates → Esquadrão de exemplo). Isso dá o mesmo fluxo ponta a ponta (criar esquadrão → agentes paralelos → revisar diff) na sua própria máquina.

Criação de sessão excede 2s

Sintoma: o sandbox carrega, mas criar uma nova sessão trava além do SLA de 2s.

Solução:

1. Aquecimento de cold-start: o container do sandbox escala para zero durante a madrugada. Recarregue depois de 30s e o container já aquecido atende a próxima requisição em menos de 500ms.

2. Se o timeout persistir por mais de 2 minutos, o provisionador está sob carga. Tente em horários de menor pico (horário comercial BR é 09:00–18:00 BRT) ou use o caminho do sandbox local descrito acima.

Dados cruzam entre sessões (esquadrão de outra pessoa aparece na sua visão)

Sintoma: você vê um esquadrão que não criou — ou seus dados somem entre reloads.

Causa raiz: o sandbox usa cron de reset diário e cookies de sessão efêmeros. Se você abriu o sandbox em duas abas do navegador ou ficou com um cookie velho de outro dia, o ponteiro de sessão pode dessincronizar.

Solução:

1. Limpe os cookies de demo.vupt.dev e recarregue.

2. Abra uma janela anônima / privada e refaça seu teste por lá.

3. O estado do sandbox é zerado às 00:00 UTC todo dia — salve qualquer saída de esquadrão antes disso, ou ela não sobrevive ao reset.

Erros ao colar chaves BYOK

BYOK (Bring Your Own Key) é como todo provedor pago é configurado — o Vupt guarda a chave no cofre do sistema operacional e persiste apenas uma referência (por exemplo, vupt/anthropic) em ~/.vupt/config.toml. O próprio cofre é a fonte da verdade, não o arquivo de configuração. Veja Configuração para a referência completa de chaves.

Chave com espaço em branco no final falha silenciosamente

Sintoma: o provedor responde 401 Unauthorized mesmo a chave estando correta.

Causa raiz: copiar de um terminal ou de um PDF muitas vezes acrescenta uma quebra de linha ou um U+00A0 (espaço não-quebrável). A maioria dos gateways de API dos provedores trata o espaço como parte da chave e rejeita.

Solução:

1. Use o botão Validar Chave em Configurações → Provedores — ele apara os espaços antes de gravar e ainda chama o endpoint /v1/models do provedor para confirmar.

2. Se precisar colar manualmente, normalize antes:

   # macOS / Linux — apara espaços
   pbpaste | tr -d '[:space:]' | pbcopy

   # Windows
   Get-Clipboard | ForEach-Object { $_.Trim() } | Set-Clipboard

3. Depois de colar, a UI mostra os 4 últimos caracteres da chave. Se a contagem estiver com 1 a mais, você colou espaço junto.

Chave colada no provedor errado

Sintoma: o agente falha na autenticação com Invalid API key, mas a chave é realmente válida.

Causa raiz: o Vupt tem um campo de chave por provedor, e eles se parecem. Uma chave Claude Code (prefixo sk-ant-) colada no campo Codex (que espera prefixo sk-) falha porque o gateway da OpenAI rejeita o prefixo sk-ant-.

Solução: confira novamente os cabeçalhos do provedor em Configurações → Provedores:

Provedor	Prefixo da chave
Claude Code (Anthropic)	sk-ant-
Codex (OpenAI)	sk-
Cursor CLI	csk-
Aider (qualquer gateway LLM)	varia — combine com o provedor para onde aponta o Aider

Chave revogada pelo provedor

Sintoma: funcionava ontem, hoje devolve 401 em todas as tentativas.

Causa raiz: o provedor rotacionou ou revogou a chave. Isso acontece em incidentes de segurança ou quando você loga em um dispositivo novo.

Solução:

1. Acesse o dashboard de API do provedor:

   • Anthropic: console.anthropic.com/settings/keys
   • OpenAI: platform.openai.com/api-keys
   • Cursor: cursor.com/settings/api

2. Gere uma chave nova e substitua a entrada do cofre em Configurações → Provedores → Editar → Substituir chave. A entrada do cofre é o único lugar de onde o Vupt lê em runtime; substituir não exige reiniciar o app.

3. Se o provedor revogou por padrão de uso incomum, audite o diário da sua tarefa procurando algum prompt que pode ter disparado os filtros de segurança do provedor (por exemplo, pedidos para raspar dados de usuários). O Vupt não tenta de novo silenciosamente prompts bloqueados — a falha fica no diário literal.

Ainda travado

• Abra uma issue: github.com/Riiquezz/vuptdev/issues (resposta em 24h nos dias úteis)
• Página de status: status.vupt.dev
• Discord (fuso BR/LatAm): veja o link no rodapé do app desktop