Deploy do Claude Code: guia de produção

O deploy do Claude Code só se torna confiável quando o agente consegue distinguir entre “solicitação aceita” e “produção saudável”. O Dockup fornece essa camada de deploy por meio de uma CLI projetada para chamadas de máquina: JSON estruturado, códigos de saída reais do processo e um modo --wait que permanece conectado até o deploy atingir um estado terminal.

Este guia leva um repositório do trabalho local até uma release de produção verificada. Ele também define as permissões que o Claude Code deve receber, as evidências que deve retornar e o ponto em que uma pessoa precisa aprovar uma ação destrutiva.

O que o deploy do Claude Code precisa antes da produção?

Um agente de programação não deve começar tentando adivinhar o nome de um serviço ou navegando por um dashboard. Dê a ele um contrato operacional restrito: descobrir o destino exato, fazer uma única alteração pretendida, aguardar o resultado e comunicar evidências legíveis por máquina.

Os pré-requisitos básicos são simples:

Requisito	Por que é importante	Verificação
Node.js 18 ou mais recente	Obrigatório para o pacote Dockup CLI	node --version
Conta do Dockup	É proprietária dos workspaces, serviços e bancos de dados	Faça login em app.dockup.ai
Repositório Git	Fonte do build do serviço	Confirme a URL remota e a branch
Token de API	Autenticação não interativa	dockup whoami --json
Endpoint de health ou porta em escuta	Controla a virada blue-green	dockup health ... --json

Defina o limite de produção antes de o agente agir. O Claude Code pode criar um serviço, definir configurações não secretas, iniciar um deploy, consultar logs e propor um rollback. Ele não deve excluir um serviço, remover um banco de dados nem eliminar configurações sem aprovação explícita de uma pessoa.

O Dockup reforça esse limite. Comandos destrutivos se recusam a prosseguir sem --yes e retornam um erro estruturado needs_confirm, em vez de tratar a ausência de confirmação como um convite para improvisar. Para uma política mais abrangente, consulte as proteções de produção para agentes de IA.

Como instalar a skill do Claude Code e autenticar com segurança?

Instale a CLI, instale a skill incluída e verifique se ela corresponde ao binário instalado:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

O instalador grava a skill canônica em ~/.agents/skills/dockup/ e cria um link para ela no diretório de skills do Claude Code. Como a skill é distribuída no mesmo pacote npm que a CLI, dockup update atualiza ambos. O Claude Code não precisa depender de uma referência de comandos copiada que talvez descreva flags não compatíveis com o binário local.

Use um token em variável de ambiente para sessões autônomas:

export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

Uma resposta bem-sucedida identifica a conta e informa tokenSource como env. Não cole o token em um prompt, não faça commit dele no repositório nem o exiba em um log de CI. Os valores secretos armazenados no Dockup são mascarados quando a configuração é consultada novamente.

A referência completa da Dockup CLI é a superfície de comandos oficial. Com 135 comandos, o Claude Code deve consultar a referência atual e a skill empacotada, em vez de depender de flags memorizadas.

Como a skill é distribuída dentro do pacote da CLI, dockup update atualiza o executável e suas instruções em conjunto. Esse alinhamento de versões é mais seguro do que copiar uma lista de comandos para um prompt de longa duração.

Como a Dockup CLI cria um serviço a partir do Git?

Primeiro, peça ao agente para identificar o workspace e evite construir slugs a partir de nomes de exibição. Os destinos existentes são retornados por:

dockup services --json

Para um repositório que nunca foi submetido a deploy, uma única transação pode criar o serviço, fazer o deploy, aguardar a conclusão e vincular o diretório atual:

dockup create my-api \
  --repo https://github.com/acme/my-api \
  --project production \
  --deploy \
  --wait \
  --link \
  --json

Quando o repositório contém um Dockerfile, o Dockup o utiliza. Sem um, o Dockup recorre ao Nixpacks para detectar automaticamente o build. A escolha é explicada em Nixpacks vs Dockerfile, incluindo quando instruções de build explícitas compensam o custo de manutenção.

