Despliegue de Claude Code: guía para producción

El despliegue de Claude Code solo resulta fiable cuando el agente puede distinguir entre “solicitud aceptada” y “producción en buen estado”. Dockup proporciona esa capa de despliegue mediante una CLI diseñada para procesos automatizados: JSON estructurado, códigos de salida reales del proceso y un modo --wait que permanece conectado hasta que el despliegue alcanza un estado terminal.

Esta guía lleva un repositorio desde el trabajo local hasta una release de producción verificada. También define los permisos que debe recibir Claude Code, las evidencias que debe devolver y el punto en el que una persona debe aprobar una acción destructiva.

¿Qué necesita Claude Code antes de desplegar en producción?

Un coding agent no debería empezar adivinando el nombre de un servicio ni haciendo clic en un dashboard. Dale un contrato operativo limitado: descubrir el destino exacto, realizar un único cambio previsto, esperar el resultado e informar con evidencias legibles por máquinas.

Los requisitos básicos son sencillos:

Requisito	Por qué es importante	Verificación
Node.js 18 o posterior	Lo requiere el paquete Dockup CLI	node --version
Cuenta de Dockup	Es propietaria de los workspaces, servicios y bases de datos	Inicia sesión en app.dockup.ai
Repositorio de Git	Es la fuente de compilación del servicio	Confirma la URL remota y la rama
Token de API	Permite la autenticación no interactiva	dockup whoami --json
Endpoint de health o puerto en escucha	Controla el cambio blue-green	dockup health ... --json

Define el límite de producción antes de que actúe el agente. Claude Code puede crear un servicio, establecer configuración no secreta, activar un deploy, consultar logs y proponer un rollback. No debe eliminar un servicio, borrar una base de datos ni depurar la configuración sin la aprobación explícita de una persona.

Dockup refuerza ese límite. Los comandos destructivos se niegan a continuar sin --yes y devuelven un error estructurado needs_confirm en lugar de interpretar la falta de confirmación como una invitación a improvisar. Para consultar una política más amplia, usa las barreras de protección para agentes de IA en producción.

¿Cómo se instala la skill de Claude Code y se autentica de forma segura?

Instala la CLI, instala la skill incluida y verifica que la skill coincide con el binario instalado:

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

El instalador escribe la skill canónica en ~/.agents/skills/dockup/ y crea un enlace a ella en el directorio de skills de Claude Code. Como la skill se distribuye en el mismo paquete npm que la CLI, dockup update actualiza ambos componentes. Claude Code no tiene que depender de una referencia de comandos copiada que podría describir flags no compatibles con su binario local.

Usa un token en una variable de entorno para las sesiones autónomas:

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

Una respuesta correcta identifica la cuenta e informa de tokenSource como env. No pegues el token en un prompt, no lo guardes en el repositorio ni lo muestres en un log de CI. Los valores secretos almacenados en Dockup aparecen enmascarados al volver a leer la configuración.

La referencia completa de Dockup CLI es la superficie de comandos de referencia. Con 135 comandos, Claude Code debería consultar la referencia actual y la skill incluida en el paquete, en lugar de depender de flags recordados.

Como la skill se distribuye dentro del paquete de la CLI, dockup update actualiza el ejecutable y sus instrucciones conjuntamente. Esta alineación de versiones es más segura que copiar una lista de comandos en un prompt de larga duración.

¿Cómo crea un servicio desde Git Dockup CLI?

Primero, pide al agente que identifique el workspace y evita construir slugs a partir de nombres visibles. Los destinos existentes se devuelven mediante:

dockup services --json

Para un repositorio que nunca se ha desplegado, una única transacción puede crear el servicio, desplegarlo, esperar a que finalice y vincular el directorio actual:

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

Cuando el repositorio contiene un Dockerfile, Dockup lo utiliza. Si no lo contiene, Dockup recurre a Nixpacks para detectar automáticamente cómo realizar la compilación. La elección se explica en Nixpacks frente a Dockerfile, incluidos los casos en los que las instrucciones de compilación explícitas compensan el coste de mantenimiento.

