Início rápido

Este capítulo guia-o pela sua primeira sessão completa com o Bromure Agentic Coding: criar um espaço de trabalho, escolher um agente e a forma como este se autentica, partilhar uma pasta de projeto com o ambiente isolado, executar uma primeira tarefa, inspecionar o que o agente enviou pela rede e encerrar a sessão para poder retomá-la mais tarde. Reserve cerca de dez minutos.

O passo a passo utiliza deliberadamente os valores predefinidos sempre que possível. Cada definição que aqui aborda tem uma referência completa mais adiante no manual — os links são fornecidos ao longo do caminho e reunidos em Para onde ir a seguir.

Antes de começar

Precisa de:

• Ter o Bromure Agentic Coding instalado e iniciado pelo menos uma vez, com a imagem base do SO pronta — consulte Instalação. (É necessário um Mac com Apple Silicon a executar o macOS 14 ou posterior.)
• Uma forma de autenticar o agente de programação. Para o Claude Code — o agente predefinido — isso é uma chave de API da Anthropic ou uma subscrição do Claude na qual possa iniciar sessão. Ambos os caminhos são abordados no passo 4 abaixo.
• Opcionalmente, uma pasta de projeto no seu Mac na qual queira que o agente trabalhe. Um pequeno repositório git é o melhor primeiro teste, mas qualquer pasta serve.

Uma ideia a reter antes de começar: o agente é executado dentro de uma VM Ubuntu descartável e as suas credenciais reais nunca entram nessa VM. A VM apenas contém tokens de marcador de posição falsos; um proxy do lado do anfitrião troca-os pelos valores reais no momento em que um pedido sai do seu Mac. Esta é a fronteira de transmissão e é a razão pela qual o passo a passo lhe pede para colar uma chave de API na aplicação em vez de no terminal.

Crie o seu primeiro espaço de trabalho

Um espaço de trabalho é a unidade de isolamento: uma VM Ubuntu com o seu próprio disco de sistema, a sua própria pasta pessoal persistente, os seus próprios agentes, credenciais e políticas de segurança. Pode criar quantos quiser; este passo a passo cria um.

1. Abra a janela principal. A barra lateral esquerda tem o cabeçalho ESPAÇOS DE TRABALHO; na sua parte inferior encontra-se um botão circular preto + (dica: Novo espaço de trabalho). Clique nele.

2. Um editor de definições abre-se numa janela intitulada Novo espaço de trabalho, pré-preenchida a partir do seu modelo de preferências e com o nome "Espaço de trabalho predefinido" (numerado automaticamente se esse nome já estiver em uso). O painel Geral está a ser mostrado. Escreva um nome à sua escolha — por exemplo O Meu Primeiro Projeto. O nome é o único campo obrigatório; tudo o resto neste passo a passo é aperfeiçoamento opcional. Se quiser, escolha uma Cor — ela tinge o mosaico do espaço de trabalho na barra lateral.

Ainda não clique em Criar — vale a pena visitar antes dois painéis.

Escolha um agente e a autenticação

3. Clique em Agentes na barra lateral de categorias do editor. O painel mostra um cartão por cada agente suportado — Claude Code, Codex e Grok Build — cada um com um interruptor para ativar. O Claude Code está ativado e apresenta a etiqueta laranja Primário logo à partida: o agente primário é aquele que é iniciado automaticamente no primeiro separador da sessão. Os outros agentes ativados também estão instalados e autenticados, mas é você que os inicia a partir de um novo separador.

Dentro do cartão do Claude Code vê quatro modos de autenticação: Token de API, Subscrição (início de sessão interativo) com um link Registar…, Bedrock (AWS) e Modelo local (esbatido com "— descarregue um modelo em Modelos locais" até que um modelo local esteja instalado). Escolha um dos dois primeiros:

4. Se tiver uma chave de API da Anthropic: selecione Token de API e cole a chave no campo Chave de API da Anthropic. A chave é armazenada encriptada no anfitrião; a VM recebe apenas um falso que preserva a estrutura, e o proxy substitui a chave real nos pedidos à Anthropic — em mais lado nenhum. Deixe a caixa de verificação Exigir aprovação para utilizar desativada por agora; ativá-la faria com que a aplicação pedisse o seu consentimento na primeira vez que cada sessão utilizasse a chave (consulte Credenciais).

5. Se tiver uma subscrição do Claude: selecione Subscrição (início de sessão interativo) — a predefinição de fábrica — e clique em Registar…. O Bromure arranca uma VM temporária e descartável, sem acesso às suas pastas ou credenciais, executa o início de sessão real do Claude dentro dela e abre a página de início de sessão do fornecedor no navegador predefinido do seu Mac. Inicie sessão aí; tem alguns minutos antes de o fluxo expirar. Em caso de sucesso, os tokens capturados são armazenados encriptados no anfitrião, a VM descartável é destruída e a aplicação pergunta se pretende partilhar o registo com Todos os espaços de trabalho ou Apenas este espaço de trabalho. Uma vez registado, o cartão mostra um selo verde além dos controlos Voltar a registar… e Esquecer. As VMs dos seus espaços de trabalho nunca realizam OAuth por si próprias e nunca contêm os tokens reais — o anfitrião injeta-os na transmissão e trata da renovação.

