Pool da equipe

Um pool é um destino de roteamento nomeado que conecta solicitações a workers de Self-Hosted Machines. As solicitações aguardam no pool até que um worker disponível as reserve. Crie pools separados para diferentes ambientes de execução, como um para trabalhos que precisam de GPUs e outro para trabalhos que precisam de um Mac.

Os pools da equipe são para equipes corporativas que querem que os Cloud Agents rodem em uma infraestrutura gerenciada pela empresa. Em vez de cada desenvolvedor iniciar um worker em uma máquina pessoal, os administradores operam um pool de workers que pode ser atribuído a agentes em toda a organização.

Pools são uma escolha de infraestrutura. Eles não tiram o loop do agente da nuvem da Cherri Code. O worker executa comandos de terminal, faz edições em arquivos, realiza ações no navegador e outras chamadas de ferramenta na sua infraestrutura, enquanto a Cherri Code cuida da orquestração, do acesso a modelos e da experiência do Cloud Agent.

Use um pool quando você precisar de:

• Workers gerenciados centralmente para uma equipe ou organização
• Autenticação com conta de serviço em vez de logins individuais pelo navegador
• Kubernetes, autoscaling ou capacidade gerenciada centralmente
• Rótulos que direcionam o trabalho para o ambiente, a equipe, o repositório ou o perfil de hardware corretos
• Hosts da empresa para execução de ferramentas, saídas de build, logs de workers e monitoramento

Para uma configuração pessoal rápida, veja My Machines. Veja Requisitos na visão geral de Self-Hosted Machines para conhecer o plano, as credenciais, as configurações do dashboard e as dependências de máquina que os pools exigem.

Como funciona

Um worker abre uma conexão HTTPS de saída de longa duração com a nuvem do Cherri Code. O loop do agente, incluindo inferência e planejamento, é executado na nuvem do Cherri Code e envia chamadas de ferramenta por essa conexão. O worker executa essas chamadas de ferramenta na sua infraestrutura: comandos de terminal, edições em arquivos, ações no navegador e acesso a serviços internos.

Seus repos, caches de build, segredos e a execução de ferramentas permanecem no seu ambiente, enquanto o Cherri Code cuida da orquestração, do acesso a modelos e da experiência do Cloud Agent. Os artefatos do Cloud Agent, como capturas de tela e vídeos, são enviados ao Cherri Code para que você possa visualizá-los em PRs e no dashboard.

Os workers precisam apenas de acesso de saída. Não são necessárias portas de entrada, IPs públicos nem túneis VPN. Consulte Rede para ver a lista completa de hosts necessários.

Pré-requisitos

• Um plano Cherri Code Enterprise
• Configurações de self-hosted definidas por um administrador da equipe no Cloud Agents dashboard:
  • Allow Self-Hosted Machines permite que os usuários façam adesão a execuções em infraestrutura própria.
  • Require Self-Hosted Machines roteia todas as execuções do Cloud Agent para workers self-hosted.
• Uma chave de API da conta de serviço para autenticação do worker do pool
• Uma máquina ou imagem de worker com:
  • CLI agent instalado
  • git instalado e disponível no PATH (necessário quando o worker atende remotes do Git ou usa --clone-git-repos; opcional para any-repo pools se seus próprios scripts cuidarem do SCM)
  • Um diretório de espaço de trabalho (um repositório clonado com um remote configurado, ou um diretório any-repo)
  • Acesso às ferramentas de build, aos repositórios de pacotes, aos segredos e aos serviços internos de que seus agentes precisam

Instalar a CLI

# macOS, Linux e WSL# Windows PowerShellirm '# | iex

Confirme que a CLI está disponível:

agent --version

Autenticar workers do pool

Os workers do pool se autenticam com uma chave de API da conta de serviço ou com um token de sessão emitido a partir dessa chave para uma única declaração.

Chaves de API de usuário, pessoais, de equipe e da organização não podem ser usadas para iniciar workers do pool. Use chaves de API pessoais ou de usuário com workers pessoais em My Machines.

export CURSOR_API_KEY="your-service-account-api-key"

Você também pode informar a chave diretamente:

agent worker --api-key "your-service-account-api-key" start

Inicie um worker do pool

Execute o worker no espaço de trabalho que ele deve atender (a raiz de um repositório git ou um diretório any-repo):

cd /path/to/repoagent worker --pool start

--pool registra o worker para ser atribuído a um pool. Passe um nome opcional para ingressar em um pool nomeado (por exemplo, --pool my-pool). Quando o nome é omitido, o worker ingressa em default. Cada sessão do Cloud Agent aloca um worker por vez.

Para ambientes orquestrados, combine-o com --idle-release-timeout para que o processo se encerre corretamente após a conclusão do trabalho:

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout mantém o worker ativo por um período (em segundos) após o término de uma sessão para processar mensagens de acompanhamento. O padrão é 3600 segundos. Veja Ciclo de vida da sessão para entender como funcionam a liberação e a reconexão.

