Ambientes

Ambientes permitem que você escolha onde os terminais do Maestri rodam. Um workspace pode rodar localmente, em um servidor SSH, dentro de um container Docker, dentro de um Docker Sandbox, ou através de um runtime command-line compatível e customizado.

O ambiente é parte do modelo de workspace e terminal, não apenas um launcher de terminal. Skills, a CLI do Maestri, responsabilidades, uploads, comunicação entre agentes, herança de workspace, recrutamento e andares seguem o ambiente selecionado.

Tipos de ambiente em um relance

  • Local — Trabalhar no Mac atual. Processo local direto. Sem descoberta.
  • SSH — Servidores remotos e máquinas de desenvolvimento. Sessão OpenSSH mais túnel reverso. Host SSH existente, entrada manual.
  • Docker Container — Containers locais existentes. Usa docker exec. Externamente proprietário; o Maestri nunca cria ou deleta. Descoberto de containers em execução.
  • Docker Sandbox — Ambientes de desenvolvimento de IA isolados. Usa sbx exec. Externamente proprietário do Docker Sandboxes. Descoberto de sandboxes existentes.
  • Custom Runtime — Podman, Apple container, Lima e outras ferramentas exec-style. Executável configurado e arrays de argumentos. Externamente proprietário. Configuração manual.

Docker Container e Docker Sandbox são integrações de primeira classe com configuração e descoberta dedicadas. O Custom Runtime oferece as mesmas capacidades do Maestri para ferramentas sem integração dedicada.

Habilitar ambientes

Abra Configurações > Geral > Ambientes.

A página contém interruptores independentes para:

  • Workspaces SSH
  • Containers Docker
  • Docker Sandboxes
  • Runtimes customizados

Terminais locais estão sempre disponíveis e não precisam de interruptor. Um ambiente habilitado aparece no seletor de Conexão ao criar ou editar um workspace ou terminal.

A página de Ambientes também contém a Porta do Bridge compartilhada, com padrão 7433. Túneis SSH, containers, sandboxes e runtimes customizados usam este listener para se comunicar com o Maestri.

A página Configurações > Geral > Ambientes com interruptores para SSH, containers Docker, Docker Sandboxes e runtimes customizados, mais a Porta do Bridge compartilhada

Escolher um ambiente para um workspace

  1. Crie um workspace, ou edite um existente.
  2. Escolha uma opção habilitada em Conexão.
  3. Configure e teste o ambiente.
  4. Defina o diretório de trabalho como ele existe dentro daquele ambiente.
  5. Salve o workspace.

A conexão do workspace vira o padrão para terminais no nível do chão e em todos os andares. Caminhos remotos são mantidos na sua forma remota, incluindo ~; o Maestri não os valida contra o sistema de arquivos local do Mac.

Um workspace local com andares isolados por git deve remover esses andares isolados antes de poder ser convertido em um workspace remoto.

Sobrescrever o ambiente para um terminal

Um terminal pode herdar o ambiente do workspace ou usar sua própria conexão.

  1. Crie ou edite um terminal.
  2. Abra Detalhes.
  3. Escolha Padrão do Workspace, Local, ou outro ambiente habilitado.
  4. Configure e teste a sobrescrita quando necessário.
  5. Salve o terminal.

Padrão do Workspace não armazena sobrescrita de terminal. O terminal resolve a conexão atual do workspace sempre que inicia. Uma escolha específica de terminal é persistida com aquele terminal.

Trocar o ambiente de um terminal em execução reinicia aquele terminal após salvar. Responsabilidades atribuídas e o modo Maestro continuam funcionando em todos os ambientes suportados.

Local

Local é o ambiente padrão. O Maestri inicia o shell configurado diretamente no Mac no diretório de trabalho selecionado.

Terminais locais usam o Unix socket criado pelo Maestri, então não precisam da Porta do Bridge TCP. A CLI e as Skills do Maestri são instaladas localmente pelo app.