6. Isto é tudo o que o painel Agentes precisa para uma primeira sessão. (Ativar o Codex ou o Grok Build em paralelo funciona da mesma forma — cada cartão obtém o seu próprio modo de autenticação — mas um agente é mais do que suficiente por hoje.)

Partilhe uma pasta de projeto

7. Clique em Pastas na barra lateral de categorias. Este painel lista as pastas do anfitrião que serão montadas na VM. Como diz a legenda, cada pasta é montada com o seu nome real — por exemplo, ~/Documents no seu Mac aparece como ~ubuntu/Documents na VM — e um espaço de trabalho está limitado a 8 pastas. Um espaço de trabalho novo em folha mostra "Nenhuma pasta partilhada."

8. Clique em Adicionar pasta… e escolha a sua pasta de projeto no seletor de diretórios. Ela aparece na lista com o seu caminho completo no anfitrião (remova-a mais tarde com o botão de menos se mudar de ideias). Dentro da VM estará ativa em /home/ubuntu/<basename> — os mesmos ficheiros, não uma cópia, pelo que as alterações que o agente fizer ficam no seu Mac instantaneamente.

Nota: Partilhar uma pasta é opcional. Tudo o que está sob /home/ubuntu da VM é persistente por espaço de trabalho, pelo que também pode clonar um repositório dentro da VM e manter o ambiente isolado totalmente separado do sistema de ficheiros do seu Mac. Eliminar um espaço de trabalho nunca toca nas pastas partilhadas do anfitrião.

9. Clique em Criar. O editor fecha-se e o seu espaço de trabalho aparece na barra lateral com o rótulo de estado Desligado.

Inicie a sessão

10. Clique na linha do espaço de trabalho na barra lateral. O palco à direita mostra o painel de controlo do espaço de trabalho: uma etiqueta Desligado sob o nome, cartões para CPU, Memória, vCPUs, Disco e Tempo de atividade (na sua maioria traços e zeros antes do primeiro arranque — o disco é criado no primeiro início), um resumo de CONFIGURAÇÃO listando o seu agente e o modo de autenticação, os estados das Salvaguardas e da análise de Injeção de prompt, e as suas pastas partilhadas. Clique no botão Iniciar no canto superior direito.

11. No primeiro arranque, o Bromure cria o disco de sistema privado do espaço de trabalho como um clone copy-on-write da imagem base partilhada — isto é instantâneo e ocupa quase nenhum espaço em disco — e arranca a VM com 4 vCPUs e a RAM indicada no painel de controlo (dimensionada ao seu Mac por predefinição: 4, 6 ou 8 GB). Enquanto a VM arranca, uma sobreposição animada com o nome do espaço de trabalho e uma barra de progresso cobre o painel; ela esbate-se no momento em que o primeiro terminal do convidado aparece, normalmente em segundos. Se nenhum terminal aparecer em 30 segundos, a sobreposição muda para um painel MERGULHO FALHADO com os botões Continuar a aguardar e Repor imagem base… — consulte Resolução de problemas se isso acontecer.

12. Quando o arranque termina, está a olhar para um terminal no palco, e o agente primário — o Claude Code — já está a ser executado nele, pronto para um prompt. Nunca executa claude login dentro da VM; a autenticação foi tratada na fronteira de transmissão. Na barra lateral, o ponto de estado do espaço de trabalho está agora verde, o rótulo de estado indica Em execução, e o seu primeiro separador (rotulado com o programa em primeiro plano, por exemplo claude) está aninhado sob a linha do espaço de trabalho juntamente com um nó Docker. A barra de ferramentas da janela mostra agora um conjunto de controlos para esta VM: o seu endereço IP como uma etiqueta de clicar-para-copiar, e botões para navegar pelos ficheiros, reiniciar, inspecionar o rastreio, editar o espaço de trabalho, destacar a sessão para a sua própria janela e alternar os painéis do navegador e dos ficheiros do repositório.

Execute a sua primeira tarefa

13. Escreva uma tarefa no prompt do Claude Code, referenciando a pasta partilhada pelo seu caminho na VM. Por exemplo:

    Read the code in ~/my-project and summarize what it does.
    Then add a README.md with build instructions.
    

    Observe o ponto de estado no ícone do separador na barra lateral: pulsa a laranja enquanto o agente trabalha, fica verde quando o agente termina e fica vermelho quando o agente precisa da sua intervenção.