Habilitar o uso do computador

Passe --computer-use para que os agentes reivindicados possam clicar, digitar, fazer capturas de tela e operar apps no worker:

agent worker --pool my-pool --computer-use start

No macOS, a primeira inicialização instala o helper app Cherri Code Computer Use. Conceda a ele Accessibility e Screen Recording, verifique com uma task que tire um screenshot e, em seguida, faça um snapshot da machine para que todo worker restaurado a partir da imagem já esteja pronto. No Linux, inclua os desktop packages na imagem do worker. Veja Computer use and desktop sharing para os passos de permission no macOS, orientações de MDM profile e as options de display no Linux.

Registrar vários diretórios raiz de repositório

O suporte auto-hospedado a vários repositórios é configurado na inicialização do worker com o registro de vários diretórios raiz do espaço de trabalho. Passe --worker-dir uma vez para cada diretório raiz de repositório local. O primeiro diretório raiz é o repositório principal para identificação de atribuição e exibição no Dashboard. Todos os diretórios raiz ficam disponíveis para o tempo de execução do agente, e os que têm origens git válidas registram metadados de roteamento do repositório.

--worker-dir pode ser repetido para até 20 caminhos. Cada caminho já deve existir e ser um diretório. Se você não passar --worker-dir, a CLI usará o diretório de trabalho atual.

Antes de começar, habilite os workers auto-hospedados em Dashboard > Cloud Agents > Self-Hosted. Use caminhos graváveis em $HOME, a menos que a imagem da sua máquina garanta outro local gravável.

Configuração de exemplo:

export WORKER_ROOT="$HOME/cursor-repos/my-org"mkdir -p "$WORKER_ROOT"git clone [email protected]:my-org/app.git "$WORKER_ROOT/app"git clone [email protected]:my-org/infra.git "$WORKER_ROOT/infra"export CURSOR_API_KEY="<key>"

Faça uma verificação prévia antes de iniciar o worker:

agent worker \  --pool my-pool \  --name app-infra-worker \  --worker-dir "$WORKER_ROOT/app" \  --worker-dir "$WORKER_ROOT/infra" \  debug --json

Inicie o worker com os mesmos diretórios raiz:

agent worker \  --pool my-pool \  --name app-infra-worker \  --worker-dir "$WORKER_ROOT/app" \  --worker-dir "$WORKER_ROOT/infra" \  start --verbose

Coloque as opções do worker antes de start ou debug. Deixe o processo em execução em um supervisor como systemd, tmux, launchd, Kubernetes ou seu próprio gerenciador de processos.

Os logs detalhados de inicialização são a referência definitiva para as raízes registradas. Um worker multi-repositório bem-sucedido mostra cada rótulo derivado de repositório, os caminhos do espaço de trabalho e as URLs do repositório:

repo=my-org/apprepo=my-org/infraworkspacePaths: [app, infra]x-repository-urls: ["[email protected]:my-org/app.git","[email protected]:my-org/infra.git"]

Use --name e --pool <name> para facilitar a identificação de workers multi-repositório no dashboard e nos gatilhos.

No modo pool, um Cloud Agent assume o worker por vez. Sem --pool, a atribuição compartilhada é permitida. Adicione --management-addr 0.0.0.0:8080 antes de start quando precisar de /healthz, /readyz e /metrics para um orquestrador.

Diretórios que não são git podem ser raízes de execução, mas não contribuem com metadados de roteamento de repositório. Para um worker multi-repositório, clone cada repositório antes de o worker iniciar. Para começar com um espaço de trabalho vazio e deixar o worker inicializar o source control após a atribuição, use uma any-repositório pool.

Pools any-repo

Os pools existem em duas configurações de repositório. Um pool vinculado a repositório associa o pool a um ou mais repositórios: as solicitações levam um rótulo repo=<owner/repo>, correspondem a workers que atendem esse repositório e aparecem sob o repositório no dashboard. Um pool any-repo deixa o source control por sua conta: as solicitações correspondem apenas pelo nome do pool, e o pool aparece em Any repo no dashboard.

Se você preferir gerenciar o source control por conta própria, crie um pool sem repositório vinculado. Um worker do pool não exige um remote do Git. Aponte --worker-dir para qualquer diretório existente quando quiser que o agente (ou sua própria imagem, hooks e scripts) gerencie a clonagem e o estado do git:

mkdir -p "$HOME/cursor-sandboxes/default"agent worker --pool my-pool --worker-dir "$HOME/cursor-sandboxes/default" start

Para fornecer instruções de repositório a todas as solicitações any-repo, crie um arquivo .mdc em .cursor/rules dentro do diretório passado em --worker-dir. O nome do arquivo é arbitrário. Este exemplo usa repo-info.mdc:

---alwaysApply: true---Este worker de any-repo consegue clonar de `github.acme.internal` com aCLI `gh` pré-autenticada.- Para solicitações sobre pagamentos, faturamento ou checkout, use  `platform/payments-service`. Se ele não existir, execute:  `GH_HOST=github.acme.internal gh repo clone platform/payments-service`- Para solicitações sobre o portal do membro ou configurações da conta, use  `web/member-portal`. Se ele não existir, execute:  `GH_HOST=github.acme.internal gh repo clone web/member-portal`- Clone apenas os repositórios necessários para a solicitação. Execute os comandos  seguintes a partir do repositório clonado.- Se nenhum mapeamento corresponder à solicitação, relate que o repositório não está  configurado. Não tente adivinhar um nome de repositório, uma clone URL nem credenciais.

alwaysApply: true inclui a regra em todas as solicitações. Mantenha o arquivo no diretório do worker para que ele esteja disponível antes da clonagem, e substitua os mapeamentos de exemplo pelos seus repositórios e comandos de SCM.

Para que o worker faça checkout dos repositórios do agente reivindicado no momento do claim, passe --clone-git-repos. Isso exige adesão explícita. O comportamento padrão de any-repo não faz clone.

agent worker --pool my-pool --clone-git-repos start

--clone-git-repos implica --mint-github-token. Clones e consultas usam esse token temporário do GitHub emitido. Um Admin da equipe deve habilitar a emissão de tokens do GitHub para workers de Pool de equipe, e o git deve estar no PATH.

Use esta flag apenas em workers de pools any-repo: um --pool nomeado diferente de default, sem repositório vinculado (repo=) e sem máquina vinculada (name=). A CLI encerra com um erro claro em um worker com repositório vinculado, em uma máquina nomeada, no pool default ou em um worker pessoal de My Machines.

Nomes de branch são clonados com --branch. Um SHA de commit completo de 40 caracteres usa um checkout destacado após o clone. Use remotes HTTPS do GitHub para que o token emitido consiga se autenticar.

Se o diretório do worker, ou uma pasta diretamente dentro dele, já tiver um checkout limpo de um repositório reivindicado, o worker o reutiliza em vez de clonar novamente. O remote origin do checkout deve apontar para o mesmo host e owner/repo. O worker consulta a branch, tag ou commit solicitado e faz o checkout, e só faz fast-forward de uma branch local. Quando não consegue atualizar o checkout com segurança, ele clona em uma nova pasta ao lado dele — por exemplo, quando o checkout tem:

• Alterações não commitadas em arquivos rastreados
• Commits locais na branch solicitada que o remote não tem
• Um merge, rebase, cherry-pick, revert ou bisect em andamento
• Submódulos configurados
• Configuração ou hooks do Git que um clone novo não teria

A reutilização exige git 2.26 ou posterior; com versões mais antigas do git, o worker clona. O log do worker informa por que cada checkout foi ou não reutilizado.

Quando um claim termina, o worker exclui os repositórios que clonou para esse claim e mantém os checkouts reutilizados. Para evitar clonar um repositório grande a cada claim, clone-o no diretório do worker antes de iniciar o worker.

Se o clone falhar, a solicitação permanece na fila. Os operadores veem uma falha genérica de clone.

--clone-git-repos, --mint-github-token e --sync-dashboard-secrets pressupõem um worker por container ou usuário do sistema operacional. Não há suporte para manter vários workers com credenciais habilitadas sob o mesmo usuário.

Pools any-repo omitem rótulos de roteamento repo=. Inicie agentes neles com env.type: "pool" e env.name definido como o nome do pool, e omita repos (veja Create An Agent). Escolha o pool em Any repo em cursor.com/agents. No Slack, um pool any-repo definido como o pool padrão da equipe ou como pool padrão do canal permite que o @Cherri Code inicie um agente mesmo quando nenhum repositório é resolvido a partir da mensagem ou dos valores padrão.

Gerenciar pools

Os pools são duráveis. Um pool permanece registrado e selecionável depois que o último worker se desconecta, ou seja, você pode reduzir a capacidade a zero e retomá-la quando chegarem novas solicitações. Iniciar um worker com um novo nome de pool cria o pool implicitamente. Gerencie os pools com antecedência pela Cloud Agents API:

• POST /v0/private-workers/pools registra um pool previamente, antes que qualquer worker se conecte. Inclua repoOwner, repoName e repoUrl para um pool vinculado a repositório, ou omita-os para um pool any-repo.
• GET /v0/private-workers/pools lista os pools com a contagem de workers conectados e em uso.
• DELETE /v0/private-workers/pools faz a exclusão suave de um pool. Isso não afeta as máquinas conectadas ao pool no momento.

