04/Documentation

Collie no Windows

Windows 11 com Herdr: o que é suportado, instalação com install.ps1, o binário não assinado, atualizações, caminhos longos e o que não foi testado

Como instalar o Collie no Windows 11, abri-lo no celular e corrigir o que der errado. Leia Segurança primeiro: o Collie fornece acesso remoto via shell à sua máquina por padrão de projeto.

No Linux e no macOS, collie start pode publicar o Collie no seu celular para você, com o Tailscale Serve. O Tailscale é um serviço que conecta seus dispositivos em uma rede privada, chamada de tailnet.

No Windows, o Collie não se publica sozinho. O Tailscale Serve dá ao Collie um endereço HTTPS na sua tailnet e, no Windows, você executa essa etapa manualmente. Acessando a partir do seu celular mostra como.

Experimental. Experimental significa que o mantenedor é responsável e testa o código do Windows, mas as partes abaixo ainda não foram totalmente comprovadas. Este é o status completo: Testado - Um ensaio de 25 passos de instalação, atualização e rollback em uma máquina virtual Windows 11, contra cópias locais dos arquivos de lançamento. - Uma instalação real a partir da versão pública v1.16.0 em uma máquina virtual Windows 11: install.ps1 encontrou a versão, o sha256 coincidiu e collie.exe foi executado. Em seguida, collie start, collie status, collie doctor e collie stop funcionaram. - Acesso pelo celular via Tailscale Serve sobre HTTP, em uma tailnet do Headscale: a verificação de Host, collie url, pareamento e o write gate. Ainda não testado - Uma atualização entre duas versões reais no Windows. - O formato HTTPS do Tailscale Serve no Windows e, com ele, a instalação na tela inicial, Web Push e o microfone. - Windows 10, Windows Server, Windows on ARM e os outros itens em O que não foi testado. A verificação de lançamento agora exige o zip do Windows. Apenas o mantenedor pode ignorar isso, no caso de um hotfix para Linux (detalhes).

O que você recebe

O Collie mostra os agentes do seu terminal no celular, para que você possa ver qual deles precisa de atenção e responder.

Os agentes rodam em painéis do Herdr. Um painel é uma janela de terminal dentro do Herdr. O Herdr é um multiplexador de terminal, um programa que mantém seus agentes em execução nos painéis. No Windows, o Herdr é o único multiplexador com suporte.

O Collie lê agentes como Claude Code, Codex, OpenCode, pi e omp. O agente em si deve rodar no Windows. Quais deles funcionam é uma questão do agente, não do Collie.

Antes de começar

Você precisa disto:

Windows 11 em x64. O WSL não é considerado Windows aqui. Dentro do WSL, siga a instalação para Linux em Instalação.
PowerShell. O Windows PowerShell 5.1 que acompanha o Windows 11 é suficiente.
Herdr 0.9.3 ou mais recente para Windows. A etapa 1 abaixo faz a instalação. O projeto Herdr cria a compilação para Windows, e o Collie depende dela.
Um celular com um navegador, um iPhone ou um celular Android.
Uma conta gratuita do Tailscale. Você a cria ao fazer login pela primeira vez no app do Tailscale. O PC e o celular devem estar conectados à mesma conta. O celular acessa o PC por meio dela, e a etapa 6 faz essa configuração.

Verifique se o Smart App Control está ativado, pois ele pode bloquear collie.exe. Abra a Segurança do Windows, depois Controle de aplicativos e do navegador e depois Configurações do Smart App Control. Há três estados possíveis:

Estado	O que isso significa para esta instalação
Desativado	Não bloqueia nada.
Avaliação	O Windows ainda está decidindo se deve ativá-lo. Ele não bloqueou o Collie na máquina virtual de teste.
Ativado	Pode bloquear `collie.exe`, porque o arquivo não está assinado e não tem permissão por arquivo.

Se estiver ativado, leia Binário não assinado primeiro. Ele lista as suas opções.

Do zero ao celular

Siga estas etapas em ordem. Depois da lista, você encontra o que deve ver após cada etapa. Para ler o script do instalador antes de executá-lo, consulte Instalação.

01
Instale o Herdr com o instalador próprio dele e depois verifique a versão:
```
irm https://herdr.dev/install.ps1 | iex
herdr --version
```

Instale o Collie com o instalador dele:

irm https://colliepwa.dev/install.ps1 | iex

01
Abra um NOVO terminal, inicie o Herdr nele e deixe-o aberto:
```
herdr
```

01
Abra um segundo terminal, ou um novo painel do Herdr, inicie o Collie e exiba o endereço dele:
```
collie start
collie url
```