Antes de tentar criar novamente após uma sessão interrompida, execute dockup services --json outra vez e inspecione o destino exato. Se o serviço já existir, continue a partir do status dele, em vez de emitir outra solicitação de criação.

Depois de vinculado, os comandos nesse repositório podem resolver o destino a partir de .dockup, mas os runbooks de produção ainda devem registrar o valor completo de project/service. A descoberta é o limite seguro entre uma ação anterior incerta e uma nova alteração em produção.

Como preparar variáveis de ambiente, bancos de dados e verificações de integridade?

Mantenha a configuração comum separada dos secrets. O Claude Code pode definir um valor público de runtime e um secret mascarado sem exibir posteriormente os valores secretos armazenados:

dockup env set NODE_ENV=production \
  -s production/my-api \
  --json

dockup env set API_KEY="$API_KEY" \
  --secret \
  -s production/my-api \
  --json

As alterações de ambiente são aplicadas no próximo deploy. Isso é intencional: um container em execução mantém seu ambiente de processo atual até ser substituído. O padrão operacional completo é abordado em variáveis de ambiente e secrets.

Se a aplicação precisar de um banco de dados PostgreSQL gerenciado, crie-o no workspace selecionado e consulte seus detalhes por meio dos comandos de banco de dados documentados:

dockup db create --name main-db --type postgresql --json
dockup db list --json

A rede privada pode posteriormente fornecer aos serviços e bancos de dados hostnames estáveis no formato <slug>.internal dentro de um mesmo projeto. Não peça ao agente para inventar uma URL de banco de dados; use as informações de conexão retornadas pelo Dockup e armazene-as como um secret.

Configure um gate de readiness antes da primeira release importante em produção:

dockup health production/my-api \
  --path /healthz \
  --interval 5 \
  --retries 5 \
  --json

O Dockup realiza deploy blue-green sem downtime e só direciona o tráfego para a nova versão depois que o gate de health é aprovado. A arquitetura é explorada em deploys sem downtime.

Como o Claude Code faz o deploy e comprova que ele foi bem-sucedido?

Use --wait; não deixe o agente interpretar “deploy enfileirado” como “aplicação em execução”:

dockup deploy production/my-api --wait --json

O timeout padrão de espera é de 900 segundos. Em caso de sucesso, o comando termina com 0 e retorna o status terminal, a duração, o ID do deploy e a URL. Se o build falhar, ele termina com um código diferente de zero e code:"deploy_failed". Se a operação ainda estiver em execução quando o timeout for atingido, ele termina com um código diferente de zero e code:"deploy_timeout".

Uma instrução útil para o Claude Code é: “Trate o código de saída do processo como o resultado principal; depois, faça um resumo dos campos JSON.” Isso evita uma linguagem otimista quando a plataforma já retornou uma falha.

Após o sucesso, colete três sinais independentes:

dockup status production/my-api --json
dockup uptime production/my-api --hours 24 --json
dockup security production/my-api --json

status confirma o serviço e o estado do deploy mais recente. uptime retorna estatísticas de monitoramento minuto a minuto, incluindo o tempo médio de resposta e o p95. security mostra a CVE mais recente da imagem e a verificação de configuração. Essas verificações complementam as práticas de segurança no nível da aplicação; não substituem os testes da aplicação.

O que o Claude Code deve fazer quando a produção falhar?

Separe falhas de build de falhas de runtime. Um build malsucedido exige o log de build mais recente:

dockup logs production/my-api --build --json

Um container que foi compilado, mas falha após a inicialização, exige a saída de runtime:

dockup logs production/my-api --json

Para acompanhar um build preservando lotes legíveis por máquina, use o modo follow com NDJSON:

dockup logs production/my-api --build -f --json

O comando para quando o deploy atinge um estado terminal e termina com um código diferente de zero se houver falha. O Claude Code pode transmitir o progresso sem criar um loop de polling por conta própria.

Se a release atual estiver unhealthy e um deploy anterior conhecido precisar ser executado novamente, liste o histórico e use o ID exato:

dockup deployments production/my-api -n 20 --json
dockup rollback <deploymentId> production/my-api --json

O agente deve informar qual ID de deploy selecionou e por quê. Rollback é uma decisão operacional, não um substituto para compreender a falha. Preserve o log de build, o log de runtime, o código de saída e o registro de auditoria para que o incidente continue sendo reconstruível.

Um relatório final de deploy do Claude Code deve incluir o destino, o commit ou a branch, o ID do deploy, o status terminal, a URL, o tempo decorrido, o resultado do health check e qualquer risco pendente. Essas evidências transformam uma ação autônoma em uma alteração de produção passível de revisão.

Defina um contrato de conclusão para produção

Antes de começar, inclua no task o contrato de conclusão esperado. Uma solicitação útil é: faça o deploy do repositório vinculado em production/my-api; aguarde um resultado terminal; não exclua, elimine nem transfira nada; em caso de falha, retorne o código de erro e as 60 linhas finais relevantes do log de build; em caso de sucesso, retorne o status, a URL, o ID do deploy, a duração e as evidências de health.

Essa formulação fornece ao Claude Code um objetivo delimitado e um schema de relatório. Ela também impede que o agente altere “prestativamente” uma infraestrutura não relacionada quando a release falhar. O agente pode propor uma correção separada, mas a ação em produção continua atribuível a uma única solicitação.

Para releases recorrentes, mantenha um pequeno registro de releases no repositório ou no sistema de gerenciamento de mudanças. Registre o destino, a branch de origem, o path de health esperado, o timeout normal e a ação de recuperação aprovada. Um deploy do Claude Code é mais seguro quando a sessão seguinte não precisa reconstruir esses fatos a partir do histórico do chat.

Verifique o limite da conta antes da primeira gravação

Os workspaces são limites de propriedade e cobrança. Peça ao Claude Code para exibir whoami, listar os serviços e informar o workspace selecionado antes de alterar qualquer coisa. O plano Pro custa US$ 20 por mês, com US$ 20 em créditos de uso, e é o plano pago recomendado; todos os planos pagos permitem workspaces, bancos de dados e deploys ilimitados, enquanto o uso de CPU, RAM e disco é medido por minuto em relação ao saldo do plano.

Esse modelo de preços não altera a regra de segurança: um agente deve inspecionar o uso e o escopo do destino antes de escalar ou criar recursos adicionais. O relatório de produção deve distinguir o plano de assinatura do consumo efetivamente medido.

Coloque o fluxo em produção

Instale a skill no mesmo ambiente em que o Claude Code será executado, verifique a autenticação e comece com um serviço de baixo risco cujo endpoint de health já seja conhecido.

npm install -g dockup-cli
dockup skill install

O primeiro comando instala a CLI. O segundo instala a skill correspondente do Dockup para o Claude Code e o Codex. Comece gratuitamente em app.dockup.ai.

FAQ

O Claude Code pode fazer deploy diretamente em produção com o Dockup?

Sim. Instale a skill do Dockup, forneça um DOCKUP_TOKEN com escopo definido, resolva o destino exato de projeto/serviço e execute o comando de deploy com --wait e --json.

Por que o Claude Code deve usar --wait?

Sem --wait, uma resposta bem-sucedida significa apenas que o deploy foi enfileirado. Com --wait, o Dockup termina com 0 somente após o sucesso e retorna erros estruturados deploy_failed ou deploy_timeout nos demais casos.

O Claude Code consegue ver os valores secretos armazenados?

O Dockup mascara os valores secretos na saída. O agente pode definir ou substituir um secret, mas a leitura da configuração de ambiente não retorna o valor secreto armazenado.

O que acontece quando um repositório não tem Dockerfile?

O Dockup usa o Nixpacks para detectar e compilar a aplicação automaticamente. Um Dockerfile do repositório tem precedência quando está presente.

Como o Claude Code pode se recuperar de uma release problemática?

Ele deve inspecionar os logs de build e runtime, listar o histórico de deploys e executar novamente um deploy anterior conhecido usando dockup rollback com o ID exato do deploy.