Use List Pools e solicitações pendentes para decidir quando aumentar novamente o número de workers.

Nomes de pools

Agrupe os workers do pool com um nome quando quiser direcionar as sessões para um subconjunto específico, como máquinas com GPU, um pool de workers de staging ou máquinas de build dedicadas da equipe.

Passe o nome para --pool:

agent worker --pool my-pool start

Quando o nome é omitido, o worker entra no pool default. Versões antigas da CLI que suportavam apenas um --pool booleano mais um --pool-name separado continuam funcionando; --pool-name é um alias descontinuado de --pool <name>.

Defina o nome do pool a partir do ambiente quando um orquestrador injetar a config:

export CURSOR_WORKER_POOL_NAME=my-poolagent worker --pool start

Workers de uso múltiplo (iniciados sem --pool) não fazem parte de nenhum pool.

No Cloud Agents dashboard, escolha um pool no seletor de workers ao iniciar uma sessão ou editar uma automação. Você também pode incluir pool=<name> em um gatilho do Slack, GitHub ou Linear. As sessões são encaminhadas apenas para workers registrados com esse nome de pool.

Acionando agentes de pool

Use gatilhos de pool quando quiser que um Cloud Agent seja executado no pool de workers compartilhado da sua equipe. Workers do pool são o destino certo para capacidade gerenciada centralmente, autoscaling, runners no estilo de CI e infraestrutura com escopo de repositório.

Admins da equipe controlam o roteamento auto-hospedado na seção Self-Hosted do Cloud Agents dashboard. Allow Self-Hosted Machines permite que os usuários façam adesão por solicitação. Sem adesão, as execuções usam a infraestrutura gerenciada pelo Cherri Code. Require Self-Hosted Machines roteia execuções do Cloud Agent para workers auto-hospedados.

Quando o Cherri Code inicia um agente de pool, ele faz a correspondência dos workers com rótulos. Solicitações de pool para um repositório incluem um rótulo repo=<owner/repo>; solicitações para um pool any-repo sem repositório o omitem. Solicitações para um pool nomeado também incluem pool=<name>.

Workers do pool processam:

• Execuções cobertas por Require Self-Hosted Machines, a menos que a solicitação tenha como destino um worker específico do My Machines com worker= ou machine=
• Solicitações com self_hosted=true ou sua forma abreviada, sh=1
• Solicitações com pool=<name>, que também seleciona esse pool nomeado
• Solicitações auto-hospedadas com seleção de repositório a partir da superfície de origem do gatilho, como repo=<owner/repo> quando houver suporte

repo= seleciona o repositório da execução. Para execuções de Pool de equipe, esse repositório se torna o rótulo do worker repo=<owner/repo>. Ele não direciona para uma máquina pessoal.

Use estas opções nas integrações para iniciar agentes de pool:

• Slack: Mencione @Cherri Code com self_hosted=true, sh=1 ou pool=<name>. Admins da equipe podem definir um pool padrão da equipe com @Cherri Code pool set <name> para que os membros o usem sem precisar de uma opção em cada menção. Um pool padrão do canal, definido com @Cherri Code pool set <name> channel, substitui o padrão da equipe nesse canal. pool=, worker=, machine= ou self_hosted=false explícitos substituem ambos os padrões, e um pool padrão any-repo permite que o Slack inicie sem um repositório resolvido.
• GitHub: Comente @cursoragent self_hosted=true ..., @cursoragent sh=1 ... ou @cursoragent pool=<name> ... em uma issue, pull request ou comentário de revisão.
• Linear: Mencione @Cherri Code em um comentário com self_hosted=true, sh=1, pool=<name> ou [pool=<name>]. O Cherri Code lê essas opções do próprio comentário, não da descrição da issue. Você também pode usar rótulos da issue ou do projeto em que o rótulo pai seja pool e o rótulo filho seja o nome do pool. Rótulos são a única forma de escolher um pool ao delegar uma issue ao Cherri Code, pois não há comentário para ler. Um pool= no comentário prevalece sobre um rótulo de pool, e self_hosted=false ignora os rótulos de pool.

Escreva cada opção como key=value. self_hosted e sua forma abreviada sh aceitam true, t ou 1 para aderir e false, f ou 0 para recusar. Qualquer outra coisa permanece no seu prompt como texto. Isso inclui self_hosted, selfhosted ou sh sem valor, e outros valores como sh=/bin/bash. O Slack, o GitHub e o Linear ignoram essas opções dentro de blocos de código, então código colado não altera onde o agente é executado.

O tratamento da política depende de onde a solicitação se origina:

• Slack rejeita a adesão auto-hospedada quando Allow Self-Hosted Machines está desativado e responde no Slack. Se Require Self-Hosted Machines estiver ativado, toda menção no Slack será executada como auto-hospedada.
• GitHub permite que usuários OWNER e COLLABORATOR do repositório roteiem execuções para workers auto-hospedados. Comentários de outros usuários são executados na infraestrutura gerenciada quando há adesão, ou ignorados se Require Self-Hosted Machines estiver ativado. Isso protege repositórios públicos onde contribuidores externos podem deixar comentários.
• Linear rejeita solicitações auto-hospedadas explícitas quando Allow Self-Hosted Machines está desativado. A issue recebe um erro de atividade do agente pedindo que um admin ative os workers auto-hospedados ou remova a indicação para executar na infraestrutura gerenciada pelo Cherri Code.

Para direcionar para uma das suas próprias máquinas pelo nome, use My Machines com worker= ou machine=.

A API do Cloud Agent usa o mesmo resolvedor com os campos usePrivateWorker e labels. Consulte a documentação da API do Cloud Agent para detalhes dos endpoints.

Hooks

Os workers de Self-Hosted Machines executam hooks baseados em comandos durante sessões de Cloud Agent. Eles carregam a configuração a partir do espaço de trabalho que o worker atende.

• Hooks de projeto. Faça commit do .cursor/hooks.json e dos scripts que ele referencia no repositório ou no diretório do espaço de trabalho que o worker usa. Esse é o git checkout, uma raiz --worker-dir ou o diretório que você informa para um any-repo pool.
• Hooks gerenciados pela equipe e pelo nível corporativo. No Enterprise, os workers também executam hooks configurados no web dashboard.

A referência de Hooks cobre o schema, os eventos e os exemplos. Cloud agent support lista quais eventos o loop do Cloud Agent executa.

Os limites de Cloud Agent que também valem para esses workers de execução de ferramentas:

• Apenas hooks baseados em comandos. Hooks baseados em prompt não são executados.
• Sem hooks exclusivos do IDE. Hooks do Tab (beforeTabFileRead, afterTabFileEdit) e workspaceOpen não são executados nos workers.

sessionStart e sessionEnd são executados nos workers de Self-Hosted Machines. Eles disparam quando uma sessão de Cloud Agent faz o claim do worker e quando esse claim é liberado. Os Cloud Agents gerenciados pela Cherri Code ignoram esses hooks.

Os workers no Kubernetes e em outras plataformas orquestradas usam esse mesmo modelo de hooks.

Rótulos

Rótulos são pares de chave-valor que descrevem um worker. Eles controlam como as sessões do Cloud Agent são direcionadas ao pool correto.

agent worker \  --pool \  --label team=backend \  --label env=production \  start

Os rótulos repo e pool são reservados. repo vem do remote do Git do diretório do worker, quando presente. pool é definido por --pool. Não defina nenhum deles manualmente.

Servidores MCP

Os servidores MCP em workers self-hosted são roteados por tipo de transporte:

Se o seu servidor MCP precisar acessar endpoints de rede privada, use o transporte de comando (stdio). O processo é executado diretamente no worker e usa a mesma rede. Para servidores MCP baseados em HTTP, o Cherri Code gerencia a conexão pelo backend, cuidando do OAuth e do cache de sessão.

Artefatos

O comportamento dos artefatos é idêntico em workers self-hosted e agentes Cherri Code-hosted. O agente produz o artefato dentro do worker, e o worker faz o upload para o armazenamento gerenciado pelo Cherri Code via HTTPS. Tudo o que acontece depois (PR embeds, dashboard previews, anexos de notificação) é gerenciado pelo backend do Cherri Code e não depende de onde o worker é executado.

Os artefatos são ativados por padrão. Consulte Recursos para ver como eles aparecem na UI.

Para desativar os uploads de artefatos, bloqueie o tráfego de saída para cloud-agent-artifacts.s3.us-east-1.amazonaws.com. A sessão do agente continua funcionando; o upload dos artefatos produzidos durante a sessão falha.

Rede

Os workers precisam de acesso HTTPS de saída para:

• api2.cursor.sh e api2direct.cursor.sh para a sessão do agente
• downloads.cursor.com para atualizações da CLI e a primeira instalação do Cherri Code Computer Use no macOS
• cloud-agent-artifacts.s3.us-east-1.amazonaws.com para upload de artefato

Se o seu firewall só aceitar curingas, *.s3.us-east-1.amazonaws.com inclui o host de artefato, mas também libera todos os outros buckets da região. Prefira uma regra de host exato quando o firewall oferecer suporte a isso.

Não são necessárias portas de entrada, IPs públicos nem túneis VPN. Se você usar um proxy, defina HTTPS_PROXY ou https_proxy no ambiente do worker.

Modos de falha

A seção Pré-requisitos aborda o conjunto mais amplo de hosts de que um worker precisa durante execuções de agentes (hosts do Git, registros de pacotes, APIs internas).

Deploy no Kubernetes