Use Local quando:

  • O repositório e as ferramentas estão no Mac atual.
  • O agente deve acessar arquivos locais diretamente.
  • Nenhum isolamento de container ou remoto é necessário.

SSH

O SSH conecta um workspace ou terminal a um host remoto existente usando o cliente OpenSSH do sistema e as chaves em ~/.ssh.

O Maestri usa autenticação por chave, não interativa. Prompts de senha são desativados para que um lançamento de terminal não fique preso atrás de um prompt de autenticação invisível. Chaves de host vistas pela primeira vez são aceitas, enquanto chaves alteradas ainda falham na verificação.

Habilitar SSH

  1. Abra Configurações > Geral > Ambientes.
  2. Habilite Workspaces SSH.
  3. Revise o Caminho do Script. O padrão é ~/.maestri/bin/maestri.
  4. Escolha se deve Adicionar ao PATH.
  5. Confirme a Porta do Bridge compartilhada.

Com Adicionar ao PATH ativado, o Maestri adiciona o diretório do script a arquivos de profile comuns de shell remoto.

Configurar uma conexão SSH

A sheet de SSH contém:

  • Host: nome DNS ou endereço IP.
  • Porta: porta SSH, padrão 22.
  • Usuário: nome da conta remota.

Selecione Testar para rodar um comando não interativo curto através do OpenSSH. Falhas fornecem orientação específica para chaves faltantes, problemas de hostname, conexões recusadas, timeouts e chaves de host alteradas.

Como o SSH funciona

Quando um terminal SSH inicia, o Maestri:

  1. Conecta com /usr/bin/ssh.
  2. Abre um túnel reverso da Porta do Bridge configurada no servidor para a mesma porta no Mac.
  3. Descobre e usa o diretório home remoto.
  4. Instala as Skills habilitadas e o wrapper da CLI do Maestri.
  5. Instala arquivos de responsabilidades atribuídas no projeto remoto.
  6. Inicia o shell remoto no diretório selecionado.
  7. Injeta o ID do terminal, endpoint do bridge e token por terminal.
  8. Entrega o comando do agente após a configuração completar.

O túnel reverso significa que a CLI remota alcança localhost:<Porta do Bridge> no host SSH, enquanto o OpenSSH encaminha com segurança de volta ao Maestri.

O Maestri não instala um daemon no servidor. A CLI instalada é um pequeno wrapper de curl, e o processo SSH é dono do túnel para a sessão do terminal.

Remover SSH

Remover uma configuração SSH tenta remover a CLI provisionada e as Skills habilitadas do home remoto. Não deleta o projeto remoto nem modifica a configuração do servidor SSH.

Docker Container

O Docker Container anexa terminais do Maestri a um container em execução existente através da CLI do Docker. É projetado para containers de desenvolvimento que já foram criados e iniciados pelo Docker Desktop, Docker Compose, OrbStack, outro contexto Docker, ou pelo usuário.

O Maestri nunca cria, inicia, para, reinicia ou deleta o container selecionado.

Configurar um container Docker

A sheet de Docker Container contém:

  • Container: nome ou ID do container em execução.
  • Contexto Docker: nome de contexto opcional. Deixe vazio para usar o contexto Docker local atual.
  • Usuário: usuário opcional do container. Deixe vazio para usar o padrão da imagem.
  • Shell: caminho do shell dentro do container. O padrão é /bin/sh.

O menu de containers lista containers em execução do contexto Docker selecionado e mostra a imagem de cada container. Atualizar recarrega a lista.

Um terminal configurado para rodar dentro de um container Docker, mostrando a seleção de container e os campos de conexão

Testar um container Docker

Selecione Testar para verificar que:

  • A CLI do Docker está disponível.
  • O container selecionado está em execução.
  • O diretório home efetivo existe e é gravável.
  • /bin/sh, bash e curl estão instalados.
  • O shell configurado existe.

Um resultado bem-sucedido exibe Container pronto.

Como a execução Docker funciona

