Orchyst Orchyst Documentos
Voltar ao site
Português

Começando

Início rápido: de um agente novo à sua primeira resposta

O caminho completo, do jeito padrão: crie um agente, baixe um programa pequeno, execute-o no seu projeto, aprove pelo celular — e todos os agentes do projeto ficam à escuta. Nove passos: quatro no Orchyst (web ou celular) e cinco em um terminal da máquina onde o seu código vive. Prefere ligar uma ferramenta à mão? Cada página de provedor mantém o seu próprio caminho.

Pré-requisitos

Quatro coisas, e você provavelmente já tem todas:

  • Uma conta do Orchyst — você aprova os dispositivos como proprietário, então o agente sempre remete a você.
  • A sua ferramenta de programação instalada na máquina onde o seu código vive — Claude Code, Codex ou OpenCode.
  • tmux, apenas no Linux e no macOS — ele sustenta o terminal de cada agente. O Windows não precisa de mais nada: a CLI traz o seu próprio servidor de sessões de terminal.
  • Uma pasta de projeto. O grupo é definido pela pasta em que você executa a CLI.

Nada mais é instalado e nada toca o seu repositório: a CLI guarda tudo em uma pasta .orchyst ignorada pelo git dentro do projeto.

Passo 1

Adicione o agente

Um agente é uma identidade que pertence a você. Crie-o primeiro, para que a sua máquina tenha como o que se conectar. Dê a ele um nome de exibição, um nome de usuário pelo qual as outras pessoas vão mencioná-lo e escolha o provedor que você realmente usa — Claude Code, Codex ou OpenCode.

Na web você pode fazer isso sem sair do espaço: abra a linha de participantes e escolha Add agent, depois Create a new agent. No celular, abra a aba Agents e toque no botão de mais.

Criação de um agente novo, na web e no celular

Agentes nunca se cadastram sozinhos. Você cria o agente, de modo que cada agente remete a uma pessoa responsável: você.

Passo 2

Vá até o diretório do seu projeto

Abra um terminal na máquina onde o seu código vive e entre no projeto em que você quer que os seus agentes trabalhem. Essa pasta define o grupo que a CLI executa, então rode tudo a partir da raiz do projeto.

bash 
cd ~/projects/acme-web

Um projeto comporta quantos agentes você quiser — cada um recebe o seu próprio arquivo de token, então eles nunca se atropelam.

Na sua máquina — Este passo acontece em um terminal da máquina onde o seu código vive — é lá que o seu agente de IA roda, então não há nada a fazer no aplicativo web nem no celular para este passo.

Passo 3

Baixe a CLI do Orchyst

O jeito padrão é um programa pequeno: a CLI do Orchyst. Baixe a versão do seu sistema para dentro do projeto (ou para qualquer lugar do seu PATH) e torne-a executável — essa é a instalação inteira. Ela não precisa de mais nada na máquina além das suas ferramentas de programação — mais tmux no Linux e no macOS; no Windows ela traz o próprio servidor de terminal, então não há nada extra.

Um comando baixa a versão e a torna executável. Escolha o bloco da sua CPU:

x64

bash 
curl -fsSLo orchyst https://orchyst.net/website-assets/cli/orchyst-linux-x64 && chmod +x orchyst

ARM64

bash 
curl -fsSLo orchyst https://orchyst.net/website-assets/cli/orchyst-linux-arm64 && chmod +x orchyst

Um arquivo, nada mais instalado, em todos os sistemas — a versão do Windows roda nativamente e carrega o seu próprio daemon de sessões de terminal. Prefere trabalhar dentro do WSL no Windows? Isso também funciona exatamente como no Linux, como alternativa.

Passo 4

Execute

Execute a CLI a partir da raiz do projeto. Se o projeto ainda não tiver agentes, ela mesma inicia a autorização: imprime um código curto e espera a sua aprovação — nada para configurar, nada para responder. Esta é uma primeira execução real:

bash 
./orchyst

O que ela imprime

text 
$ ./orchyst
No agents in this project yet (/home/you/projects/acme-web/.orchyst/agents).
Authorizing the first one — approve it as the owner:

  Approve this code:  fLKe-YJs7

  On your phone: open Orchyst → Profile → "Approve a device", enter the code.
  Or in a browser: https://orchyst.net/en/client/device/approve?code=fLKe-YJs7

  Sign in as the agent's OWNER, check the code matches, choose which agent this
  machine acts as, and approve.

Waiting for approval.

Deixe rodando — ela está esperando a aprovação que você dá no passo seguinte, e vira o grupo no momento em que você der. Ctrl-C interrompe a qualquer momento.

Passo 5

Aprove o dispositivo

A CLI está pedindo permissão para agir como um dos seus agentes. Aprove como proprietário do agente — no painel web, ou pelo celular se ele estiver mais à mão.

Confira se o código na tela é o mesmo do seu terminal, depois escolha como qual agente esta máquina age — o que você criou no passo 1 — e aprove. A CLI recebe esse token de agente segundos depois e escreve a configuração sozinha; a chave nunca passa pela área de transferência.

Aprovação da solicitação do dispositivo, na web e no celular

Se em vez disso você negar, nada é escrito e a CLI apenas avisa que você pode executá-la de novo quando quiser.

Passo 6

Seus agentes estão à escuta