Execute workers do pool no Kubernetes quando quiser que a própria plataforma cuide do agendamento, dos health checks e do ciclo de vida dos Pods. Comece por anysphere/k8s-workers: um exemplo de Helm que executa o controlador de worker no seu cluster com --spawn. O spawn hook cria um Pod de worker por solicitação reivindicada, ou o controlador mantém Pods idle pré-aquecidos com --warm-idle. Nenhuma CRD é necessária.

Outros hosts funcionam da mesma forma: qualquer VM, container ou máquina bare-metal que consiga instalar a CLI do Cherri Code e acessar o Cherri Code por HTTPS de saída pode executar um worker do pool com systemd, Docker ou seu próprio gerenciador de processos. Para guias de parceiros e templates de referência sobre AWS Lambda, Cloudflare, Namespace, Modal, Daytona, E2B, Vercel, Tensorlake, Coder e SuperServe, consulte integração.

Controlador de workers

O agent worker controller inicia workers a partir de um hook --spawn. O hook pode fazer fork de um processo, iniciar um contêiner ou criar um Pod do Kubernetes, como faz o template k8s-workers. --warm-idle é o caminho de capacidade warm: o controlador executa o hook uma vez para cada worker ocioso ausente, em vez de aplicar patch em um Deployment ou HPA. WorkerDeployment.spec.readyReplicas pertence ao Kubernetes operator descontinuado; somente clusters que já o executam precisam desse controle.

--spawn <path> é obrigatório. O hook é executado uma vez após uma declaração bem-sucedida, ou uma vez para cada warm worker ausente. O ambiente do hook inclui CURSOR_API_KEY (ou CURSOR_AUTH_TOKEN no lugar dela, ao usar --session-token), CURSOR_API_URL, CURSOR_API_ENDPOINT, CURSOR_AGENT_WORKER_ID e os campos da solicitação. Autentique-se com uma chave de conta de serviço via --api-key ou CURSOR_API_KEY. A chave define a equipe. O login por sessão não é usado.

O hook de spawn recebe tudo o que precisa como variáveis de ambiente:

O hook de spawn deve iniciar um worker com o mesmo worker id:

#!/usr/bin/env bashset -euo pipefailagent worker --pool "$CURSOR_POOL" --worker-id "$CURSOR_AGENT_WORKER_ID" start

A CLI do worker também lê CURSOR_AGENT_WORKER_ID do ambiente, então um hook de spawn que inicia um contêiner pode, em vez disso, repassar as variáveis:

#!/usr/bin/env bashset -euo pipefaildocker run -d \  -e CURSOR_API_KEY \  -e CURSOR_AGENT_WORKER_ID \  -e CURSOR_WORKER_POOL_NAME="$CURSOR_POOL" \  your-worker-image \  agent worker --pool start

Reserva-then-spawn

Modo padrão. O controlador lista as solicitações pendentes, monitora GET /v0/private-workers/pending-requests/stream, reserva cada solicitação e executa --spawn uma vez para cada reserva.

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --pool default

Warm pool

--warm-idle <count> mantém <count> workers ociosos conectados em cada --pool, criando antecipadamente workers sem declaração. Ele nunca chama a declaração. O Cherri Code atribui os agentes em fila a esses warm workers.

O controlador reconcilia com GET /v0/private-workers/pools a cada 60 segundos. O stream SSE de solicitações pendentes apenas acelera o backfill.

O modo warm exige --pool e não pode ser combinado com --all-pools. Execute um controlador warm por pool: não existe lease de criação no lado do servidor, portanto controladores concorrentes podem criar workers em excesso temporariamente.

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --warm-idle 5

Tokens de sessão

Por padrão, toda máquina iniciada pelo spawn hook armazena a chave de API da conta de serviço. Com --session-token, o controlador solicita um token de sessão para cada declaração e repassa esse token ao hook, de modo que a chave permanece no controlador.

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --session-token

O hook recebe CURSOR_AUTH_TOKEN e CURSOR_AUTH_TOKEN_EXPIRES_AT em vez de CURSOR_API_KEY. Grave o token em um arquivo e inicie o worker com --auth-token-file:

#!/usr/bin/env bashset -euo pipefailprintf '%s' "$CURSOR_AUTH_TOKEN" > /run/cursor/tokenagent worker --pool "$CURSOR_POOL" --auth-token-file /run/cursor/token start

Um token de sessão:

• Atende a uma única declaração. Ele só pode conectar o worker id declarado, e o Cherri Code o recusa em qualquer endpoint que um worker não chama.
• Expira junto com a declaração. Ele deixa de funcionar quando a declaração é liberada ou quando a chave da conta de serviço que o emitiu é excluída ou expira. A expiração de 7 dias em CURSOR_AUTH_TOKEN_EXPIRES_AT serve como garantia adicional.
• Pode ser substituído. Um worker que precisa de um token para uma declaração que você já detém, como uma máquina hibernada reativada ou uma execução que dura mais que o token, obtém um novo por meio de Create A Session Token. O controlador faz isso por você quando reativa uma máquina hibernada. Grave o token substituto no mesmo arquivo; o worker relê o arquivo ao se reconectar.

