Toda conversa sobre agentes de codificação com IA acaba esbarrando na mesma pergunta prática, geralmente mais tarde do que deveria: onde o código realmente é executado? Não qual modelo, mas qual máquina guarda o seu repositório, as suas credenciais, os seus caches e o shell no qual o agente está digitando.
O Sharkly transforma essa resposta em um conceito de primeira classe chamado Computer. Um Computer fornece o host de execução para o trabalho dos Agentes. Ele pode ser um computador local, um servidor remoto, um contêiner ou um host de nuvem compatível. O seu notebook se qualifica. A máquina Linux no seu rack também. Você escolhe o host, você o controla, e o Sharkly coordena o trabalho nele em vez de executar o seu código em algum lugar que você não consegue ver.
O Sharkly não substitui o Claude Code, o Codex ou outras ferramentas de execução. Ele adiciona a camada compartilhada de tarefas, Computers, contexto, controle e revisão em torno das ferramentas que a sua equipe já usa. Essas ferramentas continuam instaladas nas suas máquinas, e o uso dos modelos continua pelas assinaturas ou chaves de API configuradas nelas.
Resumo rápido
Um Computer é o host de execução do trabalho dos Agentes no Sharkly: um computador local, um servidor remoto, um contêiner ou um host de nuvem compatível que você controla. Um pequeno serviço local conecta o Computer ao Sharkly, detecta os Runtimes disponíveis (as ferramentas de agente concretas instaladas ali, como o Claude Code ou o Codex), recebe execuções na fila, prepara o diretório da tarefa, inicia o Runtime selecionado e transmite o progresso de volta para a Tarefa. Conecte uma máquina pessoal com o Sharkly Desktop, ou um host remoto com a CLI do Sharkly e um token de instalação de uso único. O uso dos modelos flui pelas assinaturas e chaves de API já configuradas nas suas ferramentas; os limites de concorrência definem quanta carga de trabalho paralela um host suporta.
O que um Computer é, e o que ele não é
O Sharkly divide a execução em quatro papéis, e cada um tem exatamente uma função:
- O Agente define como o trabalho deve ser conduzido: instruções, Skills, repositórios, configurações de execução.
- O Computer fornece o host e os recursos locais: sistema operacional, arquivos, credenciais, rede, ferramentas.
- O Runtime realiza a sessão de agente propriamente dita: a ferramenta de codificação detectada naquele Computer.
- A Tarefa permanece como o registro compartilhado: objetivo, discussão, estado de execução, rastreamento, resultado.
Essa separação explica a maior parte do que vem a seguir. Um Agente não é o host de execução; a mesma configuração de Agente pode apontar para Computers diferentes ao longo do tempo. Um Computer não é um agente; ele reúne um ou mais Runtimes e não faz nada até que um trabalho seja enviado a ele. E um único Computer pode atender vários Agentes ao mesmo tempo, limitado pela sua cota de concorrência.
Isso também explica a proposta de valor. Plataformas hospedadas empacotam o modelo, o executor e a infraestrutura em um único produto, o que significa que o seu código é executado em uma infraestrutura que você não opera. O Sharkly assume a posição oposta: o host de execução é seu, e o que ele acrescenta por cima é atribuição, enfileiramento e revisão. Se você é novo nesse modelo, o que é o Sharkly cobre o cenário completo.
O serviço local: a peça que faz o trabalho de verdade
Um pequeno serviço local conecta cada Computer ao Sharkly. Ele registra o Computer, detecta os Runtimes instalados, envia heartbeats, recebe execuções na fila, prepara diretórios de tarefa e reporta o progresso e os resultados de volta.
Um detalhe de design carrega bastante peso operacional: o serviço local é quem inicia a conexão com o servidor, então uma configuração típica não exige porta de entrada. É isso que faz de um notebook atrás de um roteador doméstico, de uma estação de trabalho atrás de um firewall corporativo e de um servidor em uma sub-rede privada Computers igualmente viáveis.
Os heartbeats são como o Sharkly sabe que um Computer está vivo: Online quando o servidor os está recebendo, Offline quando eles param. A distinção que economiza tempo de troubleshooting: online significa apenas que os heartbeats estão chegando. Não significa que o Runtime selecionado consegue executar uma Tarefa.
Runtimes: o que o seu Computer realmente consegue executar
Um Runtime é uma capacidade de execução de agente compatível, detectada em um Computer. O serviço local procura por ferramentas de agente compatíveis e reporta cada uma que esteja utilizável, de modo que um Computer com Claude Code e Codex instalados expõe ambos como Runtimes que um Agente pode selecionar.
A página de detalhes do Computer informa um status de capacidade para cada Runtime:
- Disponível: o Runtime está conectado e pode executar trabalho de Agente.
- Requer configuração: a ferramenta foi detectada, mas falta alguma configuração obrigatória.
- Não instalado: a ferramenta não está disponível para o serviço local; instale-a ou escolha outro Runtime.
- Sem suporte: o Runtime ou o ambiente está fora do conjunto de capacidades compatíveis.
A instalação continua sendo responsabilidade sua, por decisão de design. Você instala e autentica cada ferramenta da mesma forma que faria para usá-la diretamente; a página de detalhes do Computer indica o guia oficial de instalação, e um novo escaneamento confirma que o serviço local consegue enxergá-la. Se uma capacidade da qual você depende não for detectada, você pode adicionar um Runtime ACP personalizado com um nome e um comando de inicialização e, depois, testar a conexão.
Duas consequências vêm daí. A proposta de “traga a sua própria assinatura” é literal: a cota de modelo depende das ferramentas de codificação com IA, dos planos e das contas de API que a sua equipe conecta, então um erro de cota aponta para a conta configurada na ferramenta, e não para uma configuração do Sharkly. E a seleção de modelo fica com a ferramenta: um Agente segue o modelo padrão do seu Runtime. Como os Agentes são configurados é o assunto de Agentes no Sharkly.
Conectando o seu primeiro Computer
O primeiro Computer geralmente é a máquina em que você está sentado. Abra Configurações, vá em Computers, escolha Conectar Computer e selecione o caminho de configuração para o seu sistema operacional. Para um computador pessoal compatível, o caminho recomendado é instalar o Sharkly Desktop, que inclui o serviço local e conduz você pelo processo de registro. O guia de primeiros passos percorre tudo isso de ponta a ponta em cerca de dez minutos.
Depois de conectar, confirme que pelo menos um Runtime aparece como Disponível. Esse é o ponto de verificação que as pessoas costumam pular: um Computer conectado sem um Runtime utilizável não consegue executar trabalho de Agente.
Duas configurações exclusivas do desktop importam para notebooks. Impedir suspensão mantém a máquina acordada para que uma execução longa não seja interrompida, e Continuar em execução com a tampa fechada é uma opção separada do macOS. Ambas aparecem apenas na máquina local, nunca em um Computer remoto.
Adicionando um servidor remoto
Um notebook é um ótimo primeiro Computer e um péssimo Computer permanente. Ele suspende, viaja e disputa memória com a sua IDE. O segundo passo natural é um host remoto que fica sempre ligado. Instale nele a CLI do Sharkly e o serviço local diretamente:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
sharkly version
Em seguida, na página Computers, gere um token de instalação de uso único e execute no host de destino o comando de registro que ele fornece:
sharkly computer register --install-token sit_...
O registro grava o Computer na sua organização, inicia o serviço local e dispara a detecção de Runtimes. O token de instalação expira em 30 minutos e é de uso único, o que leva a uma regra de higiene que a documentação enuncia sem rodeios: não o coloque em uma imagem reutilizável, script, Tarefa ou comentário.
As credenciais são deliberadamente separadas aqui. Um token de acesso pessoal não registra um computador, e um token de instalação não cria um login humano na CLI. O token de acesso pessoal shk_ autentica você para comandos de recursos como sharkly task list; o token de instalação sit_ cria a sessão que o serviço local usa. A superfície mais ampla de comandos é o tema de o guia da CLI e da API do Sharkly.
Depois do registro, a mesma CLI também serve como o seu kit de diagnóstico: sharkly computer status e sharkly computer logs leem o estado local no host, enquanto sharkly computer list, show, usage e ping inspecionam Computers registrados de qualquer lugar. O host remoto precisa das mesmas coisas que o seu notebook tinha: ferramentas de agente instaladas e autenticadas, e acesso ao Git para repositórios privados.
Local, remoto ou contêiner: uma comparação honesta
Não existe um host único correto. A documentação trata todos eles como Computers, e os trade-offs são os de infraestrutura de sempre.
| Host | Melhor para | Pontos fortes | Atenção |
|---|---|---|---|
| Computador local (Sharkly Desktop) | Primeira configuração, trabalho individual, execuções com diretório especificado que reaproveitam o seu checkout e os seus caches já existentes | Zero infraestrutura extra; o seu ambiente e as suas credenciais exatos; diretórios de trabalho especificados estão disponíveis somente em Computers locais | Suspensão e desligamento interrompem a disponibilidade; as execuções disputam CPU e memória com o seu próprio trabalho |
| Servidor remoto (CLI + serviço local) | Cargas de trabalho em equipe, capacidade sempre ativa, concorrência mais alta | Fica online; isola a carga dos agentes do notebook de qualquer pessoa; um host pode atender vários Agentes | Você mesmo instala e autentica os Runtimes e o acesso ao Git; o planejamento de capacidade é por sua conta |
| Contêiner ou host de nuvem compatível | Ambientes de execução reproduzíveis e descartáveis | Ambiente limpo e reconstruível; o mesmo fluxo de registro via token de instalação | O token de uso único deve ser gerado a cada registro, nunca embutido em uma imagem reutilizável |
O par de decisão que mais importa: use o seu Computer local quando quiser Agentes trabalhando no ambiente em que você já confia; use um remoto quando as Tarefas precisarem continuar fluindo com o notebook fechado. Muitas equipes acabam com os dois, já que encaminhar trabalho para outro host é uma mudança de configuração, não de fluxo de trabalho.
O que acontece durante uma execução
Quando uma Tarefa atribuída a um Agente fica pronta, o Sharkly enfileira uma execução e a despacha para o Computer selecionado. Antes de o Runtime iniciar, o serviço local pode aguardar capacidade de concorrência, preparar um diretório, buscar os repositórios e projetar as variáveis de ambiente permitidas.
A preparação do diretório segue um de dois modos. No modo Temporário, cada Tarefa recebe um diretório isolado, e execuções com repositório podem preparar um worktree Git novo a partir dos dados de repositório em cache; use-o para a maioria dos trabalhos com repositório e sempre que várias Tarefas puderem modificar a mesma base de código em paralelo, como explorado em como o Sharkly executa Agentes em paralelo sem conflitos de merge. No modo Especificado, a execução reaproveita um diretório absoluto configurado em um Computer local, junto com as dependências e os caches que já estão nele, e um diretório especificado atende uma execução por vez.
Enquanto o Runtime trabalha, o progresso é transmitido de volta. O estado da execução passa por Na fila, Despachada, Aguardando diretório local e Em execução, e então Concluída, Com falha ou Cancelada. Eventos de rastreamento, chamadas de ferramentas e a resposta final retornam todos para a Tarefa. O Computer é onde a execução acontece fisicamente; a Tarefa é onde acontece a aceitação.
Concorrência: quanto um único Computer deve carregar?
Cada Computer tem um limite de concorrência de tarefas, e cada Agente tem o seu próprio máximo de Tarefas em execução paralela. Os padrões são conservadores de propósito: um Agente que usa diretórios temporários assume por padrão 50% do limite do Computer, e um que usa diretórios especificados assume por padrão a sua contagem de diretórios configurada. Se você forçar um valor acima dessa contagem, o produto avisa que as gravações podem colidir. Acredite no aviso.
A orientação da documentação é a que deve ser seguida: concorrência mais alta consome mais CPU, memória, disco, capacidade do provedor e largura de banda de repositório, então aumente-a somente depois que a configuração atual lidar com a carga existente de forma confiável. A capacidade do provedor é o teto que as pessoas esquecem: dez execuções paralelas por uma única conta de modelo atingem os limites de taxa dez vezes mais rápido. Para padrões de escala, veja executando vários agentes do Claude Code em paralelo.
Um Agente online ainda pode ter trabalho na fila simplesmente porque a concorrência ou a capacidade de diretórios está esgotada. Estar na fila é um estado saudável, não um estado travado.
Compartilhamento, propriedade e como manter o host limpo
Quando um Computer passa a atender a equipe, três controles importam. A visibilidade decide quem pode vê-lo e usá-lo: Pessoal, Organização ou Space. A propriedade é algo separado: o proprietário pode transferir o Computer e é a única pessoa que pode excluí-lo. E, no caso de um Computer pessoal local, o proprietário controla quais organizações podem usá-lo, de modo que entrar em uma nova organização nunca oferece o seu notebook sem você perceber.
As execuções de Agentes deixam diretórios de trabalho, caches e artefatos para trás, então a limpeza já vem embutida. Por padrão, ela torna execuções concluídas ou canceladas elegíveis depois de cerca de 7 dias, pode aplicar um limite mínimo de espaço livre e nunca toca em trabalhos em execução ou na fila, execuções fixadas (pinned) ou execuções com falha que ainda estão em investigação. Para uma verificação imediata, sharkly daemon disk-usage informa o uso e sharkly daemon cleanup mostra uma prévia do que seria recuperado.
Comece com a máquina que você já tem
O conceito de Computer responde a uma pergunta que as plataformas hospedadas preferem que você não faça: na infraestrutura de quem o agente está rodando? Aqui, a resposta é sua, de um único notebook a uma frota de servidores compartilhados. Você não precisa da frota no primeiro dia. Conecte um Computer, confirme que um Runtime aparece como Disponível, crie um Agente e atribua a ele algo sem graça. Quando os limites do notebook aparecerem, registre um servidor ao lado dele. A documentação do Sharkly cobre cada configuração aqui com mais profundidade.
Perguntas frequentes
O que é um Computer no Sharkly?
Um Computer é o host de execução do trabalho dos Agentes: um dispositivo, servidor ou contêiner conectado que fornece o sistema operacional, os arquivos, as credenciais, o acesso à rede e as ferramentas de que um Agente precisa. Um pequeno serviço local o conecta ao Sharkly, detecta Runtimes, recebe execuções e transmite o progresso de volta para a Tarefa.
O Sharkly executa o meu código na nuvem dele?
Não. O trabalho dos Agentes é executado nos Computers que você conecta, que são máquinas sob o seu controle. O Sharkly coordena atribuição, enfileiramento, progresso e revisão em torno desses hosts. O uso dos modelos também é seu: ele flui pelas assinaturas ou chaves de API configuradas nas ferramentas de codificação instaladas em cada Computer.
Como conecto um servidor remoto como Computer?
Instale a CLI do Sharkly no host, gere um token de instalação de uso único na página Computers e execute sharkly computer register --install-token sit_... nessa máquina. O token expira em 30 minutos e funciona uma única vez, então nunca o embuta em uma imagem ou script. Depois, instale e autentique as ferramentas de agente que você quiser e confirme que cada Runtime aparece como Disponível.
Por que o meu Computer aparece como Online, mas a execução não inicia?
Online significa apenas que o serviço local está enviando heartbeats; não significa que o Runtime selecionado consegue executar trabalho. Abra os detalhes do Computer e verifique o status de capacidade do Runtime: Requer configuração e Não instalado bloqueiam as execuções. O comando sharkly computer ping confirma se um Runtime específico completa uma ida e volta.