Antes de volver a intentar la creación después de una sesión interrumpida, ejecuta de nuevo dockup services --json e inspecciona el destino exacto. Si el servicio ya existe, continúa desde su estado en lugar de emitir otra solicitud de creación.

Una vez vinculado, los comandos de ese repositorio pueden resolver el destino desde .dockup, pero los runbooks de producción deberían seguir registrando el valor completo project/service. El descubrimiento es el límite seguro entre una acción anterior cuyo resultado no está claro y una nueva modificación de producción.

¿Cómo se deben preparar las variables de entorno, las bases de datos y los health checks?

Mantén la configuración ordinaria separada de los secretos. Claude Code puede establecer un valor público de runtime y un secreto enmascarado sin mostrar después los valores secretos almacenados:

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

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

Los cambios de entorno se aplican en el siguiente despliegue. Es intencionado: un contenedor en ejecución conserva su entorno de proceso actual hasta que se sustituye. El patrón operativo completo se describe en variables de entorno y secretos.

Si la aplicación necesita una base de datos PostgreSQL gestionada, créala en el workspace seleccionado y consulta sus detalles mediante los comandos documentados para bases de datos:

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

La red privada puede proporcionar posteriormente a los servicios y las bases de datos nombres de host estables <slug>.internal dentro de un mismo proyecto. No hagas que el agente invente una URL de base de datos; utiliza la información de conexión devuelta por Dockup y guárdala como secreto.

Configura un readiness gate antes de la primera release de producción importante:

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

Dockup realiza un despliegue blue-green sin downtime y solo dirige el tráfico a la nueva versión después de que el health gate se supera correctamente. La arquitectura se analiza en despliegues sin downtime.

¿Cómo despliega Claude Code y demuestra que ha tenido éxito?

Usa --wait; no permitas que el agente interprete “despliegue en cola” como “aplicación en ejecución”:

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

El timeout predeterminado de espera es de 900 segundos. Si todo va bien, el comando termina con 0 y devuelve el estado terminal, la duración, el ID del despliegue y la URL. Si falla la compilación, termina con un código distinto de cero y code:"deploy_failed". Si la operación sigue ejecutándose cuando vence el timeout, termina con un código distinto de cero y code:"deploy_timeout".

Una instrucción útil para Claude Code es: “Trata el código de salida del proceso como el resultado principal; después resume los campos JSON”. Así se evita un lenguaje excesivamente optimista cuando la plataforma ya ha devuelto un error.

Después de un resultado correcto, recopila tres señales independientes:

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

status confirma el estado del servicio y del último despliegue. uptime devuelve estadísticas de monitorización minuto a minuto, incluidos el tiempo medio de respuesta y el p95. security muestra el último CVE de la imagen y el análisis de configuración. Estas comprobaciones complementan las prácticas de seguridad a nivel de aplicación; no sustituyen a las pruebas de la aplicación.

¿Qué debe hacer Claude Code cuando falla producción?

Distingue entre un fallo de compilación y un fallo de runtime. Un fallo de compilación requiere el último build log:

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

Un contenedor que se ha compilado, pero falla después del arranque, requiere la salida de runtime:

dockup logs production/my-api --json

Para supervisar una compilación conservando lotes legibles por máquinas, utiliza el modo follow con NDJSON:

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

El comando se detiene cuando el despliegue alcanza un estado terminal y termina con un código distinto de cero si ha fallado. Claude Code puede transmitir el progreso sin inventar un bucle de polling.

Si la release actual no está sana y debe volver a ejecutarse un despliegue anterior conocido, consulta el historial y utiliza su ID exacto:

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

El agente debe informar de qué ID de despliegue ha seleccionado y por qué. Un rollback es una decisión operativa, no un sustituto de comprender el fallo. Conserva el build log, el runtime log, el código de salida y el registro de auditoría para que el incidente pueda reconstruirse.