Workers pré-aquecidos iniciam antes de existir qualquer declaração, por isso controladores com --warm-idle continuam passando a chave de API para o hook. Quando o Cherri Code recusa um token de sessão, o worker é encerrado e exibe o motivo, como o horário de expiração do token ou o fato de a declaração ter terminado.

Para criar seu próprio controlador, use a API de Cloud Agents.

Ciclo de vida da sessão

Assim que um worker é associado a uma solicitação, o Cherri Code encaminha todas as chamadas de ferramenta do agente diretamente para a máquina. A conexão tem um tempo limite de inatividade de 1 hora por padrão. Configure-o conforme necessário:

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout (variável de ambiente CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) é o número de segundos que o worker permanece conectado após o fim de uma sessão, aguardando mensagens de acompanhamento. Se uma mensagem de acompanhamento chegar, o temporizador é reiniciado. Quando o tempo limite é atingido, a CLI encerra com o código 0 para que um supervisor possa reciclar a máquina. Passe 0 para desativar a liberação por inatividade. Liberar uma reserva é uma API separada: ela deixa de priorizar aquela máquina para o agente, mas não encerra a CLI do worker.

Assim que um worker atinge o tempo limite, o Cherri Code o marca como liberado. A máquina pode ser reiniciada e voltar ao pool. Se um usuário reiniciar um chat que foi desconectado de sua máquina, o chat se reconecta a uma nova máquina do pool. O estado do espaço de trabalho da máquina original não é transferido, a menos que o pool use hibernação.

Hibernação

Uma máquina de pool não precisa permanecer online enquanto seu agente está ocioso. Depois que uma sessão termina, o worker aguarda mensagens de acompanhamento até que seu tempo limite de inatividade seja acionado, e manter todas as máquinas ligadas entre os turnos sai caro.

O custo dessa escolha é a localidade do espaço de trabalho. Sem hibernação, uma mensagem de acompanhamento que chega depois que a máquina foi liberada readquire capacidade do pool: o agente cai em uma máquina nova e pode gastar os primeiros minutos reconstruindo o espaço de trabalho que já tinha. Com hibernação, a máquina volta com o espaço de trabalho intacto e a mensagem de acompanhamento retoma de onde o agente parou.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/pools" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "scope": "team",    "poolName": "my-pool",    "workerReadyTimeoutSeconds": 900  }'

export CURSOR_AGENT_WORKER_ID="<claimedWorkerId>"agent worker --pool my-pool start

Crie seu próprio controlador

O controlador integrado atende à maioria das configurações. Se você precisar de lógica personalizada, por exemplo, seu próprio agendamento, cotas ou alocação de máquinas, construa um controlador sobre a API de Cloud Agents. Um controlador faz três coisas: observa a fila de solicitações, reserva uma solicitação e inicia um worker para ela. Os mesmos endpoints servem para monitorar a utilização e implementar o escalonamento automático fora do Kubernetes.

Autentique-se com a chave de API da conta de serviço do pool via Basic auth ou Bearer token. Outros tipos de chave de API não podem gerenciar a capacidade do pool de workers.

Monitorar a fila de solicitações

Liste a fila uma vez para montar sua visão das solicitações pendentes e, em seguida, acompanhe as alterações em tempo real por Server-Sent Events (SSE).

Comece com GET /v0/private-workers/pending-requests. Adicione ?pool=<name> para acompanhar um único pool. Pagine até o fim e guarde o streamCursor da resposta:

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pending-requests?pool=my-pool&limit=50" \  -u "$CURSOR_API_KEY:"

Em seguida, abra o stream de eventos com GET /v0/private-workers/pending-requests/stream, passando esse streamCursor e os mesmos filtros. Mantenha sua visualização atualizada conforme os eventos chegam: adicione solicitações dos eventos created e claimed_offline e remova solicitações ao ver claimed ou expired:

curl --request GET --no-buffer \  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?pool=my-pool&cursor=$STREAM_CURSOR" \  --header 'Accept: text/event-stream' \  -u "$CURSOR_API_KEY:"

Os cursores expiram cinco minutos após a listagem que os emitiu. Quando o stream retornar 410 Gone, liste novamente e reabra o stream a partir do novo streamCursor. Melhor ainda: liste novamente a cada cinco minutos com algum jitter, em vez de esperar pelo 410.

O número de solicitações na sua visualização corresponde à profundidade da fila do pool. Quando ela crescer, adicione workers. Trate os eventos como indícios e a listagem como fonte da verdade: a entrega de eventos é best-effort, e cada nova listagem corrige eventuais divergências. Consulte Watch Solicitações Pendentes de Pool para ver todas as garantias de entrega e as regras de cursor.

