Carbon SuperAgent

Instalar o Carbon

Requisitos: Node 22.13+, git e um agente logado: Claude Code ou Codex. gh é opcional (para abrir PRs).

# clone, instale e rode o setup interativo
git clone https://github.com/leolegends/carbon-superagent.git
cd carbon-superagent
npm install
npm run setup

O setup verifica a máquina, oferece instalar o agente que faltar, compila o painel e abre o assistente no navegador (perfil de admin, agente e repositório). Depois:

npm start        # painel em http://127.0.0.1:3417
npm run doctor   # diagnóstico do ambiente

Primeira tarefa local

1. No Mission Control, crie uma tarefa à mão (ou importe do Linear, GitHub, Jira, Slack, Telegram).
2. Escolha executor, modelo e esforço (ou automático). Em Onde rodar, deixe Esta máquina.
3. A tarefa passa por intake → plan → research → code → test → review → deliver → reflect num worktree isolado, no branch agent/<tarefa>.
4. Se o agente pedir permissão ou fizer uma pergunta, um card aparece com as opções.
5. No card Branch e entrega: Abrir PR, Merge local ou Aplicar na pasta.

Localmente, o Carbon roda uma tarefa por vez (fila serial) e a UI escuta só em 127.0.0.1. Para rodar mais de uma ao mesmo tempo, use workers.

Conceitos

Cada tarefa tem um runtime (onde roda), independente do executor (Claude Code ou Codex). O painel continua dono da fila, do estado e da entrega; o worker só executa.

O worker puxa