Un informe terminado de despliegue de Claude Code debe incluir el destino, el commit o la rama, el ID de despliegue, el estado terminal, la URL, el tiempo transcurrido, el resultado del health check y cualquier riesgo pendiente. Estas evidencias convierten una acción autónoma en un cambio de producción revisable.

Define un contrato de finalización para producción

Antes de empezar, incluye el contrato de finalización esperado en la tarea. Una solicitud útil sería: despliega el repositorio vinculado en production/my-api; espera un resultado terminal; no elimines, depures ni transfieras nada; si falla, devuelve el código de error y las últimas 60 líneas relevantes del build log; si tiene éxito, devuelve el estado, la URL, el ID de despliegue, la duración y las evidencias de health.

Esta redacción proporciona a Claude Code un objetivo acotado y un esquema de respuesta. También evita que el agente cambie “para ayudar” infraestructura no relacionada cuando falla la release. El agente puede proponer una corrección independiente, pero la acción de producción sigue siendo atribuible a una única solicitud.

Para releases repetidas, conserva un pequeño registro de releases en el repositorio o en el sistema de gestión de cambios. Registra el destino, la rama de origen, la ruta de health esperada, el timeout habitual y la acción de recuperación aprobada. Un despliegue de Claude Code es más seguro cuando la siguiente sesión no tiene que reconstruir estos datos a partir del historial del chat.

Verifica el límite de la cuenta antes de la primera escritura

Los workspaces son límites de propiedad y facturación. Pide a Claude Code que muestre whoami, enumere los servicios e indique el workspace seleccionado antes de modificar nada. El plan Pro cuesta 20 $ al mes e incluye 20 $ de crédito de uso, por lo que es el plan de pago recomendado; todos los planes de pago permiten workspaces, bases de datos y despliegues ilimitados, mientras que el uso de CPU, RAM y disco se mide por minuto con cargo al saldo del plan.

Este modelo de precios no cambia la regla de seguridad: un agente debe revisar el uso y el alcance del destino antes de escalar o crear recursos adicionales. El informe de producción debe distinguir el plan de suscripción del consumo real medido.

Lleva el flujo de trabajo a producción

Instala la skill en el mismo entorno donde se ejecutará Claude Code, verifica la autenticación y empieza con un servicio de bajo riesgo cuyo endpoint de health ya conozcas.

npm install -g dockup-cli
dockup skill install

El primer comando instala la CLI. El segundo instala la skill de Dockup compatible con Claude Code y Codex. Empieza gratis en app.dockup.ai.

Preguntas frecuentes

¿Puede Claude Code desplegar directamente en producción con Dockup?

Sí. Instala la skill de Dockup, proporciona un DOCKUP_TOKEN con el alcance adecuado, resuelve el destino exacto project/service y ejecuta el comando de deploy con --wait y --json.

¿Por qué debe usar Claude Code --wait?

Sin --wait, una respuesta correcta solo significa que el despliegue se ha puesto en cola. Con --wait, Dockup termina con 0 únicamente después de un resultado correcto y devuelve errores estructurados deploy_failed o deploy_timeout en los demás casos.

¿Puede Claude Code ver los valores secretos almacenados?

Dockup enmascara los valores secretos en la salida. El agente puede establecer o sustituir un secreto, pero la lectura de la configuración de entorno no devuelve su valor almacenado.

¿Qué ocurre cuando un repositorio no tiene Dockerfile?

Dockup utiliza Nixpacks para detectar y compilar la aplicación automáticamente. Si existe un Dockerfile en el repositorio, este tiene prioridad.

¿Cómo puede Claude Code recuperarse de una release defectuosa?

Debe inspeccionar los logs de compilación y runtime, consultar el historial de despliegues y volver a ejecutar un despliegue anterior conocido con dockup rollback usando el ID de despliegue exacto.