01
Em um painel do Herdr, inicie o seu agente, por exemplo o Claude Code:
```
claude
```

Dê acesso ao telefone com Acessando a partir do seu celular, que o projeto executou apenas por HTTP no Windows. Antes do comando tailscale serve dele, apenas este PC pode acessar o Collie; depois dele, todos os dispositivos da sua tailnet podem, até você parear.

No telefone, digite esse endereço no navegador ou envie-o para você mesmo; depois, adicione o Collie à tela inicial, conforme mostrado em Abra no seu celular.

01
Pareie o telefone executando isto no PC:
```
collie pair
```

O que você deve ver após cada etapa:

O Herdr exibe a saída do instalador. herdr --version exibe 0.9.3 ou mais recente. Esta página não tem um comando próprio do Herdr, porque o projeto Herdr mantém o instalador. Se este falhar, abra herdr.dev e siga as etapas para Windows.
O script exibe cada etapa. Ele termina com uma linha que começa com OK Collie e uma lista de próximas etapas, que começa com Next steps. This script does not take them for you:, depois 1. Open a NEW terminal window. e 3. Start Collie, then print its address:. Para ler o script primeiro, consulte Instalação.
Nenhum serviço é iniciado e nada permanece em execução. O script executa collie.exe version uma vez para verificar se o Windows permite a execução, e isso é tudo.
O Herdr abre e assume o controle desse terminal. Um novo terminal é necessário porque o Windows atribui o novo PATH apenas às janelas abertas após a instalação.
Um segundo terminal é necessário porque o Herdr ocupa o primeiro. collie start exibe o banner do O Collie está em execução e uma observação informando que o Collie não publica uma front door aqui. Uma front door é o endereço HTTPS na frente do Collie que o seu telefone abre. Essa observação é esperada no Windows: a etapa 6 faz essa parte manualmente. Antes do Tailscale ser instalado, ele também exibe esta linha no stderr: error: 'tailscale status' named no host for this node. Essa linha é esperada neste momento e desaparece após a etapa 6.
O seu agente inicia no painel. O Collie o exibe no painel de controle dele.
tailscale serve status mostra o endereço da sua tailnet, e collie url o exibe. Antes desta etapa, collie url pode exibir um endereço de loopback (127.0.0.1), um endereço que apenas este PC pode abrir. Você pode abri-lo em um navegador neste PC para ver o painel de controle.
O telefone exibe o painel de controle do Collie. Os painéis que aguardam você aparecem primeiro.
collie pair exibe um código de oito caracteres, depois uma linha como single-use · expires <time> (10 minutes) e, em seguida, um código QR. Digite o código no Collie no telefone, no aplicativo que você abriu na tela inicial. Com isso, o telefone estará pareado.

Instalação

O que install.ps1 faz e o que você pode alterar.

irm https://colliepwa.dev/install.ps1 | iex

Para ler o script antes de executá-lo, salve-o, abra-o e execute-o como um arquivo:

Invoke-WebRequest -OutFile install.ps1 https://colliepwa.dev/install.ps1
notepad install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

install.ps1 não precisa de Bun, nem de Git e nem de bash. Ele analisa as últimas cinco versões, pega a primeira que contém um zip do Windows, verifica o sha256 e interrompe se houver divergência. Um sha256 é a impressão digital do arquivo. O script exibe cada etapa e nunca solicita privilégios de administrador. Se nenhuma versão contiver o zip, ele para com descrito abaixo.

A política de execução padrão, Restricted, que é a regra do Windows sobre quais scripts podem ser executados, rejeita arquivos de script baixados. A última linha da opção "leia primeiro" define Bypass para essa execução única. Unblock-File .\install.ps1 é a outra alternativa. A forma com irm ... | iex executa o texto do script diretamente e dispensa isso.

O script coloca a versão em %LOCALAPPDATA%\collie\versions\<version>, aponta a junção current para ela e adiciona current\bin ao PATH do seu usuário. Uma junção é um link de pasta no Windows, e current sempre aponta para a versão em execução. O script executa collie.exe version uma vez para confirmar se o Windows permite a execução. Nada mais é iniciado. Uma segunda execução não altera nada e aponta para collie update.

Variável	Efeito
`COLLIE_DIR`	Onde instalar. Padrão `%LOCALAPPDATA%\collie`. Mantenha o caminho curto.
`COLLIE_TAG`	Instale uma versão exata, por exemplo `v1.16.0`.
`COLLIE_UPDATE_REPO`	O repositório GitHub de onde baixar. Padrão `AltanS/collie`.
`COLLIE_NO_PATH_EDIT=1`	Não altere seu PATH. Execute `<COLLIE_DIR>\current\bin\collie.exe`.

