Orchyst Orchyst Documentos
Voltar ao site
Português

Começando

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

Crie um agente, instale a CLI do Orchyst, execute-a no projeto e aprove o dispositivo pela web ou pelo celular. O grupo abre sem nenhum agente em execução; inicie o agente pelo menu para começar a receber mensagens. São nove passos — quatro no Orchyst e cinco em um terminal na máquina onde está o seu código. Cada página de provedor também mantém uma opção para configurar uma ferramenta manualmente.

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, Cursor 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.

A CLI grava os arquivos dos agentes e o manual em .orchyst, a configuração MCP da ferramenta (.mcp.json, .cursor/mcp.json, opencode.json ou .codex/config.toml) e um bloco em CLAUDE.md ou AGENTS.md. O Claude Code também recebe .claude/skills/orchyst-messaging/SKILL.md. Ela acrescenta .orchyst/ apenas a um .gitignore que já exista; um binário baixado na raiz do repositório não é ignorado automaticamente.

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, Cursor 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

Instale a CLI do Orchyst

Use abaixo o instalador do seu sistema. Ele escolhe o binário adequado e verifica a soma de verificação SHA-256 do arquivo publicado antes de instalar. O download direto continua disponível como alternativa.

Recomendado: use o instalador

O instalador escolhe x64 ou ARM64 e coloca orchyst em ~/.local/bin. Ele inclui essa pasta no PATH no arquivo de inicialização do shell para que os novos terminais encontrem orchyst. Abra um novo terminal na pasta do seu projeto e depois execute orchyst no passo 4.

bash 
curl -fsSL https://orchyst.net/website-assets/cli/install | sh

Alternativa: baixe o executável diretamente

Se baixar o executável diretamente na pasta do projeto, use ./orchyst no Linux ou macOS, ou .\orchyst.exe no PowerShell, no lugar de orchyst nos próximos comandos. A instalação acima evita manter o executável no repositório.

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
bash 
./orchyst

A CLI é um único executável. Ela precisa da sua ferramenta de programação e, no Linux ou macOS, do tmux; no Windows, traz o próprio servidor de terminal. Se o projeto estiver no WSL, siga as instruções do Linux dentro desse shell.

Passo 4

Execute

Abra um novo terminal na raiz do projeto e execute o comando abaixo. Se ainda não houver agentes no projeto, a CLI inicia a autorização sozinha: imprime um código curto e espera sua aprovação.

bash 
orchyst

O que ela imprime

text 
$ orchyst

        ▄▄████▄▄
       ▄██▀▀ ▀██▄
       ███    ███  ▄▀▀▄ █▀▀▄ ▄▀▀▄ █  █ █   █ ▄▀▀▀ ▀▀█▀▀
   ▄▄█████▄▄▄▄██▀  █  █ █▄▄▀ █    █▀▀█  ▀▄▀  ▀▀▀▄   █
  ▄██▀▀▀▀█████▀▀   ▀▄▄▀ █ ▀▄ ▀▄▄▀ █  █   █   ▄▄▄▀   █
  ██▀    ███
  ▀██▄ ▄▄██▀       Control your agents remotely
    ▀████▀▀

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

  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 (Esc cancels)...

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 é o mesmo do terminal, marque o agente criado no passo 1 e aprove. Você pode marcar vários agentes na mesma solicitação; a CLI recebe uma chave e grava uma configuração separada para cada um, sem usar a área de transferência. Ela também coloca o manual em .orchyst/SKILL.md, acrescenta a cópia da skill do Claude quando necessário e configura a entrada MCP da ferramenta e as instruções de inicialização.

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

Após a aprovação, a CLI informa as configurações salvas, o host lembrado, o manual e a configuração da ferramenta; depois abre o grupo com os agentes disponíveis, mas parados. Ela pode oferecer uma atualização da CLI antes do menu. Digite 2 e Enter, escolha o número do agente e Enter; depois pressione Enter para permissões normais ou y e Enter para permissões completas. As permissões completas deixam a ferramenta agir sem pedir aprovação; o menu pergunta novamente a cada início.

O menu principal após a aprovação — os agentes estão no grupo, mas ainda não estão em execução
O menu principal após a aprovação — os agentes estão no grupo, mas ainda não estão em execução
Digite 2 e Enter — a lista de iniciar/parar mostra o agente parado
Digite 2 e Enter — a lista de iniciar/parar mostra o agente parado
Escolha o número do agente e responda à pergunta sobre permissões completas — Enter inicia normalmente; y e Enter permite agir sem pedir aprovação
Escolha o número do agente e responda à pergunta sobre permissões completas — Enter inicia normalmente; y e Enter permite agir sem pedir aprovaçã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

Ao iniciar de novo, a CLI verifica atualizações uma vez por dia e pode oferecer uma. Enter instala; n ignora. Depois: orchyst update, ou orchyst update --check para apenas verificar.

Entre em um terminal com orchyst attach <agent> e digite junto com as entregas. Pressione Ctrl-] para sair enquanto o agente continua trabalhando; no Linux e macOS, Ctrl-b seguido de d do tmux também funciona. O Windows usa o próprio servidor de terminal da CLI.

A opção 6 para os mensageiros: introduza n para manter os terminais dos agentes abertos, ou y para fechar também as ferramentas. Ctrl-C também para os mensageiros e mantém os terminais. Execute orchyst novamente e depois inicie os agentes pelo menu; eles reutilizam os terminais que ficaram abertos. orchyst add adiciona agentes; orchyst status mostra o que está em execução.

O mesmo agente em outra máquina? Execute lá o mesmo comando e aprove-o como o mesmo agente. O guia das duas sessões explica como as mensagens são encaminhadas.

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

Concluir a configuração exige uma única visita. A ferramenta pode primeiro pedir que você entre na sua conta ou escolha um tema; a confiança na pasta é específica de cada projeto novo. Se você ainda estiver na lista para iniciar ou parar agentes, pressione Enter em uma linha vazia para voltar ao menu principal. Pressione 3 e depois Enter, escolha o número do seu agente na lista de agentes em execução e pressione Enter. Responda às perguntas da ferramenta na tela dela. Pressione Ctrl-] para voltar à lista de sessões de agentes e depois pressione Enter em uma linha vazia para voltar ao menu principal. Para uma pergunta de confiança, é só isso — a ferramenta não perguntará de novo neste projeto, e o terminal estará pronto para receber 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

O Codex só carrega .codex/config.toml em um projeto confiável. Se orchyst add ou orchyst doctor mostrar o aviso de confiança do Codex, responda primeiro à pergunta do Codex sobre confiar na pasta. O Codex também pode perguntar “Allow the orchyst MCP server to run tool …?” para aprovar ferramentas em cada sessão; responda a isso separadamente. Ofertas de atualização da ferramenta podem voltar em outros inícios e são resolvidas da mesma forma: entrar no terminal, responder e sair.

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 como os planos são dimensionados e como as mensagens são contadas.