Claude Code Headless: Comprueba tu despliegue desde la terminal

El modo headless de Claude Code ejecuta un prompt desde tu terminal con claude -p y sale cuando termina la tarea. Puedes canalizar datos, guardar la respuesta y llamarlo desde un script. Esta guía lo utiliza para explicar las comprobaciones de despliegue: un endpoint de estado, una cotización y un informe que tu script puede verificar.

El ejemplo detecta un fallo común: /healthz devuelve HTTP 200 mientras que una ruta real de la aplicación devuelve 503. Obtendrás una demo reproducible, un informe JSON y un código de salida distinto de cero cuando falle la comprobación de la aplicación.

Empieza con un comando no interactivo

Con Claude Code instalado y con la sesión iniciada, ejecuta:

claude -p "Explain what an HTTP 503 response tells me in two sentences." \
  --tools ""

-p significa imprimir el resultado y salir. --tools "" desactiva las herramientas integradas para esta pregunta. Claude puede responder desde el prompt sin leer tu repositorio ni ejecutar un comando de shell. La referencia de la CLI de Claude Code enumera las flags disponibles.

Para una comprobación de despliegue, proporciona al modelo las observaciones que tu script ya ha recopilado. Esto hace que cada petición HTTP y condición de aprobación sea fácil de inspeccionar. También mantiene las credenciales de despliegue fuera de la entrada del modelo.

Qué necesitas

Usa Python 3.10 o superior, una instalación actual de Claude Code y una cuenta autenticada. La demo utiliza la biblioteca estándar de Python, por lo que no hay paquetes de Python que instalar. Ejecuta los ejemplos de shell en Bash o Zsh en macOS o Linux.

Comprueba la CLI instalada y su estado de autenticación:

claude --version
claude auth status

Si una petición falla porque la sesión guardada ha caducado, ejecuta claude auth login y vuelve a intentarlo. Puede existir un inicio de sesión guardado incluso cuando la siguiente petición a la API no pueda actualizarlo.

Para las comprobaciones alojadas opcionales, instala Lizard CLI e inicia sesión en tu propio proyecto. Si aún necesitas desplegar tu aplicación, sigue primero Desplegar desde Claude Code.

Descarga el ejemplo e inicia la demo

Crea una nueva carpeta y descarga los seis archivos. Léelos antes de ejecutarlos. La demo acepta peticiones GET y no guarda datos de clientes.

mkdir claude-deployment-check
cd claude-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done
python3 demo.py --port 8787

Deja esa terminal en ejecución. En otra terminal, cambia a la misma carpeta. La demo expone /healthz y /api/quote?quantity=3. Cada artículo cuesta 1.200 centavos; una cotización para tres artículos debe devolver currency: USD y total_cents: 3600.

Estas son rutas de demostración. Para tu propia aplicación, edita las rutas y los campos esperados en collect.py y gate.py. Elige una operación pequeña que un usuario realmente necesite: leer un registro inicial, calcular un precio o recuperar un documento guardado. Una ruta que solo devuelve "OK" no puede verificar esas operaciones.

Recopila resultados de las comprobaciones antes de preguntar a Claude

python3 collect.py http://127.0.0.1:8787 > evidence.json

El recolector realiza dos peticiones con un tiempo de espera de cinco segundos para cada una. Rechaza redirecciones, JSON no válido y respuestas mayores de 64 KiB. Comprueba tanto el estado HTTP como los campos JSON esperados. Registra la hora, los valores esperados y los resultados de la comprobación; no copia texto de respuesta arbitrario en el prompt.

Esa última elección es importante cuando un endpoint contiene texto del usuario. Un mensaje de soporte o una fila de base de datos puede contener instrucciones dirigidas a un agente. Este ejemplo proporciona a Claude un pequeño conjunto de campos medidos para explicar.

El recolector sale con éxito cuando escribe los datos, incluidos los datos de una comprobación fallida. El script de comprobación final determina si el trabajo se aprueba. Mantén esos dos significados separados en tu automatización.

Pide un informe estructurado

Ejecuta esto desde la carpeta que contiene los archivos descargados:

claude --safe-mode -p \
  "Explain the evidence on stdin. Use no tools. Copy its verdict. List the names of failed checks in failed_checks. Give a short summary and one next_step. Do not infer a root cause from HTTP status alone." \
  --tools "" \
  --no-session-persistence \
  --output-format json \
  --json-schema "$(cat report.schema.json)" \
  < evidence.json > claude-result.json

El ejemplo utiliza --safe-mode para desactivar personalizaciones como hooks, plugins y servidores MCP durante esta tarea de informe. Utiliza el inicio de sesión de la cuenta existente. Consulta la ayuda de tu versión instalada si no reconoce la flag.

La respuesta de Claude tiene un objeto de resultado externo. Cuando proporcionas el esquema, el informe se encuentra dentro de structured_output. El objeto externo también contiene metadatos de ejecución y un campo is_error. Una respuesta JSON simple y una respuesta restringida por esquema tienen propósitos diferentes; analiza el campo que solicitó tu comando.