O zip também se encontra na página de cada versão no GitHub, ao lado do respectivo arquivo .sha256. Utilize o script, em vez de fazer uma instalação manual do zip.

collie start registra uma tarefa no Agendador de Tarefas chamada herdr.collie. O Agendador de Tarefas é o utilitário do Windows que executa rotinas em horários ou eventos específicos. A tarefa inicia o Collie durante o seu logon com um token restrito, ou seja, sem privilégios de administrador.

A tarefa executa um inicializador, um pequeno programa que reinicia a bridge caso ela seja encerrada com erro. A bridge é o componente do Collie que roda no seu PC e disponibiliza a página web para o seu telefone.

Acessando a partir do seu celular

Etapa 6 do "Zero ao telefone", na íntegra. Trata-se dos mesmos passos usados no Linux e macOS, executados manualmente. O projeto os executou uma vez no Windows, via HTTP, em uma tailnet do Headscale (o Headscale é uma implementação auto-hospedada do servidor Tailscale), usando um navegador de desktop redimensionado para tela de telefone. A configuração HTTPS abaixo não foi testada, e nenhum telefone ou agente real foi usado. Caso alguma etapa falhe, relate o problema (onde).

Atenção. A partir da execução do comando tailscale serve (etapa 3 abaixo) até o pareamento de um dispositivo, o Collie fica acessível a todos os dispositivos da sua tailnet, permitindo que leiam e digitem nos seus painéis. Antes desse comando, apenas este PC consegue acessar o Collie. Execute as etapas no telefone e collie pair logo em seguida. Se outras pessoas compartilham sua tailnet, pareie imediatamente e consulte Segurança sobre como restringir o acesso ao Collie.

Instale o Tailscale no PC e no telefone e acesse a mesma conta em ambos: tailscale.com/download.

No console de administração do Tailscale, abra DNS, ative o MagicDNS e selecione Enable HTTPS.

01
Em um novo terminal no PC, publique a porta local do Collie (8787 por padrão) na sua tailnet:
```
tailscale serve --bg --set-path=/ 8787
```

Crie a pasta de configuração do Collie caso ela não exista e abra o arquivo .env:

New-Item -ItemType Directory -Force "$env:APPDATA\herdr\plugins\config\herdr.collie"
notepad "$env:APPDATA\herdr\plugins\config\herdr.collie\.env"

01
Adicione estas duas linhas ao final do arquivo, substituindo pelo seu próprio nome obtido na etapa 3, e salve:
```
COLLIE_PUBLIC_HOSTS=myhost.tail1234.ts.net
COLLIE_PUBLIC_URL=https://myhost.tail1234.ts.net
```

01
Reinicie a bridge e exiba o endereço:
```
collie restart
collie url
```

O Collie escuta apenas neste PC, em um endereço de loopback que somente este PC pode acessar. No Linux e macOS, o collie start executa o Tailscale Serve para você. É isso que significa "porta de entrada gerenciada": o próprio Collie publica o endereço. No Windows, o collie start não faz isso, portanto você deve executar o Tailscale Serve manualmente.

Na etapa 3, o Tailscale exibe uma linha com um endereço semelhante a https://myhost.tail1234.ts.net. O nome é o trecho que vem após https://. Copie-o. O comando tailscale serve status exibe o mesmo endereço:

https://myhost.tail1234.ts.net (tailnet only)
|-- / proxy http://127.0.0.1:8787

O comando é o mesmo que collie start executa automaticamente no Linux e macOS. O --set-path=/ substitui qualquer serviço que este PC já esteja disponibilizando em / na sua tailnet.

Nota. Em uma tailnet do Headscale, o comando HTTPS da etapa 3 falha com error enabling https feature: error 501 Not Implemented, pois o Headscale não emite certificados HTTPS. Até que você publique, o collie doctor exibe um aviso na linha front-door: this tailnet has no HTTPS certificates, so an https front door cannot be published. Nesse caso, faça a publicação via HTTP, que foi a opção testada pelo projeto no Windows: tailscale serve --bg --http=80 --set-path=/ 8787. A publicação ocorre na porta 80 da tailnet, portanto o endereço é http://<name> sem porta. Utilize esse endereço http:// em COLLIE_PUBLIC_URL. Após esse comando, a verificação da linha front-door tem sucesso. Na versão 1.16.0, o aviso continua sendo exibido. O uso de HTTP puro é aceitável aqui porque o Tailscale criptografa o tráfego entre os dispositivos da tailnet (WireGuard), mantendo o tráfego HTTP restrito à tailnet. Nunca utilize tailscale funnel. Em conexões HTTP, a instalação na tela inicial, o Web Push e o uso do microfone permanecem desativados. No Linux e macOS, o modo HTTP nativo do Collie publica diretamente na porta da bridge (COLLIE_SERVE_MODE). Como o Collie não executa o Serve no Windows, essa variável não altera a publicação aqui.