Setup não interativo, operações de responsabilidades, comandos e uploads usam docker exec. Terminais interativos usam docker exec -i -t. Quando configurado, argumentos de contexto e usuário são incluídos em toda invocação.

Para o terminal interativo, o Maestri também passa:

  • O diretório de trabalho selecionado através de --workdir.
  • Variáveis de terminal e bridge através de --env.
  • Sobrescritas seguras de ambiente de terminal.
  • O shell configurado como o processo final.

O container alcança o Maestri em:

host.docker.internal:<Porta do Bridge>

O PATH remoto inclui $HOME/.maestri/bin e $HOME/.local/bin.

Caminhos de workspace Docker

Defina o diretório do workspace como um caminho que existe dentro do container, não o caminho de origem no Mac. Exemplos incluem /workspace, /app ou ~/project.

O Maestri não adiciona mounts nem muda a configuração de sistema de arquivos do container. O container já deve ter acesso ao projeto.

Remover Docker

Remover a configuração Docker tenta remover a CLI do Maestri provisionada e as Skills habilitadas do container. O container e seus arquivos permanecem intactos.

Docker Sandbox

O Docker Sandbox conecta o Maestri a um Docker Sandbox existente através da CLI sbx. Sandboxes fornecem sistemas de arquivos isolados, rede e engines Docker para fluxos de desenvolvimento de IA.

O Maestri se anexa ao sandbox mas não cria, clona, para ou deleta ele. Acesso ao workspace e modo de clone permanecem gerenciados pelo Docker Sandboxes.

Configurar um Docker Sandbox

A sheet de Docker Sandbox contém:

  • Sandbox: nome do sandbox existente.
  • Usuário: usuário opcional do sandbox. Deixe vazio para usar o padrão do sandbox.
  • Shell: caminho do shell dentro do sandbox. O padrão é /bin/bash.

O menu de sandboxes é populado a partir de sbx ls --quiet. Atualizar recarrega os sandboxes disponíveis.

Testar um Docker Sandbox

O teste faz dois trabalhos:

  1. Concede apenas ao sandbox selecionado acesso ao Maestri em localhost:<Porta do Bridge> através da política de rede do Docker Sandbox.
  2. Verifica o diretório home, /bin/sh, bash, curl e o shell configurado.

O Maestri checa a política primeiro, adiciona a regra com escopo apenas quando necessário, e verifica de novo. Um resultado bem-sucedido exibe Sandbox pronto.

Como a execução do Sandbox funciona

Setup não interativo, comandos, operações de responsabilidades e uploads usam sbx exec. Terminais interativos usam sbx exec -i -t. Usuário, diretório de trabalho, variáveis de terminal, credenciais do bridge e sobrescritas seguras de ambiente são encaminhadas para dentro do sandbox.

O PATH remoto inclui $HOME/.maestri/bin e $HOME/.local/bin.

Caminhos de workspace do Sandbox

Use o caminho do projeto como ele aparece dentro do sandbox. O Maestri não controla o modo de clone do Docker Sandbox nem a exposição de diretório do host.

Remover Sandbox

Remover a configuração do Sandbox tenta remover a CLI do Maestri provisionada e as Skills habilitadas. Não deleta o sandbox nem revoga políticas não relacionadas do sandbox.

Custom Runtime

O Custom Runtime conecta através de qualquer CLI local compatível que possa executar um comando arbitrário dentro de um ambiente existente. É a opção avançada para Podman, Apple container, Lima, ferramentas de VM customizadas e runtimes futuros sem suporte dedicado no Maestri.

Como Docker e Sandbox, o Custom Runtime é apenas anexar. O ciclo do alvo permanece com a ferramenta externa.

Configurar um Custom Runtime

A sheet de Custom Runtime contém:

  • Nome: rótulo visível para o usuário, por exemplo Podman Development.
  • Executável: nome do comando ou caminho absoluto do executável.
  • Argumentos de Comando: prefixo exato para setup, testes, comandos, responsabilidades e uploads.
  • Argumentos Interativos: prefixo exato para sessões de terminal, incluindo flags de TTY.
  • Shell: caminho do shell dentro do alvo.
  • Host do Bridge: hostname ou IP que o alvo usa para alcançar o Mac.
  • Prévia de Comando: prévia selecionável do formato do comando interativo.