14. Como a pasta partilhada é uma montagem ativa, o README.md que o agente escreve está imediatamente no seu Mac — verifique-o no Finder, se quiser. Se a sua pasta for um repositório git, o painel do explorador de ficheiros do repositório abre-se automaticamente quando o diretório de trabalho do separador ativo entra no repositório, mostrando uma árvore ao estilo de IDE com o estado do git e diffs por ficheiro; também pode alterná-lo a qualquer momento com ⌃⌘E. Prima ⌘T para um separador de shell simples adicional junto ao agente — cada separador é uma janela da mesma sessão tmux na VM.

15. Tudo o resto que o agente faz — apt install, npm install, escrever ficheiros descartáveis na pasta pessoal da VM — permanece dentro do ambiente isolado. O disco de sistema e a pasta pessoal persistem entre sessões, e ambos podem ser repostos independentemente mais tarde (Espaços de trabalho).

Inspecione o rastreio

16. Prima ⇧⌘I (ou clique no botão Inspecionar rastreio da barra de ferramentas) para abrir o Inspetor de Rastreios. Os novos espaços de trabalho registam ao nível Detalhes do pedido de IA: cada pedido de rede que o agente fez é listado com anfitrião, estado e latência, e para anfitriões de LLM conhecidos os corpos completos do pedido e da resposta também são capturados. Selecione um dos pedidos à Anthropic e o inspetor renderiza-o como uma conversa — cabeçalho do fornecedor e do modelo com contagens de tokens, o prompt de sistema, e as mensagens do utilizador, do assistente e das ferramentas como balões de conversa.

17. Duas coisas a notar no seu primeiro rastreio. Primeira, o relatório de troca: o token de API falso que a VM contém foi trocado pela sua credencial real na transmissão, exatamente uma vez por pedido, delimitado ao anfitrião do fornecedor. Segunda, tudo o que é capturado permanece no seu Mac, encriptado em repouso. Os níveis de rastreio, os limites de retenção e os avisos de fuga são abordados em Rastreio.

Feche e retome

18. Feche a sessão: passe o cursor sobre a linha do espaço de trabalho na barra lateral e clique no seu botão × (ou prima ⌘W no seu último separador). Os novos espaços de trabalho têm a sua ação de fecho definida como Perguntar, pelo que aparece um pedido — "Fechar “O Meu Primeiro Projeto”?" — com os botões Executar em segundo plano, Suspender, Encerrar e Cancelar, e a explicação: "Executar em segundo plano mantém a VM em execução para que possa voltar a ligar-se mais tarde. Suspender guarda o seu estado no disco. Encerrar desliga-a."

19. Clique em Suspender. A RAM da VM é capturada num instantâneo para o disco e o rótulo de estado da linha na barra lateral muda para Suspenso. Nada se perde — nem a conversa do agente, nem o histórico da sua shell, nem a disposição dos separadores.

20. Retomar: clique no espaço de trabalho e prima Retomar no seu painel de controlo (ou utilize o menu ⋯ da linha → Retomar). A sessão restaura-se quase instantaneamente, exatamente onde a deixou — os mesmos terminais, com o Claude Code a meio de uma conversa.

21. Se pretender sempre o mesmo comportamento ao fechar, abra o menu ⋯ da linha → Editar… e defina Ao fechar a janela no painel Geral como Suspender (ou Executar em segundo plano / Encerrar) para que o pedido nunca apareça. Consulte Definições — Geral.

Dica: Um espaço de trabalho suspenso ou encerrado mantém o seu disco de sistema e a sua pasta pessoal. Destruir dados é sempre um ato explícito — Repor disco, Apagar pasta pessoal… ou Eliminar espaço de trabalho — e mesmo eliminar um espaço de trabalho nunca toca nas pastas do anfitrião que partilhou com ele.

Para onde ir a seguir

• Conceitos — o modelo mental por trás do que acabou de fazer: espaços de trabalho, o ciclo de vida da VM, a fronteira de transmissão e como as peças se encaixam.
• Espaços de trabalho — duplicar, repor e eliminar espaços de trabalho; camadas de armazenamento, pontos de verificação e o modelo de preferências a partir do qual cada novo espaço de trabalho é derivado.
• Sessões — separadores e worktrees do git, a Grelha de terminais, o painel do navegador agêntico, a transferência de ficheiros para dentro e para fora da VM, e todos os atalhos de teclado.
• Referência de definições — cada painel de definições, uma página cada, incluindo Agentes e Pastas deste passo a passo.
• Credenciais — o catálogo completo de credenciais (tokens git, chaves SSH, AWS, Kubernetes, registos de contentores, bases de dados e mais), pedidos de aprovação, e como a troca de falso-para-real funciona em detalhe.
• Rastreio — níveis de rastreio, o Inspetor de Rastreios e a deteção de fugas.
• Cadeia de fornecimento e Injeção de prompt — as proteções que pode acrescentar em camadas a um espaço de trabalho antes de apontar um agente a código não confiável.
• Fusion e Modelos locais — responder a prompts com vários modelos ao mesmo tempo, e executar modelos no seu Mac em vez da nuvem.
• Automatização e CLI — controlar espaços de trabalho a partir de scripts, a API HTTP, e o servidor bromure-cli mcp.