Em uma tailnet com HTTPS ativado, o Tailscale atribui ao endereço um certificado em que o telefone confia. No Headscale, consulte a observação acima. A instalação na tela inicial, o Web Push (notificações para o telefone) e o uso do microfone exigem HTTPS. Em conexões HTTP puras, esses recursos ficam desativados (Entrada de voz e Web Push).

Na etapa 4, o Bloco de Notas pergunta se deseja criar o arquivo caso ele não exista. Clique em Sim. O diretório corresponde à pasta de configuração do plugin Herdr para herdr.collie, por padrão %APPDATA%\herdr\plugins\config\herdr.collie. O Collie consulta o Herdr para obtê-la, portanto herdr plugin config-dir herdr.collie exibe esse caminho.

COLLIE_PUBLIC_HOSTS é a verificação de Host: o Collie inspeciona o nome do site informado em cada requisição e rejeita qualquer um que não esteja nessa lista, impedindo que páginas web o acessem via DNS rebinding. COLLIE_PUBLIC_URL é o endereço exibido por collie url e pelo código QR de collie pair. Acesse o Collie pelo nome completo: a validação de Host recusa o endereço IP da tailnet e o nome curto. O Collie também tenta identificar o nome da tailnet por conta própria na inicialização. As duas linhas tornam isso garantido.

O Collie não gerencia esse mapeamento no Windows. Os comandos collie stop e collie uninstall o mantêm inalterado. tailscale serve status lista o mapeamento e tailscale serve reset remove todas as configurações do Serve no PC. Nunca utilize tailscale funnel: o Funnel expõe o Collie na internet pública.

Caso prefira usar um proxy reverso (programa que encaminha requisições web para o Collie) ou outro túnel, Implantação descreve as alternativas. O fluxo é Variante C, com COLLIE_PUBLIC_HOSTS configurado para o nome que o telefone acessa. A primeira execução de collie start não aciona avisos de firewall, pois o Collie escuta apenas nesta máquina.

Abra no seu celular

Transfira o endereço de collie url para o telefone: digite-o ou envie-o para você mesmo. No iPhone, acesse pelo Safari. No Android, acesse pelo Chrome. O telefone precisa ter o aplicativo Tailscale instalado e conectado à sua tailnet.
Adicione o Collie à tela inicial para que ele abra em tela cheia como um aplicativo: - iPhone: no Safari, toque em Compartilhar, toque em Adicionar à Tela de Início e depois em Adicionar. - Android: no Chrome, abra o Collie Configurações e toque em Instalação no card superior.
Abra o Collie a partir do novo ícone.
No aplicativo, abra Configurações, depois Sistema e, em seguida, Dispositivos pareados.
Execute collie pair no PC, digite o código e um nome, depois toque em Emparelhar este dispositivo.

Digite o código no app que você abriu a partir do ícone. Não escaneie o código QR que collie pair exibe: a câmera o abre em uma aba do navegador, e no iPhone o app da tela de início mantém seu próprio armazenamento, separado do Safari, de modo que um pareamento feito na aba não é transferido.

O código é válido por 10 minutos e funciona uma vez. Execute collie pair novamente se o tempo expirar. O pareamento encerra o acesso aberto mencionado no Aviso acima (Parear um dispositivo).

Comandos do dia a dia

Execute estes comandos em qualquer terminal. Cada um funciona como no Linux e no macOS, com as observações sobre Windows abaixo.

Comando	O que faz no Windows
`collie start`	Registra a tarefa `herdr.collie` se necessário e inicia a bridge.
`collie stop`	Desativa a tarefa, encerra uma bridge em execução e seu inicializador, e exibe `bridge stopped`. O Collie permanece desligado, inclusive no seu próximo logon, até `collie start`.
`collie restart`	Reinicia apenas a bridge.
`collie status`	Informa o nome da tarefa e seu estado, e mostra o banner do O Collie está em execução.
`collie doctor`	Verifica a instalação, o Herdr, caminhos longos e arquivos secretos, e exibe uma solução para cada problema.
`collie url`	Exibe o endereço a ser aberto no celular.
`collie logs`	Exibe as últimas linhas do arquivo de log.
`collie update`	Atualiza para a versão mais recente (Update).
`collie update --rollback`	Volta para a versão anterior (Update).
`collie uninstall`	Remove a tarefa (Uninstall).

Update

