Maestri Box

O Maestri Box é o Maestri rodando num servidor Linux, sem tela. Você pareia a Box com o Maestri no seu computador ou com o Maestri Remote, e ela aparece nos seus espaços como qualquer outro computador.

O canvas dela fica vivo mesmo sem ninguém olhando, então seus terminais e agentes continuam trabalhando mesmo com o seu computador desligado.

Requisitos

  • Linux: Ubuntu 24.04 ou 22.04, ou Debian 12.
  • CPU: x86_64 ou arm64.
  • Memória: 1 GB, ou 2 GB se agentes como Claude Code ou Codex forem rodar nela.
  • Disco: cerca de 1 GB.
  • Rede: uma porta TCP aberta para os seus dispositivos, a 7434 por padrão (dá para trocar), ou uma rede privada como o Tailscale.

Alpine, NixOS e hosts que pausam depois de alguns minutos não são suportados. A maioria dos provedores de VPS funciona, inclusive a máquina arm64 gratuita da Oracle Cloud.

Instalação

Primeiro, confira a máquina. Isso não muda nada:

curl -fsSL https://themaestri.app/box/script.sh | bash -s -- --check

Depois instale a partir da sua própria conta:

curl -fsSL https://themaestri.app/box/script.sh | sudo bash

O instalador configura o serviço maestri-box, inicia ele e mostra um código de pareamento no final. Rodar de novo atualiza a Box e mantém seus dados e pareamentos.

Com qual conta ela roda

Por padrão a Box roda com a sua conta, então os agentes dela usam seus projetos, suas chaves de git e SSH e seus logins do Claude ou do Codex.

Isso também quer dizer que um dispositivo pareado com Controle total pode fazer tudo o que a sua conta faz. Se outras pessoas forem parear com a Box, dê uma conta dedicada para ela:

curl -fsSL https://themaestri.app/box/script.sh | sudo bash -s -- --system-user

Use --user <nome> para rodar com outra conta que já existe. Passe a mesma opção para o --check, assim ele confere essa conta. A Box nunca roda como root.

Pareamento

O instalador termina com um código de pareamento. Para ver um de novo, rode isto num terminal no servidor:

maestri-box pair

Todos os comandos maestri-box desta página funcionam sem sudo num terminal na Box. Use sudo só quando você estiver logado no servidor com outra conta, por exemplo por SSH como root.

Ele mostra o endereço da Box e um código de seis dígitos, e um QR code.

Um terminal depois de sudo maestri-box pair, mostrando o código de pareamento com a validade, o endereço da Box, os outros endereços em que ela está e a chave

No Maestri Remote, escaneie o QR code.

No computador, clique no + no fim dos ícones de espaço e escolha Outro Computador. Digite o endereço e o código e clique em Parear.

A Box aparece como um espaço novo. Abra o espaço de trabalho dela e você já está trabalhando no servidor.

O Maestri num Mac no espaço da Box, com um terminal no canvas da Box respondendo whoami, hostname, uname e pwd a partir da Box

Para parear mais dispositivos, abra Pareamento nas configurações da Box num dispositivo que já está pareado, ou rode maestri-box pair num terminal na Box.

Dica

Na AWS, Oracle Cloud e Tencent Cloud o endereço público não fica na máquina, então a Box só enxerga os privados. Pareie com maestri-box pair --host <endereço público> e ela guarda esse endereço.

Cada dispositivo tem Controle total ou Somente leitura. Mude isso, ou revogue um dispositivo, nas configurações da Box, em Dispositivos.

Pareamento seguro

  • Um código só existe enquanto o pareamento está aberto, e ele muda a cada poucos minutos.
  • Tentativas erradas são limitadas: cinco por endereço, depois esperas cada vez maiores. Dez no servidor inteiro aposentam o código.
  • Todo dispositivo novo mostra uma notificação e aparece em Dispositivos, onde você pode revogar ele.
  • Parear pelo QR code também confere que é mesmo a sua Box do outro lado.

Para deixar a Box totalmente fora da internet pública, coloque ela numa rede privada como o Tailscale. Veja Rede.

Configurações

