Arquitectura

Lizard organiza todo lo que despliegas en una jerarquía de tres niveles, además de addons gestionados que se adjuntan a un proyecto.

workspace
└── project
    ├── service (app)          ← built from GitHub or an upload
    ├── service (worker)       ← background job, no HTTP port
    └── addons
        ├── postgres
        ├── redis
        └── s3

Espacio de trabajo

Un workspace es el nivel de cuenta u organización. Perteneces al menos a uno, y la facturación, los miembros y los proyectos dependen de él. Lista aquellos a los que tienes acceso:

lizard workspace list

Muchos comandos aceptan -w, --workspace <ws> para distinguir proyectos cuando el mismo nombre de proyecto existe en más de un workspace. El propietario puede limitar cuántos sandboxes ejecuta un workspace a la vez y cuánta CPU, memoria y disco usa con lizard workspace limits (consulta lizard workspace).

Proyecto

Un proyecto agrupa servicios y addons relacionados dentro de un workspace. Tu directorio de trabajo queda vinculado a un proyecto, y ese vínculo (almacenado en ~/.lizard/config.json) indica a la CLI qué proyecto debe usar.

lizard init --name my-project   # create or select a project, link the cwd
lizard link --project my-project  # link to an existing project
lizard status                   # show the current directory's link
lizard unlink                   # remove the link
lizard project list             # all projects in the workspace

Una carpeta que no has enlazado usa el proyecto predeterminado de tu cuenta: el proyecto más antiguo de tu workspace personal, <username>'s Project en una cuenta nueva. lizard up, lizard add, lizard sandbox create y los demás comandos de proyecto van ahí, salvo que enlaces la carpeta o pases --project.

Consejo: Usa el nombre del repositorio o del directorio para el proyecto, y nombres de tipo app (api, worker, web) para los servicios.

Servicio

Un servicio es una sola unidad desplegable. Su origen es uno de estos:

• github: un repositorio de GitHub conectado. Los pushes a la rama seguida vuelven a desplegar automáticamente.
• upload: un tarball subido con lizard up.

Cada servicio se ejecuta en su propio pod aislado con una política de red de denegación por defecto, un dominio <name>-<suffix>.onlizard.com generado (los servicios más antiguos conservan <words>.<region>.onlizard.com) y TLS automático. Tú aportas el contenedor y Lizard lo ejecuta. Este modelo se llama container as a service, y el blog explica de qué sigues teniendo que ocuparte. Inspecciona y gestiona servicios con:

lizard ps                       # list services with status + URL
lizard service show             # full config as JSON
lizard service set <svc> --set <field>=<value>
lizard service rename <new-name> --service <svc>
lizard service delete --service <svc>

Para detener un servicio sin borrarlo, usa lizard pause; para que duerma cuando no recibe tráfico, usa lizard sleep.

Los campos de configuración del servicio son planos y se asignan 1:1 al esquema de la API (p. ej. repoUrl, branch, buildCommand, startCommand, containerPort, rootDirectory). No existe anidamiento de build.* / deploy.*. Consulta lizard service para ver la lista completa.

Servicios app vs. worker

Por defecto, un servicio es una app HTTP que escucha en un puerto (3000 por defecto) y se sirve en su dominio. Un servicio que no escucha en un puerto, como un consumidor de colas, reconciliador o bucle de sondeo, debe ejecutarse en modo worker configurando containerPort=0. Los workers omiten la inyección de puerto, la comprobación de accesibilidad del puerto y el registro en el balanceador de carga.

Addons gestionados

Los addons son Managed Postgres, Managed Redis y Managed Object Storage (compatible con S3) que aprovisionas por proyecto:

lizard add postgres redis s3

Cada addon expone un conjunto fijo de variables de entorno que tus servicios consumen por referencia (${{<addon-name>.KEY}}). Consulta Managed Addons.

Referencias entre recursos

Cualquier valor de un servicio o addon puede referenciarse desde el entorno de otro recurso usando:

${{<name>.<KEY>}}

Las referencias se resuelven en tiempo de despliegue contra el entorno combinado del destino. Coinciden con el nombre actual del destino: si renombras un servicio o addon, actualiza todas las referencias que usen el nombre anterior. Una referencia a un destino o clave inexistente se resuelve como una cadena vacía (el despliegue no falla por eso); solo las referencias circulares lanzan errores.

# Wire a service to the project's Postgres
lizard secrets set DATABASE_URL='${{postgres.DATABASE_URL}}' --service api

Comprueba que la referencia se resolvió. El log de build imprime una advertencia por cada referencia que se resolvió como un valor vacío, y secrets list muestra lo que está almacenado:

lizard logs --build --service api
lizard secrets list --service api --show

Variables inyectadas por la plataforma

Cada servicio recibe automáticamente estas variables (no se pueden sobrescribir):

Consulta Variables & Secrets para ver cómo interactúan con tus propias variables y el orden completo de precedencia.

Actualizado 21 de octubre de 2026