Listar workers

curl --request GET \  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \  -u "$CURSOR_API_KEY:"

Os workers incluem name, isInUse, metadados de conexão e campos de repositório (repoOwner/repoName são strings vazias para workers any-repo). Consulte a referência da API para ver a resposta completa.

Listar pools

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool" \  -u "$CURSOR_API_KEY:"

Retorna os pools duráveis com connectedWorkerCount, inUseWorkerCount, isStale e campos opcionais de repositório. Pools any-repo omitem os campos de repositório. Use isso para obter as contagens de workers conectados e em uso por pool; o resumo de workers de toda a equipe abaixo não substitui a demanda específica de cada pool.

Buscar resumo do worker

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/summary" \  -u "$CURSOR_API_KEY:"

Retorna as contagens de itens conectados e em uso do seu usuário e da sua equipe. Veja Get Worker Summary. Use isso para dimensionar sua resposta quando a profundidade da fila crescer, ou para acionar o escalonamento quando a utilização estiver alta:

const summary = await response.json();const team = summary.teamSummary;if (team && team.totalConnected > 0) {  const utilization = team.inUse / team.totalConnected;  if (utilization >= 0.9) {    // Escalar horizontalmente: provisionar workers adicionais  }}

Buscar worker por ID

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pw_123" \  -u "$CURSOR_API_KEY:"

Declarar uma solicitação pendente

Controladores efêmeros podem reservar uma solicitação em fila antes de iniciar um worker:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Em seguida, inicie o worker com o mesmo id (CURSOR_AGENT_WORKER_ID=pw_123). Consulte Declaração de uma solicitação pendente.

Para não expor a chave da conta de serviço no worker, adicione "sessionToken": true ao corpo. A resposta então também inclui um token de sessão em token, com a data de expiração em expiresAt. Grave o token em um arquivo e inicie o worker com --auth-token-file em vez da chave.

Emitir um token de sessão

Obtenha um novo token de sessão para uma declaração que sua equipe já detém, por exemplo, para reativar uma máquina hibernada:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/tokens" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Consulte Criar um token de sessão.

Liberar uma reserva

Remova a reserva que vincula um agente a um self-hosted worker. O Cherri Code deixa então de priorizar essa machine para o agente:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \  -u "$CURSOR_API_KEY:"

Uma segunda reserva feita enquanto há uma reserva ativa é rejeitada; libere-a primeiro e depois reserve um novo workerId. Consulte Liberar uma reserva.

Monitoramento

O servidor de gerenciamento expõe GET /metrics, GET /healthz e GET /readyz ao iniciar um worker com --management-addr:

agent worker --pool --management-addr ":8080" start

Colete métricas do seu worker:

curl http://localhost:8080/metrics

Métricas disponíveis

Indicadores

Contadores

Motivos de encerramento da sessão

O contador cursor_self_hosted_worker_session_ends_total inclui um rótulo reason com um destes valores:

Segurança

Fluxo de dados. Duas coisas saem da sua rede: fragmentos de arquivo que o modelo lê durante a inferência e artefatos do Cloud Agent (capturas de tela, vídeos e referências de logs) que o worker envia para o armazenamento gerenciado pelo Cherri Code para que eles possam aparecer em PRs e no dashboard. Seus repositórios, caches de build e segredos permanecem nas suas máquinas.

Somente saída. Os workers fazem conexões de saída via HTTPS. Nenhuma porta de entrada nem alteração no firewall é necessária.

Privacy Mode. Os Cloud Agents self-hosted respeitam as configurações do Privacy Mode do Cherri Code. Quando o Privacy Mode está habilitado, seu código não é usado para treinamento.

Isolamento. Cada sessão de agente recebe seu próprio worker dedicado. As sessões não são compartilhadas entre workers.

Autenticação. Workers do pool se autenticam com uma chave de API da conta de serviço ou com um token de sessão válido para uma única declaração, para que a chave nunca chegue ao worker. Outros tipos de chave de API são rejeitados.

Visibilidade no dashboard. Admins da equipe podem ver todos os workers conectados. Membros da equipe veem apenas os workers atribuídos a eles.

Referência da CLI

agent worker [options] start

Perguntas frequentes

Próximos passos

• anysphere/k8s-workers: template de Kubernetes construído sobre agent worker controller --spawn, com modos reserva-then-spawn e --warm-idle.
• Integrações: guias de partners e templates de referência para outras plataformas.
• Kubernetes operator (descontinuado): referência para clusters que já executam o operator WorkerDeployment.
• Computer use: permita que agentes controlem um desktop e um browser nos seus workers.
• Referência da API: endpoints para workers, pools, a fila de solicitações pendentes e tokens de worker.