El esquema pide cuatro campos:

La documentación de ejecución programática describe estos formatos de salida. Una forma JSON válida no establece si la explicación es correcta, por lo que el wrapper comprueba el informe frente a los resultados medidos.

Ejecuta la comprobación completa

run.py recopila datos nuevos, llama a Claude con un tiempo de espera de proceso de 180 segundos, extrae el informe y lo comprueba. Asigna a cada ejecución un nuevo directorio de salida:

python3 run.py claude http://127.0.0.1:8787 runs/healthy

El directorio contiene evidence.json, claude-result.json, report.json y stderr.log. Conserva el resultado sin procesar al depurar un fallo; un error de autenticación puede aparecer en el resultado en stdout.

El wrapper utiliza tres códigos de salida:

El código 0 del proceso de Claude significa que la ejecución del agente se completó. El wrapper toma la decisión por separado sobre la aplicación. Un informe no válido no puede convertir una comprobación HTTP fallida en un trabajo exitoso.

Reproduce un fallo que una comprobación de estado pasa por alto

Inicia una segunda demo en otra terminal:

python3 demo.py --port 8788 --broken

Luego ejecuta:

python3 run.py claude http://127.0.0.1:8788 runs/broken

La segunda demo sigue respondiendo a /healthz con HTTP 200. Su ruta de cotización devuelve HTTP 503. Por lo tanto, los datos registran fail, con quote como la comprobación fallida. Con una respuesta válida de Claude, el wrapper sale con 1.

También puedes probar las comprobaciones HTTP y la lógica de validación sin llamar a un modelo:

python3 verify.py

Esto comprueba las demos sanas y rotas, luego verifica que el script de validación rechaza un informe de éxito falso y datos incompletos. No utiliza créditos de Claude.

Aplica la comprobación a una aplicación en Lizard

Elige la URL de la aplicación de tu proyecto. Inspecciona el contexto actual del proyecto y el estado del servicio con Lizard CLI:

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

lizard status muestra la vinculación de la carpeta local con un proyecto. lizard ps lee el estado del servicio para el proyecto seleccionado. Los logs JSON devuelven una instantánea limitada y salen; no siguen rastreando el servicio.

Usa la URL pública del servicio con el mismo comprobador después de adaptar las dos aserciones de ruta a tu aplicación. Si alojas la propia demo suministrada, vincúlala a 0.0.0.0 y configura el puerto del servicio para que coincida. Los ejemplos locales se vinculan a 127.0.0.1.

Lee los logs alrededor de la hora de comprobación registrada cuando falle una ruta. Un HTTP 503 por sí solo no puede decirte si la causa fue una conexión a la base de datos, una dependencia o el código de la aplicación. Revisa y oculta secretos y datos personales de cualquier log antes de añadirlo a un prompt del modelo.

Para las aplicaciones que dependen de datos almacenados, añade una prueba con un registro conocido. La guía de Postgres MCP explica el acceso a bases de datos con alcance limitado, y la guía de Redis MCP cubre las lecturas restringidas de Redis. Usa datos de prueba y credenciales adecuadas para la comprobación.

Modo headless, autenticación y trabajos desatendidos

El modo headless describe cómo ejecutas el comando. No crea un inicio de sesión desatendido ni elimina los permisos de las herramientas. Para un trabajo programado, prepara la autenticación en el runner y usa un tiempo de espera explícito.

Claude también ofrece --bare, que omite gran parte del contexto de inicio normal. Su ruta de autenticación de Anthropic utiliza ANTHROPIC_API_KEY o un ayudante de clave API configurado; no lee las credenciales OAuth de suscripción. Por lo tanto, nuestro ejemplo de inicio de sesión de cuenta utiliza --safe-mode. Revisa la documentación actual antes de mover el trabajo a CI, donde la configuración de autenticación puede diferir.

Para el progreso en vivo, Claude soporta --output-format stream-json --verbose. Cada línea es un evento. Usa json simple cuando solo necesites un resultado final, como hace este ejemplo. Evita reanudar una conversación antigua para una comprobación de despliegue independiente; cada ejecución debe usar observaciones nuevas.

Solución de problemas

Alcance de la prueba y siguiente paso

El 28 de septiembre de 2026 ejecutamos las pruebas locales HTTP y de validación de informes con Python 3.12.10. Cubrieron respuestas correctas, un fallo en la ruta de cotización, un informe de éxito falso y datos incompletos. Contrastamos las opciones con Claude Code 2.1.259, Lizard CLI 4.0.8 y la documentación oficial. La respuesta del modelo Claude no formó parte de las pruebas completadas; el comportamiento descrito se basa en el formato de salida documentado. Estas pruebas de ejemplo no confirman el funcionamiento de una aplicación en producción.

Para el mismo patrón con eventos JSONL y un archivo de informe final separado, consulta las comprobaciones de despliegue de Codex Exec. Para poner tu propia aplicación en línea, sigue la guía de despliegue de Claude Code, luego añade una comprobación para la operación que más necesiten tus usuarios.