Argumentos são inseridos como texto compacto de linha de comando e parseados em valores argv discretos. Aspas preservam espaços dentro de um argumento. O Maestri lança o executável diretamente e nunca avalia esses campos como um comando de shell do host.

Argumentos de Comando

O Maestri anexa seu comando remoto após o prefixo não interativo configurado. O prefixo deve selecionar o alvo e preservar stdin quando o runtime exige uma flag para isso.

Valor de exemplo Podman:

exec -i development

Formato de comando resultante:

podman exec -i development <comando-do-maestri>

Argumentos Interativos

O prefixo interativo deve selecionar o alvo, manter stdin aberto e alocar um TTY.

Valor de exemplo Podman:

exec -i -t development

Formato de comando resultante:

podman exec -i -t development <comando-de-shell-do-maestri>

Resolução de executável

Um nome de executável puro é resolvido a partir do PATH do processo do Maestri e localizações comuns:

  • /opt/homebrew/bin
  • /usr/local/bin
  • /usr/bin

O botão de navegar seleciona um executável diretamente. Isso é útil porque aplicações GUI podem ter um PATH diferente de shells interativos.

Host do Bridge

O Maestri combina o Host do Bridge com a Porta do Bridge compartilhada. Valores comuns incluem:

  • Podman: host.containers.internal
  • Ambientes compatíveis com Docker: host.docker.internal
  • Apple container após configurar acesso ao host: host.container.internal
  • Ambientes compartilhando o loopback do host: localhost

O padrão é host.containers.internal. A rede do runtime determina o valor correto.

Testar um Custom Runtime

Selecionar Testar inicia o bridge local do Maestri e verifica o caminho completo:

  • O executável configurado existe.
  • Os Argumentos de Comando alcançam o alvo.
  • O diretório home do alvo é gravável.
  • /bin/sh, bash, curl e env estão disponíveis.
  • O shell configurado existe.
  • O alvo consegue alcançar o Host do Bridge e a Porta do Bridge.

Um resultado bem-sucedido exibe Runtime pronto.

Exemplo Podman

Assuma um container Podman em execução chamado development.

Nome: Podman Development
Executável: podman
Argumentos de Comando: exec -i development
Argumentos Interativos: exec -i -t development
Shell: /bin/bash
Host do Bridge: host.containers.internal

Exemplo Apple container

Assuma um container Apple em execução chamado development.

Nome: Apple Container Development
Executável: container
Argumentos de Comando: exec -i development
Argumentos Interativos: exec -i -t development
Shell: /bin/bash
Host do Bridge: host.container.internal

O acesso ao host do Apple container deve ser configurado separadamente antes que aquele hostname do bridge funcione. Siga a documentação do Apple container para container system dns create. A configuração do sistema pode exigir acesso de administrador e pode afetar o Private Relay, então o Maestri nunca a realiza automaticamente.

Requisitos do Custom Runtime

Uma CLI compatível deve:

  • Executar um comando arbitrário em um alvo existente.
  • Encaminhar stdout e stderr.
  • Encaminhar stdin para provisioning e uploads.
  • Alocar um TTY para sessões interativas.
  • Preservar argumentos anexados como valores separados.
  • Fornecer /bin/sh, bash, curl e env.
  • Fornecer um diretório home gravável.
  • Permitir que o alvo alcance o endpoint do bridge configurado.

Remover Runtime

Remover uma configuração de Custom Runtime tenta remover a CLI do Maestri provisionada e as Skills habilitadas do alvo original. Não remove o ambiente alvo nem os arquivos do projeto.

Comportamento compartilhado do Maestri

SSH, Docker Container, Docker Sandbox e Custom Runtime compartilham o mesmo comportamento de alto nível do Maestri, mesmo que cada transporte lance comandos de forma diferente.

