Quickstart

Este camino levanta el WhyStack Agent con el entorno de demostración: el catálogo completo respondido desde un fixture, sin una sola credencial tuya, con un incidente plantado que siempre acaba de ocurrir.

Es lo primero que debes hacer en una instalación nueva. Valida la plomería (la imagen corre en tu entorno, el certificado es válido, el túnel es alcanzable) antes de que aprovisiones cualquier credencial. Si algo falla aquí, fallaría igual en la instalación real, solo que con secrets de por medio.

Lo que necesitas

• La dirección de la imagen y la autorización de pull, que WhyStack te envía.
• Una identidad para el Agent: en la mayoría de las instalaciones es un bootstrap token, que tú mismo generas en Onboarding en el control-plane. Si WhyStack te entregó un certificado ya emitido (runner.crt, runner.key, ca.pem), aquí funciona igual. Consulta Identidad y enrollment.
• La URL del túnel (RUNNER_TUNNEL_URL).
• HTTPS de salida hacia el host del túnel. Ningún puerto de entrada.

1. Descarga la imagen

# AWS (ECR)
docker pull <whystack-account>.dkr.ecr.<region>.amazonaws.com/whystack-agent:<version>

# GCP (Artifact Registry)
docker pull <region>-docker.pkg.dev/<whystack-project>/whystack/whystack-agent:<version>

La imagen es multiarquitectura: la misma dirección sirve amd64 y arm64.

El registry es privado. Si el pull falla con no basic auth credentials, todavía no te autenticaste. Son dos comandos, uno por nube, en La imagen › Autenticarse antes del pull.

2. Ejecuta en modo demo

Con un bootstrap token (el camino que la página de Onboarding te entrega listo para ejecutar):

docker run --rm \
  -e RUNNER_TUNNEL_URL=wss://tunnel.whystack.ai:8443 \
  -e RUNNER_ENROLL_URL=https://app.whystack.ai \
  -e RUNNER_ATTESTATION_MODE=bootstrap-token \
  -e RUNNER_BOOTSTRAP_TOKEN=<the token you minted> \
  -e RUNNER_CONNECTORS=demo \
  <image-address>

Con un certificado aprovisionado, si eso es lo que recibiste: pon los tres PEMs en un directorio y móntalo en /certs. El entrypoint los carga por ti, y no hacen falta ni RUNNER_ENROLL_URL ni el token.

docker run --rm \
  -v "$PWD/certs:/certs:ro" \
  -e RUNNER_TUNNEL_URL=wss://tunnel.whystack.ai:8443 \
  -e RUNNER_CONNECTORS=demo \
  <image-address>

Ninguna de tus credenciales entra en ninguno de los dos. demo responde desde un fixture.

El token es de un solo uso

Sirve para un enrollment y expira en una hora. Ejecutar este comando otra vez implica generar otro, lo cual es aceptable en una prueba, y no es así como se ejecuta en producción: consulta Identidad y enrollment.

3. Confirma el boot

Los logs son JSON, una línea por evento:

{"level":"info","message":"boot: liveness","context":"runner","instanceId":"..."}
{"level":"info","message":"enrolled","context":"runner","spiffeId":"spiffe://rootpilot/tenant/<you>/runner"}
{"level":"info","message":"boot: ready","context":"runner","instanceId":"..."}
{"level":"info","message":"hello accepted","context":"runner","sessionId":"..."}

Con un certificado aprovisionado, la segunda línea es using provisioned cert y lleva un notAfter, la fecha en que vence.

hello accepted es la línea que importa: a partir de ahí el Agent está conectado y aparece en la vista Flota del control-plane.

Revisa el tenant en la línea del SPIFFE id

spiffe://rootpilot/tenant/<slug>/runner dice a qué organización se unió este Agent. Es la verificación que vale la pena hacer ahora, porque un token generado en la org equivocada levanta y se conecta, solo que en el lugar equivocado.

Y si usaste un certificado aprovisionado: fíjate en el notAfter. No se renueva solo; cuando vence, el Agent deja de conectarse. Anota la fecha. El tema se trata en Identidad y enrollment.

Si ves disconnected, reconnecting en bucle, el Agent está arriba y el túnel no: revisa la URL, el egress y la validez del certificado. Consulta troubleshooting.

Los tres modos de datos

RUNNER_CONNECTORS decide de dónde vienen las respuestas. Equivocarse aquí es la causa más común de “lo instalé y las tools devuelven basura”.

Modo	Credenciales	Qué responde
synthetic	ninguna	Default de la imagen. Un seed de 3 operaciones cuyas formas no coinciden con las de los connectors reales. Sirve para probar el boot y el handshake, no para ejercitar las tools.
demo	ninguna	El catálogo completo (~190 ops) desde un fixture, con time-shift. Es el modo de este quickstart.
real	las tuyas	Las APIs reales. Es el modo de producción.

synthetic es el modo por defecto, y no es un mock de las tools

Si omites RUNNER_CONNECTORS, caes en synthetic. Y el Agent levanta, se conecta y funciona, respondiendo datos fabricados. Es la falla más silenciosa de la instalación. Para una demo sin credenciales, el modo es demo; para usarlo de verdad, es real.

Siguiente paso

• Para instalar de verdad: Deploy en producción.
• Para conectar tus fuentes: Modos de connector y Credenciales por connector.