Atualize pelo terminal ou pelo celular, da mesma forma que no Linux e macOS:

collie update

A atualização baixa o release, substitui collie.exe, reinicia a bridge e verifica se ela responde. Se não responder, o Collie reverte para a versão que funcionava, em cerca de um minuto e quinze segundos. O botão Update no celular executa a mesma sequência.

Para reverter manualmente, execute isto. Não precisa de rede. Ele aponta current para a versão anterior mais recente que ainda estiver no disco e reinicia a bridge. Se essa versão não iniciar, o Collie avança novamente e não altera nada:

collie update --rollback

Uma pasta de versão antiga pode permanecer em versions\ até o inicializador reiniciar, pois o Windows não apaga uma pasta em uso por um programa aberto. A próxima atualização a remove.

Atenção. Um checkout de código-fonte nunca se atualiza sozinho no Windows: collie update e o botão do celular informam isso em uma única frase e não alteram nada. Toda instalação no Windows feita antes do primeiro zip é um checkout de código-fonte. Mudar para a instalação por zip é um passo manual único: execute collie uninstall para remover a tarefa antiga e depois execute install.ps1. Depois disso, collie update funciona.

O Collie permite uma instalação por máquina Windows, e collie start recusa uma tarefa que execute outra, motivo pelo qual a tarefa antiga deve ser removida primeiro. Você também pode permanecer em um checkout de código-fonte e atualizá-lo manualmente: baixe a tag mais recente, execute bun run build e depois collie restart. A compilação precisa do bash do Git for Windows.

Versões até a v1.15.0 inclusive não conseguem substituir um collie.exe em execução e falham com EPERM. A correção (PR 309) saiu pela primeira vez na v1.15.1. As melhorias posteriores de atualização no Windows, como o botão Update do celular no Windows, saem pela primeira vez na v1.16.0.

Uninstall

collie uninstall

collie uninstall interrompe a bridge e remove a tarefa do Agendador de Tarefas. Ele mantém a pasta de instalação, seu .env e a entrada no PATH do usuário, assim como toda instalação mantém seus arquivos. Em seguida, exibe mais duas linhas para o PowerShell. A primeira remove a pasta de instalação. A segunda remove apenas current\bin do seu PATH de usuário, por meio do registro. O Collie exibe as duas linhas individualmente, contendo sua pasta real. Elas se parecem com isto, com quebra de linha aqui para caber:

cmd /c rmdir /s /q "<install folder>"
$k = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
$k.SetValue('Path', (($k.GetValue('Path', '', 'DoNotExpandEnvironmentNames') -split ';' |
  Where-Object { $_.TrimEnd('\') -ne '<install folder>\current\bin' }) -join ';'),
  $k.GetValueKind('Path'))
$k.Close()

Copie as linhas da própria saída do Collie quando puder. O Collie não remove um mapeamento de tailscale serve feito manualmente por você (Acessando a partir do seu celular).

Quando algo quebrar

Execute collie doctor primeiro, depois localize seu problema abaixo.

collie doctor verifica a instalação e exibe uma solução para cada problema encontrado. Depois, leia a seção abaixo correspondente ao que você vê. Se nenhuma corresponder, consulte o log, descrito em Logs.

Para relatar um problema, abra uma issue em github.com/AltanS/collie/issues. Informe que você usa Windows, forneça a versão do Collie obtida com collie version e cole a saída de collie doctor e as últimas linhas do log. Remova dados privados primeiro. O log pode conter texto do painel.

Binário não assinado: SmartScreen e Smart App Control

O collie.exe não é assinado, por isso o Windows não reconhece quem o publicou. Leia isto antes de executar o instalador.

Dois recursos do Windows podem impedir a execução de um programa não assinado:

O SmartScreen pergunta antes de executar um programa baixado da internet. Para um arquivo baixado no navegador, clique em Mais informações e depois em Executar assim mesmo.
Smart App Control não permite liberação por arquivo. Se estiver ativado e bloquear o Collie, você não poderá liberar esse arquivo individualmente. install.ps1 mostra o bloqueio ao executar collie.exe version e não exibe nenhuma linha de sucesso.

Se o Smart App Control bloquear o Collie, você tem estas opções, nesta ordem:

Verifique se ele está ativado: abra Segurança do Windows, depois Controle de aplicativos e do navegador e depois Configurações do Smart App Control.
Compile a partir do código-fonte (Compilar a partir do código-fonte), o que gera collie.exe na sua própria máquina. Isso não foi testado em uma máquina onde o Smart App Control está ativado.
Use um computador onde o Smart App Control esteja desativado ou relate o bloqueio em uma issue.
Por fim, desative o Smart App Control. Isso é difícil de desfazer: a documentação da Microsoft afirma que ativá-lo novamente pode exigir a restauração do Windows, portanto leia primeiro a página atual da Microsoft.

A verificação de sha256 no install.ps1 identifica se o download está corrompido ou foi alterado. Ela não atesta quem publicou o arquivo, pois o hash fica ao lado do zip, e quem pode substituir um pode substituir o outro. A assinatura do binário é uma etapa futura possível, sem data definida.

Caminhos longos

O que você vê: um painel não abre, e o Herdr exibe The directory name is invalid (os error 267). collie doctor avisa antes: LongPathsEnabled is 0 on this machine.

O Herdr não consegue iniciar um painel em uma pasta cujo caminho tenha mais de 260 caracteres a menos que os caminhos longos do Windows estejam ativados. collie doctor também avisa quando a própria pasta de instalação for muito longa.

Em um PowerShell executado como administrador:

Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' `
  -Name LongPathsEnabled -Value 1

O Windows pode exigir uma reinicialização para que programas já em execução reconheçam a alteração. De qualquer forma, mantenha suas pastas de trabalho com caminhos curtos.

O Task Scheduler recusa um usuário padrão

O que você vê: collie start falha com error: schtasks /Create /TN herdr.collie failed, o Windows reporta 0x80070569 e o Collie informa que a conta não tem a permissão "Fazer logon como tarefa em lote".

Isso afeta uma conta de usuário padrão que nunca teve essa permissão. Uma conta de administrador geralmente a tem.

Um administrador concede a permissão:

Execute secpol.msc.
Abra Políticas Locais e depois Atribuição de Direitos de Usuário.
Abra Fazer logon como tarefa em lote e adicione a conta.
Execute collie start novamente.

O Windows Home não inclui secpol.msc.

Arquivos secretos

O que você vê: collie doctor exibe uma linha secrets-private, por exemplo can be read by other accounts, com uma correção.

O Collie limita quem pode ler seus arquivos secretos: sua conta, SYSTEM e Administrators. O Windows não tem o modo 0600, então o Collie define a lista de controle de acesso (ACL) de suas pastas de estado e configuração.

collie doctor

A linha secrets-private tem três respostas:

Resposta	Significado
Private	As pastas são privadas para a sua conta, SYSTEM e Administrators.
Loose	Outra conta pode ler uma pasta ou um segredo. Isso é um erro, e `doctor` exibe a correção.
Not checked	O Collie não consegue ler a lista, então informa `cannot confirm`. Isso é um aviso.

Uma pasta em um compartilhamento de rede ou em um volume FAT ou exFAT fica como "not checked", pois não há lista para ler. Mantenha as pastas de estado e configuração em uma unidade NTFS neste PC.

A bridge repara uma pasta permissiva na inicialização, mas apenas se for uma pasta que o Collie acabou de criar, uma pasta padrão no seu perfil de usuário ou uma pasta vazia ou que contenha apenas arquivos do próprio Collie. Qualquer outra pasta é verificada e gera um aviso, com o comando icacls que a corrige. collie doctor e outros comandos não alteram nada.

Para desfazer um reparo: antes de realizá-lo, a bridge salva a lista antiga em acl-backups na pasta de estado e exibe a linha para desfazer. Execute-a em um terminal aberto como administrador:

icacls <folder> /restore <backup file>

COLLIE_NO_ACL_REPAIR=1 desativa todas as alterações. O Collie ainda verifica e emite avisos. A descrição completa das regras está em Arquivos secretos no Windows.

Logs

O log da bridge fica em collie.log na pasta de configuração do plugin (%APPDATA%\herdr\plugins\config\herdr.collie\collie.log por padrão). collie logs exibe as últimas linhas. O Collie apenas adiciona dados a ele e nunca o rotaciona, então o arquivo cresce enquanto a bridge estiver em execução. Para esvaziá-lo, execute collie stop, exclua o arquivo e depois execute collie start.

Compilar a partir do código-fonte

O zip de release não precisa de toolchain. Um build a partir do código-fonte ainda precisa do Bun, do Git e do bash do Git for Windows no seu PATH, porque bun run build chama bash. Um build sem bash está planejado e não foi concluído.

O que é suportado

Um host: Windows 11 em x64, com Herdr como multiplexador.

Um crew é composto por várias máquinas, cada uma executando um Collie, exibidas sob uma única URL (Crews).

	Suportado	Não suportado, pode funcionar, não testado
Windows	Windows 11, x64	Windows 10, Windows Server e Windows no ARM
Multiplexador	Herdr 0.9.3 ou mais recente para Windows	tmux, zellij e tuios: nenhum tem compilação nativa para Windows
Serviço	Agendador de Tarefas, um Collie por máquina	Um serviço do Windows, winget e MSI
Crew	Collie em uma única máquina	Uma máquina Windows entrando em uma crew
Porta de entrada	Você mesmo publica, manualmente	Uma porta de entrada gerenciada pelo Collie
Binário	`collie.exe`, não assinado, com um sha256	Um binário assinado

Estes limites também se aplicam:

O Collie permite uma instalação por máquina Windows. O nome da tarefa é sempre herdr.collie.
O Collie não rotaciona collie.log (Logs).
herdr plugin install não é um caminho de instalação do Windows. Use install.ps1 e depois collie start.
Os botões de ação do Herdr não existem no Windows, pois precisam de bash.
A compilação do Herdr para Windows é feita pelo projeto Herdr. O Collie depende dela e não tem controle sobre ela.

Crews

Uma máquina Windows não pode entrar em uma crew nesta versão. collie crew invite, crew join, crew add, crew deputy, crew approve-promote e collie promote recusam a operação no Windows, informam isso em uma frase e não alteram nada. O Collie em uma máquina Windows isolada funciona de forma autônoma.

Migrando do script da comunidade

O que muda se você executou o script da comunidade e o que não é mantido.

Antes desta versão, o Windows rodava sob o contrib/windows/collie-ctl.ps1, um script escrito pela comunidade. O Collie agora executa a tarefa por conta própria, e cada verbo do script é um verbo do collie com o mesmo nome. Depois de atualizar, execute collie restart uma vez. Se o script executava a tarefa chamada herdr.collie, o Collie assume o controle dela com o mesmo nome. Até você reiniciar, collie status e collie doctor informam que a tarefa ainda executa o script antigo.

Duas coisas não são migradas:

Um nome de tarefa personalizado. O script permitia definir COLLIE_TASK_NAME. O Collie não lê essa opção, e a tarefa é sempre herdr.collie. Uma tarefa registrada com outro nome permanece onde está, e o Collie não a interrompe nem a remove. Exclua-a antes de executar collie start, ou dois supervisores iniciarão a bridge. No PowerShell: schtasks /Delete /TN "<your task name>" /F.
Cópias de logs de falha. O script mantinha uma cópia do log quando a bridge falhava. O Collie não mantém. As cópias antigas permanecem no disco até você excluí-las.

Como isso é testado e quando o status experimental termina

Por que o Collie indica experimental, para leitores que desejam ver as evidências. Você não precisa disso para usar o Collie.

Duas palavras nesta página têm significado fixo:

Suportado significa que o mantenedor é responsável pelo código do Windows e o testa: uma execução de CI a cada push e um ensaio em uma máquina virtual com Windows 11 antes de cada tag de release (ADR 0075). CI é a execução automática de testes no GitHub. Um ADR é um registro de decisão curto mantido no repositório.
Experimental significa que a atualização entre duas versões reais e o acesso do celular via HTTPS ainda não foram comprovados.

Em que se apoia o suporte:

O workflow windows.yml, um workflow de CI, executa os testes de bridge, cli e scripts no windows-latest a cada pull request e a cada push para main. Ele ainda não é uma verificação obrigatória. O mantenedor planeja torná-lo obrigatório após cerca de dez execuções bem-sucedidas consecutivas.
Cada release compila collie-<version>-windows-x64.zip com um arquivo .sha256.
Antes de cada tag de release, o mantenedor executa um ensaio, make win-rehearse. Ele instala uma versão em uma máquina virtual limpa com Windows 11, atualiza a partir do terminal e do endpoint do celular, força uma falha na verificação de integridade e confere a reversão. A atualização usa uma cópia local dos arquivos da release. Se a máquina virtual não estiver disponível, a tag aguarda.
O Windows 11 é a segunda validação além do CI, já que o runner de CI é o Windows Server.
A instalação real a partir da release pública v1.16.0 foi executada em uma VM com Windows 11. install.ps1 encontrou a versão, baixou o arquivo zip, o sha256 foi correspondente e collie.exe executou como 1.16.0. collie start registrou a tarefa e iniciou a bridge. collie status indicou running, collie doctor encerrou com código 0 e collie stop a interrompeu. O script em https://colliepwa.dev/install.ps1 está ativo e é idêntico em bytes ao script da release v1.16.0.
O acesso pelo celular foi executado em uma VM com Windows 11 em uma tailnet Headscale, via HTTP. tailscale serve --bg --http=80 --set-path=/ <port> publicou o Collie. As duas linhas .env e collie restart fizeram collie url e o banner collie start exibirem o nome da tailnet. A partir de outra máquina da tailnet, a página, /api/health e /api/snapshot responderam pelo nome completo, e uma requisição pelo endereço IP da tailnet ou pelo nome curto foi recusada. O pareamento na interface do celular funcionou e, depois dele, uma gravação sem a credencial recebeu 403 "device not paired". Um navegador de desktop redimensionado para tela de celular substituiu o aparelho.
O Smart App Control na VM de teste está em modo de avaliação, e nem o Smart App Control nem o SmartScreen bloquearam o Collie nela. Esta página descreve o que o Windows documenta, não um bloqueio que tenha ocorrido.

O termo experimental sai apenas quando todas estas condições forem atendidas simultaneamente:

Uma release inclui o zip do Windows, install.ps1 está em colliepwa.dev e uma instalação e uma atualização foram executadas contra uma release real. As três primeiras etapas foram concluídas: a v1.16.0 traz o zip, o endereço está ativo e a instalação foi executada. Uma atualização entre duas versões reais ainda não ocorreu, pois exige uma segunda versão com o zip.
A verificação do Windows é obrigatória na proteção de branches. A proteção de branches é a configuração do GitHub que bloqueia o merge até que as verificações indicadas passem.
O gate de release lê o workflow do Windows. O gate é a primeira etapa do workflow de release, que aguarda os testes antes de publicar.
A tolerância para a ausência do zip do Windows está desativada. Ela está desativada agora, como explica a próxima seção.

Uma release sem o zip do Windows

A verificação de release exige o zip do Windows a partir de agora. Apenas o mantenedor pode ignorar isso, no caso de um hotfix para Linux. O job de release verifica isso em scripts/windows-asset.ts. Ele busca uma release estável anterior (que não seja rascunho nem pré-lançamento) contendo o zip, e a v1.16.0 é uma delas. A partir de 15/11/2026, o zip é obrigatório em qualquer caso, sendo obrigatório também se a lista de releases do GitHub não responder. A única exceção é uma chave que o mantenedor pode ativar para um hotfix de Linux enquanto o build do Windows estiver quebrado: a variável de repositório COLLIE_WINDOWS_ASSET_OVERRIDE. Uma release gerada com essa chave ativa não contém o zip do Windows.

Releases anteriores à v1.16.0 não contêm o zip do Windows. O que você vê quando a release mais recente não tem o arquivo:

install.ps1 analisa as cinco releases mais recentes. Para cada uma, imprime <tag> has no Windows build. Trying the next older release.. Em seguida, imprime collie install: none of the newest 5 releases of AltanS/collie carries a Windows build yet. Nothing was installed. e termina com Install failed. e uma linha orientando a fixar uma release que contenha o arquivo. Nada é alterado na sua máquina. Para fixar uma versão, defina COLLIE_TAG.
collie update em uma instalação do Windows informa error: release <version> has no Windows build; try again after the next release. Nothing was changed.

Para verificar, abra a página de versões no GitHub e procure um arquivo chamado collie-<version>-windows-x64.zip.

O que não foi testado

Lista simples, para que nada aqui soe como promessa:

Uma atualização entre duas releases reais no Windows. O teste usou uma cópia local dos arquivos de release.
O formato HTTPS do Tailscale Serve no Windows (o Headscale respondeu 501 Not Implemented), além da instalação na tela inicial, Web Push e o microfone. Também um telefone real, um agente executando em um painel do Herdr e um proxy reverso, no lugar de Tailscale Serve.
Um collie update --rollback manual no Windows. O rollback automático após uma falha na atualização foi testado.
Migrar de um checkout do código-fonte para a instalação via zip, e atualizar um checkout do código-fonte manualmente.
Instalação manual do zip, sem install.ps1.
Windows 10, Windows Server, Windows no ARM, tmux, zellij e tuios no Windows.
Um bloqueio real do Smart App Control e PowerShell 7 para install.ps1.
Um build a partir do código-fonte em uma máquina onde o Smart App Control está ativado.
A correção do Agendador de Tarefas no Windows Home. A rota foi verificada com um usuário padrão cujo nome continha um espaço e um caractere não ASCII.
Um volume FAT em hardware real. A resposta "não verificado" é coberta por testes unitários.
A recusa de uma tarefa de um segundo Collie, coberta apenas por testes unitários.
Se o Explorer enxerga o novo PATH sem fazer logoff, e uma edição do PATH por um usuário padrão.
O provedor de voz local-cli com um mecanismo real. Sua limpeza foi testada com um comando de teste: o Collie encerra a árvore de processos do comando, mas um processo iniciado por um helper que já terminou pode continuar em execução (Entrada de voz e Web Push).

Editar esta página no GitHub