Sequência de provisioning

Quando um terminal remoto inicia, o Maestri geralmente:

  1. Conecta ou executa dentro do alvo selecionado.
  2. Descobre o diretório home efetivo.
  3. Instala o wrapper da CLI do Maestri e as Skills habilitadas.
  4. Instala arquivos de responsabilidades atribuídas no projeto.
  5. Resolve o diretório de trabalho selecionado, incluindo ~.
  6. Inicia o shell interativo com variáveis de terminal e bridge.
  7. Reporta avisos de provisioning dentro do terminal sem esconder o shell.
  8. Entrega o comando do agente configurado após a configuração completar.

Subprocessos de provisioning são cancellation-aware. Fechar ou parar um terminal enquanto a configuração roda termina o comando em vôo de SSH, Docker, Sandbox ou runtime customizado.

Bridge e autenticação

O Maestri usa um listener TCP bridge app-wide para ambientes remotos. Compartilhar uma porta evita um listener por terminal e funciona em todos os andares.

Todo terminal remoto recebe:

  • Um ID de terminal único.
  • Um token secreto único.
  • O endereço do bridge específico do runtime.

Toda requisição deve apresentar tanto o ID do terminal quanto o token. Tokens são revogados quando provedores são removidos. Um terminal não pode autenticar como outro sabendo apenas a porta compartilhada.

SSH alcança o bridge através de um túnel reverso. Docker usa o nome do gateway do host. Docker Sandbox usa uma política de rede com escopo no sandbox. Custom Runtime usa o Host do Bridge configurado.

Variáveis de ambiente

Shells remotos recebem valores incluindo:

  • TERM=xterm-256color
  • COLORTERM=truecolor
  • HOME=<home-remoto>
  • MAESTRI_TERMINAL_ID=<uuid-do-terminal>
  • MAESTRI_HOST=<endpoint-do-bridge>
  • MAESTRI_TOKEN=<secreto-por-terminal>
  • MAESTRI_CLI=<caminho-da-cli-remota>

Sobrescritas seguras de ambiente de terminal são encaminhadas. Sobrescritas não podem substituir HOME, PATH ou qualquer valor MAESTRI_.

Skills e CLI

O caminho padrão da CLI remota é:

~/.maestri/bin/maestri

Skills habilitadas são instaladas sob as raízes de Skill remotas configuradas. Docker, Sandbox e Custom Runtime estendem o PATH com:

$HOME/.maestri/bin
$HOME/.local/bin

SSH também pode persistir o diretório da CLI configurado em profiles de shell remoto quando Adicionar ao PATH está ativado.

Responsabilidades

Responsabilidades atribuídas são instaladas dentro do diretório efetivo do projeto:

<project>/.maestri/roles/<role-id>/

Instalação, atualização, limpeza e reinício de terminal funcionam para todo ambiente. Identidade de conexão é parte da limpeza de responsabilidades, impedindo que terminais com strings de caminho idênticas em sistemas de arquivos diferentes deletem arquivos uns dos outros.

Uploads de arquivos e imagens

Soltar ou colar conteúdo remoto suportado faz o stream para:

/tmp/maestri-drops/

A transferência usa o próprio transporte:

  • SSH faz stream por um comando SSH novo.
  • Docker faz stream através de docker exec -i.
  • Sandbox faz stream através de sbx exec -i.
  • Custom Runtime faz stream através dos Argumentos de Comando.

Arquivos de drop antigos são removidos oportunisticamente. O Maestri então cola o caminho remoto escapado no terminal.

Herança de workspace e andares

  • Ambientes em nível de workspace se aplicam a terminais no nível do chão e em todos os andares.
  • Sobrescritas de terminal persistem com o terminal.
  • Duplicação de workspace preserva a configuração de ambiente.
  • Duplicação de terminal preserva sobrescritas de terminal.
  • Workspaces provisionados programaticamente herdam o ambiente do workspace requisitante.
  • Agentes recrutados herdam o ambiente do terminal gerente quando apropriado.
  • Busca e gerenciamento de terminal cobrem todos os andares, não apenas o andar ativo.