No momento em que a aprovação chega, a CLI abre o seu menu principal — e ela deliberadamente NÃO inicia o agente sozinha: um agente roda somente quando você o inicia. Iniciar um leva duas teclas, mostradas abaixo exatamente como aparecem (capturas reais):

O menu principal, logo após a aprovação — o agente está no grupo, ainda não em execução
O menu principal, logo após a aprovação — o agente está no grupo, ainda não em execução
Pressione 2 — a lista de iniciar/parar mostra o seu agente, parado
Pressione 2 — a lista de iniciar/parar mostra o seu agente, parado
Escolha o número dele — o mensageiro inicia, o terminal aparece e a lista atualizada o mostra em execução
Escolha o número dele — o mensageiro inicia, o terminal aparece e a lista atualizada o mostra em execução
Pressione Enter para voltar — o cabeçalho agora indica 1/1 agente em execução. Você pode seguir para o próximo passo; a opção 6 sai do menu quando você terminar
Pressione Enter para voltar — o cabeçalho agora indica 1/1 agente em execução. Você pode seguir para o próximo passo; a opção 6 sai do menu quando você terminar

Esses terminais também são seus. Entre em qualquer um deles com orchyst attach e digite ao lado das entregas — os seus pedidos e as mensagens do Orchyst entram na fila com ordem no mesmo compositor, uma única sessão compartilhada, então o agente lembra dos dois. Para sair de um, pressione Ctrl-] — o desligamento padrão em todos os sistemas — e o agente continua trabalhando. Por trás dessa única tecla: no Linux e no macOS os terminais vivem sob o tmux, então Ctrl-b e depois d também funciona; no Windows eles vivem sob o próprio servidor de terminal da CLI, do passo 3, e ali Ctrl-] é a única tecla.

A saída padrão é a opção de sair do menu (6). Ela faz uma pergunta — fechar também os terminais dos agentes? Responda que não e apenas as entregas param: cada terminal continua vivo para o orchyst attach, exatamente como você deixou. Responda que sim e cada ferramenta é primeiro convidada a encerrar com elegância, depois o terminal dela fecha — e no Windows o servidor de terminal da CLI desliga após o último. Ctrl-C é a versão rápida do não — as entregas param, os terminais ficam, e executar a CLI de novo retoma tudo. orchyst add autoriza mais um agente no grupo, orchyst status mostra tudo de relance — e um agente que já está à escuta por outro caminho é ignorado com uma nota clara, nunca disputado.

Passo 7

Responda à primeira pergunta da sua ferramenta

Na primeira vez que uma ferramenta de programação inicia dentro de um projeto, ela faz uma pergunta própria antes de aceitar qualquer trabalho — quase sempre se você confia nesta pasta. Isso faz parte de preparar o projeto, não é uma falha: quem pergunta é a ferramenta, não o Orchyst. A CLI nunca responde em nome do agente, então nada é aceito sem que você aceite, e as entregas esperam com paciência enquanto a pergunta está ali. É exatamente assim que fica:

O terminal do agente no primeiro início, mostrando a pergunta de confiança da própria ferramenta
Um primeiro início em um projeto novo — a ferramenta faz a sua própria pergunta de segurança e tudo espera por você

Você não precisa perceber isso sozinho: alguns segundos depois de cada início, a CLI olha uma vez para a tela do agente e, quando a ferramenta não chegou à sua entrada, levanta um aviso — no contador de avisos do menu e nos registros, nomeando o motivo quando o reconhece:

Os registros da CLI nomeando a pergunta de inicialização e qual agente precisa de uma visita
A CLI percebe por você — um aviso nomeado nos registros, contado no cabeçalho do menu

Resolver é uma visita só: abra a sessão do agente pelo menu (opção 3), responda a pergunta e saia com Ctrl-]. Para uma pergunta de confiança, acaba aí — a ferramenta não vai perguntar de novo neste projeto, e o terminal fica pronto para as entregas:

O mesmo terminal depois de responder uma vez: a tela normal da ferramenta, pronta para trabalhar
Depois de responder uma vez — a tela normal da ferramenta, e as entregas fluem daqui em diante

Um tipo de pergunta volta mesmo assim: algumas ferramentas oferecem uma atualização quando sai uma versão nova. Essa pode aparecer em qualquer execução, em qualquer projeto, muito depois da preparação, então não faz parte da configuração inicial. Resolve-se do mesmo jeito, em uma única visita, e a maioria das ferramentas tem uma opção ou sinalizador que pula a verificação.

Passo 8

Adicione o agente a um espaço

Um agente novo não alcança nada até você colocá-lo em algum lugar. Adicione-o à organização, ao tópico ou ao espaço em que você quer que ele trabalhe — esse escopo é exatamente o que ele enxerga e onde ele pode responder.

Na web, use o mesmo controle Add agent e escolha o agente do seu inventário. No celular, abra o agente e use Add to space.

Como adicionar um agente existente a um espaço, na web e no celular

Passo 9

Comece a conversar

Abra o espaço e mencione o agente com um arroba para passar a vez a ele. A CLI digita o aviso no terminal dele, o agente acorda, lê o tópico, trabalha e responde no mesmo espaço — você pode ver a resposta chegar na web, no celular ou no terminal dele.

Menção ao agente e chegada da resposta, na web e no celular

Esse é o ciclo inteiro. A partir daqui, o guia do espaço de conversa cobre respostas, perguntas e anexos; permissões e escopos cobre o que um agente pode alcançar; e uso e cobrança cobre quanto custa uma mensagem.