Num Mac ou PC, as configurações da Box são as mesmas páginas das Configurações do próprio Maestri, preenchidas a partir da Box. Clique com o botão direito no ícone do espaço da Box e escolha Configurações…, ou vá em Configurações → Wire → Dispositivos, selecione a Box e clique em Configurações…. Só dispositivos com Controle total abrem elas.

  • Geral: Sistema mostra qual versão do Maestri Box ela roda e os avisos das verificações dela. Notificações, Ambientes e Git funcionam como nas suas próprias Configurações.
  • Terminal: Aparência tem as cores dos terminais da Box e o tema padrão, cada um podendo voltar ao padrão da própria Box. Avançado tem o limite de memória por terminal.
  • Agentes: Responsabilidades, Contas e Uso. Entrar numa conta abre um terminal no canvas da Box, onde você faz o login como faria no seu próprio computador.
  • Wire: Pareamento tem o código e o QR code para parear outro dispositivo, e os endereços da Box para parear um computador na mão. Dispositivos lista todos os dispositivos pareados com a Box, cada um com Controle total ou Somente leitura, e Revogar.
  • Licença: se a Box está licenciada, no teste com os dias que faltam, ou com o teste encerrado. Ative uma chave aqui, ou Desative. Quando o teste acaba, é aqui também que você escolhe, uma vez só, o espaço de trabalho que continua de graça.
  • Atualizações: Buscar Atualizações…, e Atualizar agora… quando uma atualização está pronta.
  • Dados: os backups da Box.

O Maestri Remote tem uma versão mais curta delas. Abra pelo menu do espaço da Box, em Computer Settings….

Cores dos terminais

A Box não tem tela, então os terminais dela usam as cores que você escolhe em Aparência dos terminais: Escuro, Claro, ou Seguir um dos seus dispositivos, e aí os terminais da Box trocam sempre que esse dispositivo muda entre claro e escuro. Por padrão eles seguem o primeiro dispositivo que você pareou.

Os terminais abertos trocam na hora, e os agentes que suportam isso também trocam as cores ao vivo, como o Claude Code com o tema em auto.

Rede

Abra a porta TCP 7434 no firewall do provedor, e no ufw ou firewalld se algum estiver ligado. Na Oracle Cloud, rode também sudo iptables -I INPUT -p tcp --dport 7434 -j ACCEPT e sudo netfilter-persistent save.

Para deixar a Box fora da internet, prenda ela a um endereço privado, como o do Tailscale:

maestri-box config listen-address 100.101.102.103

config listen-address all volta a escutar em tudo. Para usar outra porta, rode maestri-box config port 7500, ou instale com curl -fsSL https://themaestri.app/box/script.sh | sudo MAESTRI_BOX_PORT=7500 bash.

Atualizações

A Box procura atualizações quando inicia, a cada 24 horas, e quando um dos seus dispositivos conecta, no máximo uma vez por hora. Ela nunca instala uma sozinha.

Quando sai uma versão nova, seus dispositivos avisam. Clique em Atualizar agora… nas configurações da Box, no computador ou no Maestri Remote. A Box reinicia, e os terminais abertos nela param. Buscar Atualizações… procura na hora.

No servidor, sudo apt update && sudo apt upgrade faz o mesmo. Seus dados e pareamentos continuam.

Licença

Uma Box nova começa com 7 dias de teste. Para ativar sua chave, abra Licença nas configurações da Box, ou rode isto num terminal na Box, pelo Maestri ou pelo Maestri Remote:

maestri-box license activate

Depois do teste, sem chave, a Box mantém um espaço de trabalho de graça. Escolha qual em Licença, ou com maestri-box license pick.

Comandos

pair [--host <endereço>]   mostra um código de pareamento e espera um dispositivo
status                     se está rodando, e onde escuta
doctor                     confere a Box e diz como corrigir o que estiver errado
devices                    dispositivos pareados
remove <nome ou id>        despareia um dispositivo
password set | clear       uma senha para parear o Maestri Remote na mão
license status | activate  a licença
config port <número>       escuta em outra porta
config listen-address <ip | all>
setup --user <nome> | --system-user

Rode cada um como maestri-box <comando>, e maestri-box --help para ver o resto. Os logs ficam em journalctl -u maestri-box.

Limitações

  • Uma conta que também usa o app de desktop do Maestri na mesma máquina, aberto ou não, não pode rodar a Box. Use --user <nome> ou --system-user.
  • Páginas web nos portais não abrem janelas nativas. Popups abrem como portais, e downloads, impressão e seletores de arquivo não funcionam.
  • Num contêiner, use uma imagem Ubuntu ou Debian, um usuário que não seja root com um volume na pasta pessoal dele, e a porta publicada. Pareie com --host, já que o contêiner só enxerga o endereço privado dele.

Solução de problemas

Meu dispositivo não alcança a Box. Rode maestri-box doctor. Ele diz o que está errado e como corrigir. Na maioria das vezes a porta está fechada em algum firewall.

O código expirou. Rode maestri-box pair de novo.

Desinstalação

sudo apt remove maestri-box

Seus dados ficam na pasta pessoal da conta da Box. sudo apt purge maestri-box também remove a conta dedicada maestri, se foi a Box que criou.