Toda conexão sai do worker para o painel por HTTPS: hello, claim (long-poll de 25 s), eventos, heartbeat, entrega. A máquina worker não abre portas; o painel precisa de uma URL alcançável só em /api/worker/*.

Lease

Quem pega a tarefa recebe um lease (padrão 60 s) e o renova a cada leaseMs/3. Sem renovação, a tarefa falha com worker <nome> parou de responder — ou volta para a fila com workers.requeueOnLeaseLoss. O cancelamento chega ao worker no próximo heartbeat.

Transporte de código: git ou bundle

Com o branch no repositório do painel, Aplicar na pasta, Merge local e Abrir PR funcionam como numa tarefa local.

Join por IP, sem servidor

O mesmo carbon join do cluster, sem servidor, domínio, túnel nem Docker: o painel roda no seu computador e outro computador entra como nó apontando para <ip>:<porta>, pela rede local ou pelo IP público (porta liberada no roteador).

1. No painel, CARBON_WORKER_LISTEN=0.0.0.0:3418 no .env.local e npm start. O listener gera um certificado próprio (autoassinado) e o terminal mostra os IPs, o fingerprint e o comando pronto.
2. Configurações → Máquinas → Entrar no cluster → gerar token de join. Sem URL pública configurada, o comando já sai com o IP deste computador e o --fingerprint (mais os outros IPs e a versão para IP público).
3. No outro computador (Carbon instalado, Claude Code/Codex logado), rode o comando. Ele confere o certificado, entra no cluster e salva credencial e fingerprint para os próximos starts.

# rede local
carbon join 192.168.0.12:3418 --token cjt_… --fingerprint 5c187335…2a01
# internet: port forwarding TCP 3418 → computador do painel
carbon join 203.0.113.7:3418 --token cjt_… --fingerprint 5c187335…2a01
# sem terminal (serviço)
CARBON_JOIN_TOKEN=cjt_… CARBON_WORKER_PARALLEL=2 carbon join 192.168.0.12:3418 --fingerprint 5c18…

Por que é seguro sem domínio: o worker não confia em CA nenhuma; ele fixa o SHA-256 do certificado do painel (como o SSH com a chave do servidor). Outro certificado, seja de endereço errado ou de alguém no meio do caminho, derruba a conexão antes de qualquer token ser enviado. Sem --fingerprint, o comando mostra o fingerprint e pergunta se confere com o do painel.

Guia completo, variáveis e problemas comuns: direct-join.md.

Workers com Docker Compose

Pré-requisitos: painel exposto e URL pública do painel (https://) em Configurações → Execução.

1. Configurações → Máquinas → Adicionar máquina → Docker Compose, réplicas, tarefas por worker, executores, imagem (opcional) → Gerar kit. O token aparece uma única vez e já vai no .env do kit.
2. Na máquina worker, gere a imagem (não é publicada em registry), na mesma versão do painel.
3. Preencha o .env e suba.

# imagem (no repositório do Carbon, mesma versão do painel)
docker build -f deploy/worker/Dockerfile -t carbon-worker:0.2.0 .
# com Codex: --build-arg WITH_CODEX=true

# kit
tar xzf carbon-worker-servidor-sp-01.tar.gz && cd carbon-worker-servidor-sp-01
docker compose up -d
docker compose up -d --scale worker=3
docker compose logs -f worker

# .env — credenciais na máquina worker (nunca vêm do painel)
ANTHROPIC_API_KEY=...            # ou CLAUDE_CODE_OAUTH_TOKEN (claude setup-token)
# OPENAI_API_KEY=...             # Codex
CARBON_GIT_TOKEN=...             # push via https (opcional)
CARBON_GIT_HOSTS=github.com      # hosts que podem receber o token

Parada: docker compose down envia SIGTERM; o worker para de pegar tarefas e espera as atuais até CARBON_WORKER_GRACE_SECONDS (120 s). Capacidade = réplicas × CARBON_WORKER_PARALLEL.

Detalhes: docker-compose.md.

Kubernetes

Mesmo fluxo, escolhendo Kubernetes. O kit cria o namespace carbon-<nome> com namespace.yaml, secret.yaml (único arquivo com o token), deployment.yaml, networkpolicy.yaml (sem ingress) e kustomization.yaml.

kubectl apply -k .
kubectl -n carbon-cluster-a scale deployment/carbon-worker --replicas=5
kubectl -n carbon-cluster-a logs -f -l app.kubernetes.io/name=carbon-worker --max-log-requests=20

• Use uma imagem de registry acessível pelo cluster (campo Imagem ou --image).
• terminationGracePeriodSeconds: 600, o worker espera até 540 s pelas tarefas.
• Pod não-root (UID 10001), readOnlyRootFilesystem, emptyDir para /home/carbon e /tmp; 2 CPU / 4Gi.
• Em produção, troque o secret.yaml por Sealed Secrets ou External Secrets e restrinja o egress da NetworkPolicy.

Detalhes: kubernetes.md.

AgentCore experimental

Cada tarefa vira uma sessão do AgentCore Runtime. O painel chama InvokeAgentRuntime com {taskId, panelUrl, taskToken} (token de uso único); o container responde 202, faz o claim daquela tarefa e usa o mesmo protocolo dos workers. Ao terminar, o painel chama StopRuntimeSession.

1. Baixe o kit: Configurações → Execução → Kit AgentCore (experimental), ou node bin/carbon.mjs worker init --target agentcore --out ./carbon-agentcore.
2. Crie a role de execução com iam-policy.json (ECR + logs) e trust para bedrock-agentcore.amazonaws.com.
3. Na raiz do Carbon: npm run build:worker e rode o deploy.sh (você executa; o Carbon não executa nada na AWS).
4. Cole o ARN em Configurações → Execução, ligue o AgentCore e defina sessões simultâneas (padrão 3).

ACCOUNT_ID=<ACCOUNT_ID> \
ROLE_ARN=arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME> \
CARBON_PANEL_URL=https://workers.exemplo.com \
CLAUDE_CODE_USE_BEDROCK=1 \
bash ./carbon-agentcore/deploy.sh

• CARBON_PANEL_URL (https://) é obrigatória no container; invocações para outro painel recebem 403.
• Imagem linux/arm64, porta 8080, POST /invocations, GET /ping (HealthyBusy enquanto trabalha).
• Teto de 8 h por sessão (AWS); a tarefa respeita antes o maxRunMinutes do Carbon (até 240 min).
• Credenciais AWS do painel: cadeia padrão do SDK (AWS_PROFILE, SSO, ~/.aws). Nada de chave AWS no Carbon.
• Prefira Bedrock via IAM role a ANTHROPIC_API_KEY em variável de ambiente do runtime.
• Pontos de atenção: egress no modo PUBLIC, login do Claude Code no container, parâmetros da CLI bedrock-agentcore-control.

Detalhes: agentcore.md.

Expor o painel

Workers precisam alcançar só /api/worker/*. O listener separado encaminha essas rotas para o painel local; qualquer outra recebe 404. A UI continua em 127.0.0.1.

# .env.local do painel
CARBON_WORKER_LISTEN=127.0.0.1:3418     # atrás de túnel/VPN; 0.0.0.0:3418 = direto por IP
# TLS: auto (certificado próprio fora de loopback) · on · off
CARBON_WORKER_TLS=auto
# opcional: certificado seu (tem prioridade)
CARBON_WORKER_TLS_CERT=/caminho/cert.pem
CARBON_WORKER_TLS_KEY=/caminho/key.pem

Em ordem de preferência:

1. Direto por IP (sem servidor): listener em 0.0.0.0:3418 e carbon join com fingerprint.
2. Tailscale: tailscale serve --https=443 http://127.0.0.1:3418 (Funnel para AgentCore).
3. Cloudflare Tunnel só para a porta do listener: cloudflared tunnel --url http://127.0.0.1:3418.
4. Reverse proxy com TLS (Caddy, nginx) para 127.0.0.1:3418.

Para kits Compose/Kubernetes e AgentCore, configure a URL pública do painel (https://) em Configurações → Execução. HTTPS é obrigatório fora de loopback: o token vai no cabeçalho Authorization.

curl -s -o /dev/null -w '%{http_code}\n' https://workers.exemplo.com/   # 404

Detalhes: exposing-the-panel.md.

Servidor por túnel SSH + Claude Code compartilhado experimental

Um servidor seu como worker sem abrir porta na internet e sem copiar credencial: uma conexão SSH aberta do seu computador leva o listener e um proxy de autenticação até o loopback do servidor.

# .env.local do painel: listener só no loopback
CARBON_WORKER_LISTEN=127.0.0.1:3418

# do seu computador: dois túneis reversos (o servidor só enxerga 127.0.0.1)
ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=20 \
  -R 127.0.0.1:3418:127.0.0.1:3418 -R 127.0.0.1:8787:127.0.0.1:8787 usuario@servidor

# no servidor (usuário próprio, sem sudo, fora do grupo docker)
CARBON_PANEL_URL=http://127.0.0.1:3418
ANTHROPIC_BASE_URL=http://127.0.0.1:8787
CLAUDE_CODE_OAUTH_TOKEN=placeholder-proxy-injects-real

Em Configurações → Máquinas → Claude Code deste computador para os workers, um interruptor sobe o proxy dentro do painel. Ele lê o login do Claude Code no Keychain do macOS (na 1ª vez, clique em Permitir sempre) e injeta nas chamadas do worker. O proxy nunca renova o login: quem renova é o Claude Code daqui, senão ele seria deslogado.

Receita completa: ssh-tunnel-shared-claude.md.

Skill carbon-coop: trabalho cooperativo pelo Orca experimental

A mesma ideia do túnel, sem o painel: qualquer sessão do Claude Code vira coordenadora, um servidor seu roda orca-ide serve (só em 127.0.0.1) e é pareado como servidor Orca. Os workers lá usam o Claude Code deste computador pelo proxy local; só o código commitado viaja e o resultado volta como branch coop/<slug>. Depende só de Orca, ssh, git e Node 22+.

# instalar (Claude Code 2.1.275+)
/plugin install carbon-coop --marketplace leolegends/carbon-superagent

# versões anteriores
/plugin marketplace add leolegends/carbon-superagent
/plugin install carbon-coop@carbon-superagent

# usar, na sessão
/carbon-coop connect usuario@host
# "manda a parte X pro servidor" → worker no servidor → branch coop/<slug> volta aqui
/carbon-coop status
/carbon-coop disconnect

Passo a passo animado: página da skill. Guia completo: docs/skills/carbon-coop.md.

Máquinas (UI), carga e carbon worker init

Configurações → Máquinas (admin) lista a frota: nome, tipo, status, última batida, tarefa atual e versão.

Carga

O painel Carga mostra, a cada 5 s, cada máquina (este computador e cada worker) com uma animação do tipo dela — servidor, Mac, Linux, Windows, container ou AgentCore — cujo ritmo segue a CPU, pacotes indo do painel para cada tarefa em execução, CPU, memória, slots, utilização, concluídas, tempo médio e sucesso nas últimas 24 h, a comparação com este computador ("assumiu 67% das entregas · 2.0× mais rápido") e quem entregou. Os workers mandam a telemetria do host junto do claim e do heartbeat.

Na fila e no terminal, um selo diz onde cada tarefa roda agora; se ela passou por mais de uma máquina, o selo ganha ⇄ e mostra a trilha (esta máquina ✗ → vps-sp-01 ●).

Adicionar máquina: como ela chega no painel

O kit (Compose ou Kubernetes) começa pela conexão: IP deste computador (padrão; o kit sai com https://<ip>:3418 e CARBON_PANEL_FINGERPRINT, sem URL pública) ou URL pública. Sem Docker na outra máquina, use carbon join.

O mesmo gerador existe na CLI, no host do painel (grava a máquina direto no banco e imprime o token uma vez):

node bin/carbon.mjs worker init --target compose|k8s|agentcore --out <pasta> \
  --name <nome> --panel-url <url> [--replicas N] [--parallel N] \
  [--executors claude,codex] [--image <imagem>] [--region <região>] [--force]

# worker sem Docker (na mesma máquina, para testar)
CARBON_PANEL_URL=http://127.0.0.1:3417 CARBON_WORKER_TOKEN=cwk_... node bin/carbon.mjs worker

Cluster join (estilo Docker Swarm)

O painel é o manager. Para colocar um servidor para ajudar, gere um token de join e rode um comando nele: o servidor entra no cluster, aparece em Configurações → Máquinas com o selo join e passa a pegar tarefas com Onde rodar: Pool de workers.

# no host do painel
carbon join-token --rotate [--ttl 24h] [--max-uses 3]

# em cada servidor (Node 22.13+, git e Claude Code/Codex logado)
npx carbon join 'https://painel.exemplo.com' --token 'cjt_…' [--name gpu-1]

# ou com Docker (imagem de deploy/worker/Dockerfile); o volume guarda a credencial do nó
docker run -d --name carbon-worker --restart unless-stopped \
  -e CARBON_PANEL_URL='https://painel.exemplo.com' -e CARBON_JOIN_TOKEN='cjt_…' \
  -e ANTHROPIC_API_KEY='…' -v carbon-worker-state:/home/carbon/state carbon-worker:<versão>

• O token de join só serve para entrar: cada servidor recebe uma credencial própria (cwk_), salva com permissão 600. Remover um não afeta os outros.
• Reiniciar o worker reaproveita o mesmo nó. Girar o token barra joins novos; quem já entrou segue.
• Servidor removido para com código 3 e não volta sozinho, mesmo com --restart.
• Opções: validade, máximo de servidores e exigir aprovação (o nó fica "aguardando aprovação" até um admin aprovar).
• Trate o token como senha: quem o tem coloca servidores no cluster e recebe tarefas.

Protocolo

HTTP + JSON, versão 1, Authorization: Bearer cwk_… (máquina) ou ctk_… (tarefa AgentCore). Envelope {success, data, error}, corpo JSON ≤ 1 MB.

Códigos: 400 corpo/query inválido · 401 token inválido · 403 painel não autorizado no container · 408 tempo total no listener · 409 lease_lost descarte a tarefa · 413 corpo, bundle ou estado da tarefa grande · 422 base/resultado não importável · 426 protocolo antigo · 429 rate limit ou long-polls demais.

Referência completa, schemas, diagrama de sequência e checklist para escrever um worker próprio: protocol.md no GitHub.

Variáveis de ambiente

Tabela completa (inclui deploy.sh e configurações do painel): environment.md.

Segurança

• Superfície mínima: só /api/worker/* sai de 127.0.0.1; UI e admin continuam locais.
• Direto por IP: TLS com o certificado próprio do painel, fixado pelo fingerprint no worker; certificado diferente derruba a conexão antes do token ser enviado. Porta aberta no roteador fica exposta à internet (só /api/worker/*, com token): prefira VPN quando puder.
• Tokens: 32 bytes aleatórios, mostrados uma vez, guardados como sha256, revogáveis; nunca em log. Token de tarefa AgentCore é de uso único e vale só para aquela tarefa.
• Limites: rate limit por token (600/min) e por IP, long-polls simultâneos por worker, corpo JSON ≤ 1 MB, 256 conexões no listener (32 por IP), tempo total por requisição (60 s; 30 min no bundle), mesmo 401 para qualquer token inválido.
• Isolamento de ambiente: o worker tira CARBON_WORKER_TOKEN e CARBON_GIT_TOKEN do ambiente; o agente recebe só variáveis permitidas (nenhuma CARBON_*). Clone e TMPDIR são por tarefa, mas o HOME é compartilhado: isolamento real é uma tarefa por container (CARBON_WORKER_PARALLEL=1, o padrão).
• CARBON_GIT_HOSTS: o token git só vai para hosts https:// listados; vazio (padrão) = nunca enviado.
• Sem resolução de DNS: nomes que resolvem para IP privado não são bloqueados. Nunca exponha a porta 3417: o limite por IP confia no X-Forwarded-For definido pelo listener.
• O que nunca sai do painel: banco SQLite, usuários, chaves de integrações, credenciais de modelo/git do painel, credenciais embutidas na URL do origin.
• Permissões: "sempre neste repositório" vira "permitir uma vez" para comandos de shell, interpretador ou rede (bash, python, curl, ssh…).
• AgentCore: Bedrock via IAM role em vez de chave em variável de ambiente; restrinja GetAgentRuntime.

Modelo de ameaça completo: security.md.

Operação

Reinício do painel

Tarefas locais em execução falham no boot; remotas com lease válido continuam e os workers reenviam eventos sem confirmação. Tarefas pool interrompidas durante a importação falham com painel reiniciou durante a entrega.

Cancelamento

Pool: o worker recebe cancel no próximo heartbeat (≤ 20 s no padrão), mata o agente e reporta canceled. AgentCore antes do claim: o painel encerra a sessão na hora.

Permissões e perguntas remotas

Pedidos de permissão aparecem no painel como numa tarefa local — inclusive num alerta fixo no canto de qualquer página, com Permitir/Negar — e o worker espera a resposta (15 min, depois nega). Tarefa marcada Seguir até o final sem pedir permissão aprova sozinha o trabalho comum do projeto; infraestrutura (docker, kubectl, terraform), rede, ações fora do projeto e arquivos sensíveis continuam pedindo, e os bloqueios seguem valendo. Quando o agente faz uma pergunta, a execução termina sem entregar; ao responder, a tarefa volta para a fila do mesmo runtime e recomeça da base com as decisões no prompt.

Merge com conflito

Ao escolher o branch de destino, o card de entrega verifica conflitos (git merge-tree, sem alterar nada) e lista os arquivos. Resolver com o agente e fazer o merge roda a tarefa de novo neste computador, na mesma branch: o agente traz o destino, junta as duas versões sem descartar nenhum lado e roda os testes; o Carbon conclui e faz o merge. Para corrigir o pedido antes, o lápis na fila edita a tarefa e Salvar e rodar de novo.

Limites

Teste de ponta a ponta sem AWS: npm run build && npm run build:worker && npm run e2e:distributed. Mais em operations.md.

Troubleshooting

Lista completa a partir das mensagens do código: troubleshooting.md.

FAQ