Ambientes desativados

Desativar um ambiente o esconde de novas escolhas de conexão. Workspaces e terminais existentes ainda exibem seu ambiente salvo ao serem editados, mas um provedor remoto desativado segue o comportamento de fallback do Maestri em vez de lançar aquela conexão. Reative o ambiente antes de iniciar aqueles terminais.

Solução de problemas

Ambiente não aparece em Conexão

Habilite-o em Configurações > Geral > Ambientes. Local está sempre disponível.

Terminal remoto roda localmente

O tipo de ambiente salvo provavelmente está desativado. Reative SSH, containers Docker, Docker Sandboxes ou runtimes customizados nas configurações de Ambientes.

Diretório de trabalho está faltando

Caminhos remotos se referem ao sistema de arquivos do alvo. Use o caminho visível dentro do host SSH, container, sandbox ou alvo de runtime customizado. O Maestri não cria mounts de projeto.

Comando do Maestri não alcança o app

Verifique a Porta do Bridge e a rota específica do transporte:

  • SSH: verifique a criação do túnel reverso e a disponibilidade da porta no servidor.
  • Docker: verifique se host.docker.internal resolve no container.
  • Sandbox: rode Testar para o Maestri poder verificar ou adicionar a política com escopo.
  • Custom Runtime: verifique o Host do Bridge e rode Testar de novo.

Verifique também roteamento de VPN, políticas de rede do runtime e comportamento do firewall do host.

Provisioning relata ferramentas faltantes

Ambientes remotos exigem /bin/sh, bash e curl. Custom Runtime também verifica env. Instale pacotes faltantes na imagem ou máquina alvo.

Container Docker ausente da descoberta

Apenas containers em execução no contexto Docker selecionado são listados. Confirme o contexto e inicie o container fora do Maestri.

Container Docker não está em execução

Inicie-o com Docker ou Docker Compose. O Maestri intencionalmente não gerencia o ciclo de vida do container.

Sandbox ausente da descoberta

Confirme que sbx está instalado e que o sandbox aparece em sbx ls --quiet. Crie ou clone o sandbox com Docker Sandboxes antes de anexar o Maestri.

Política de bridge do Sandbox falha

Revise o erro retornado por sbx policy. O Maestri solicita apenas a Porta do Bridge selecionada para o sandbox selecionado.

Autenticação SSH falha

O Maestri usa autenticação por chave com BatchMode. Confirme que a chave pública está presente em ~/.ssh/authorized_keys remoto, depois teste de novo.

Executável do Custom Runtime não encontrado

Use um caminho absoluto ou o botão de navegar. Lembre-se que o PATH do processo GUI pode diferir do PATH do terminal.

Custom Runtime relata um alvo faltante

Confirme que os Argumentos de Comando e Argumentos Interativos incluem o subcomando do runtime e o identificador do alvo na ordem correta.

Provisioning ou uploads do Custom Runtime travam

Os Argumentos de Comando provavelmente não preservam stdin. Adicione a flag de stdin específica do runtime, comumente -i.

Terminal do Custom Runtime sem comportamento interativo

Argumentos Interativos devem solicitar stdin e um TTY. Flags comuns são -i e -t, mas a sintaxe varia por runtime.

Fluxo de configuração recomendado

  1. Habilite o ambiente necessário em Configurações.
  2. Prepare ou inicie o host remoto, container, sandbox ou alvo de runtime fora do Maestri.
  3. Configure o ambiente em nível de workspace.
  4. Rode a ação de Testar específica do ambiente.
  5. Defina o diretório de trabalho como visto dentro do alvo.
  6. Salve o workspace.
  7. Crie um terminal de shell simples antes de lançar um preset de agente.
  8. Verifique pwd, echo $HOME e maestri list.
  9. Adicione sobrescritas específicas de terminal apenas quando um terminal precisa de um alvo diferente.