Saltar al contenido principal
Esta página reúne, en un único documento, todo lo que hace Vertra Cloud y con qué límites: planes y precios, lenguajes y bases de datos compatibles, MCP, snapshots, workspaces, API, códigos de error y soluciones para los problemas más comunes. Es la fuente de la que derivan las demás páginas de esta documentación, y se escribió para que la lean tanto personas como asistentes de IA.
Espejo: plans-and-limits publica en forma resumida las tablas de planes, runtimes, bases de datos, la pestaña Datos y los límites de despliegue de esta página. ¿Cambiaste un número aquí? Actualiza también plans-and-limits, overview y api-reference/limitations en la misma tarea.

​
1. Descripción general

Vertra Cloud es una plataforma brasileña de alojamiento en la nube para desplegar aplicaciones y bases de datos gestionadas. Admite 13 lenguajes, 4 tipos de base de datos, monitorización en tiempo real, dominios personalizados, un servidor MCP para tu agente de IA, workspaces colaborativos y una extensión para VS Code. SLA: 99,99 % de disponibilidad, en todos los planes. Es el único SLA que declara la plataforma: el marketing, las tarjetas de los planes, la página de Enterprise, las Condiciones de uso y la documentación pública dicen 99,99 % y ninguna otra cifra.
  • Sitio: https://vertracloud.app
  • Panel: https://vertracloud.app/dashboard
  • API: https://api.vertracloud.app
  • Documentación: https://docs.vertracloud.app
  • CLI (guía): curl -fsSL https://cli.vertracloud.app/install | sh en macOS/Linux, irm https://cli.vertracloud.app/install | iex en Windows (PowerShell)
  • Servidor MCP (guía): endpoint remoto https://mcp.vertracloud.app/mcp (OAuth), o local con npx -y @vertracloud/mcp y un VERTRA_API_KEY
  • SDK (guía): npm install @vertracloud/sdk-api · pip install vertracloud-api · go get github.com/vertracloud/sdk-api-go
  • Extensión para VS Code (guía): code --install-extension VertraCloud.vertra-cloud
  • GitHub Actions (guía): vertracloud/github-action

​
2. Lenguajes compatibles

Las versiones se actualizan con regularidad con parches de seguridad. Una versión que llega al fin de su soporte se retira de la lista. Si la versión guardada en una aplicación ya no está disponible, la plataforma usa la versión más reciente de la misma rama (por ejemplo, 3.11 se ejecuta en 3.11.17); si se retiró toda la rama, recurre a la versión recommended.

​
Detección de lenguaje

La plataforma detecta el lenguaje a partir de los archivos de manifiesto de la raíz del proyecto, comprobando cada ecosistema antes que package.json: un proyecto de Python, PHP (Laravel) o Ruby (Rails) que además tenga un package.json de front-end sigue siendo Python, PHP o Ruby. bun.lock se reconoce como Bun, y los proyectos Java también se reconocen por build.gradle.kts, settings.gradle(.kts), mvnw y gradlew. MAIN=./src/index.js (con el ./ inicial) se acepta. Para forzar un lenguaje, define LANGUAGE=<slug> en vertracloud.config (por ejemplo LANGUAGE=deno) o envía language en POST /v1/apps. En vertracloud.config.json la clave es "language". La precedencia es el campo de la API, luego el archivo de configuración y, por último, la detección. Un valor desconocido se rechaza con INVALID_LANGUAGE (HTTP 400).

​
Deno, .NET y Elixir

Phoenix es compatible: define SECRET_KEY_BASE y PHX_HOST como variables de entorno. Ejecuta mix assets.deploy antes de comprimir, o usa un proyecto sin assets.

​
3. Bases de datos

Eliges la versión al crear una base de datos (el selector del panel, o version en la API); la recomendada es la predeterminada. Las bases de datos existentes conservan su versión mayor, y las actualizaciones de seguridad (versiones de parche) se aplican automáticamente cada vez que la base de datos se reinicia (detenerla y luego iniciarla, en el panel). Si usas índices btree_gist sobre columnas float o índices ltree en PostgreSQL, ejecuta REINDEX sobre ellos tras el reinicio. Las bases de datos MySQL 8.0 existentes siguen en 8.0, versión que ya no está disponible para las nuevas. Las bases de datos Redis 7.4 existentes siguen en 7.4. Una base de datos creada a partir de un snapshot nace con la versión mayor del snapshot (un snapshot de MySQL 8.0 crea una base de datos MySQL 8.4, y un snapshot de Redis 7.4 una de Redis 8.2); version puede ser igual o más nueva, nunca más antigua (SNAPSHOT_VERSION_NEWER). Restaurar en una base de datos antigua un snapshot tomado en una versión más nueva se rechaza con el mismo código y no se cambia nada. vertracloud es el usuario de las bases de datos creadas desde la v26.4.8 en adelante, y no es superusuario. Las bases de datos más antiguas conservan el usuario del motor: postgres (base de datos postgres), default en MongoDB (base de datos de autenticación admin) y Redis, y root (base de datos default) en MySQL. El campo username de la base de datos en la API indica cuál usar. El puerto es único por base de datos, no el predeterminado del motor, y se muestra en la página de la base de datos. Todas las bases de datos generan certificados TLS automáticamente (CA, servidor y cliente). Todos los motores exigen TLS y un certificado de cliente: una contraseña sola nunca conecta.

​
Cómo conectarte a cada base de datos

  • Host: <database-id-without-hyphens>.db.usa1.vertraweb.app. Puerto: único por base de datos (no 5432/27017/6379/3306); cópialo desde la página de la base de datos o desde GET /v1/databases/{id}.
  • Archivos (pestaña Certificados o GET /v1/databases/{id}/credentials/certificate): certificate-<id>.crt = certificado de cliente, certificate-<id>.key = clave privada del cliente, certificate-<id>.pem = paquete con la clave del cliente, el certificado del cliente y la CA. Usa el .pem como archivo CA en todas partes, y como archivo de clave y certificado para MongoDB.
  • El certificado del servidor coincide con el host, así que la verificación completa funciona.
Los ejemplos de Node.js para cada driver (pg, mongodb, ioredis, mysql2) están en la página Bases de datos. RAM mínima: 1.024 MB para PostgreSQL, MongoDB y MySQL; 512 MB para Redis. Almacenamiento: 6 GB + 1 GB por cada 512 MB de RAM asignada, redondeado al GB, o 3× la RAM cuando esa cifra es mayor (desde 6 GB de RAM en adelante). La cuota es siempre un número entero de GB (por ejemplo: 512 MB → 7 GB; 1 GB → 8 GB; 2 GB → 10 GB; 4 GB → 14 GB; 8 GB → 24 GB). Ninguna base de datos existente pierde espacio cuando cambia la fórmula: el límite solo crece. Operaciones: Iniciar, Detener, Reiniciar, Restablecer (destructivo, limitado a 1 por hora), Restablecer contraseña, Restablecer certificados, Descargar/Restaurar snapshot.

​
Gestor de datos (la pestaña “Datos”)

Explora y edita el contenido de la base de datos desde el panel, sin mostrar la contraseña ni la cadena de conexión. Solo en el panel; no está disponible a través de la API. SQL: esquemas, tablas, columnas, índices, filas y una consola SQL. MongoDB: colecciones, índices y documentos. Redis: claves mediante SCAN, valor según el tipo, TTL. Plan mínimo: Intermediary. Toda la pestaña se desbloquea desde Intermediary en adelante. El control verifica el plan del propietario de la base de datos, no el plan de quien accede: un miembro de un workspace sin plan puede usar la pestaña Datos en una base de datos cuyo propietario tenga el plan requerido, y un propietario sin plan no obtiene la función por invitar a alguien con un plan superior. Por debajo de ese plan, el panel muestra la tarjeta del plan en lugar del explorador. Permiso: el acceso de lectura lo tiene cualquier miembro del workspace; el acceso de escritura y la consola SQL son solo para el propietario o para administradores (el propietario de la base de datos siempre puede hacerlo). Cada modificación se registra como una actividad en el log de la base de datos, con la operación y el objeto, nunca el contenido. Lo que deliberadamente no existe: un comando administrativo o la ejecución de código arbitrario en la consola de Redis o de Mongo. En SQL, el límite es el tiempo, el tamaño y la concurrencia.

​
4. Planes y precios

Ningún plan tiene un límite de cantidad. El límite real es la RAM del plan, y lo que rechaza una creación es MEMORY_LIMIT_EXCEEDED: una aplicación de 100 MB cabe 10 veces en un plan Pro. Mínimos que consumen esa RAM: aplicación 100 MB, Redis 512 MB, Postgres/MySQL/Mongo 1.024 MB.

​
vCPU por aplicación

La columna vCPU de la tabla anterior es el techo por aplicación en el plan, no un total repartido entre los proyectos de la cuenta. Dentro de ese techo, la vCPU de un proyecto crece con su RAM:
  • Crecimiento: en planes de hasta 2 vCPU, +1 vCPU por cada 512 MB de RAM; en planes con más de 2 vCPU, +1 vCPU por cada 1 GB (1.024 MB).
  • Mínimo: un proyecto con 512 MB o más recibe al menos 2 vCPU; por debajo de 512 MB, al menos 1 vCPU.
  • Máximo: nunca más que la vCPU del plan. Economy (0,3) y Pro (0,5) siempre dan al proyecto la vCPU completa del plan.
La misma regla se aplica a las bases de datos. Más RAM nunca da menos vCPU. Un cambio surte efecto la próxima vez que el proyecto se reinicie o se despliegue.

​
Agentes de IA (MCP)

Vertra no aloja chat ni modelos de IA. Conecta Claude, Codex, Cursor u otro cliente MCP al servidor oficial para operar aplicaciones, bases de datos, archivos, logs y despliegues con tu clave de API. Las validaciones internas ocurren durante el ciclo de vida de la aplicación, como el despliegue, el nuevo build y el reinicio; no son una superficie de producto aparte.

​
Precios de Enterprise

​
Nombres de los planes

La API identifica un plan por su nombre; no existe un ID numérico de plan. GET /v1/users/me devuelve plan con name, memory, expires_at y duration, o plan: null para una cuenta sin plan activo. Las aplicaciones, las bases de datos y los workspaces llevan el plan del propietario en owner_plan (el nombre, o null). Compara los planes por nombre, nunca por su posición en esta lista. El código que leía plan_id, plan.id o owner_plan_id debe leer en su lugar plan.name y owner_plan (cambio incompatible de la API, los SDK, la CLI y el MCP).

​
Funciones por plan

Versiones anteriores conservadas cuenta las versiones distintas de la que se ejecuta ahora. Validez de la versión cuenta desde el momento en que una versión deja de ser la que se ejecuta; la versión en ejecución nunca caduca. Enterprise conserva 15 versiones en los niveles E-4, E-6 y E-8, 20 en E-12, E-14 y E-16, 25 de E-18 a E-24, y 30 de E-26 a E-32.
Rollback automático y Despliegues sin tiempo de inactividad son ajustes de despliegue, que se cambian en la configuración de la aplicación o con PATCH /v1/apps/{id}/config (deploy). Pedir cualquiera de los dos en un plan que no los incluye falla con 403 PLAN_DOES_NOT_SUPPORT_AUTO_ROLLBACK o 403 PLAN_DOES_NOT_SUPPORT_ZERO_DOWNTIME; desactivarlos siempre está permitido.
El gestor de archivos es la pestaña Archivos del panel y sus rutas HTTP; las reglas de propiedad y de rutas son las mismas en la API, la CLI y el MCP.
Tres cosas distintas que la documentación suele mezclar:
  • Publicar (Pro o superior): tener un sitio. La aplicación recibe un subdominio *.vertraweb.app y pasa a ser accesible desde internet. En Pro, la plataforma asigna el subdominio al azar. En Pro, las páginas HTML del sitio también muestran el distintivo «Powered by Vertra Cloud» en la esquina inferior derecha; desde Scale en adelante no aparece. Cambiar de plan activa o desactiva el distintivo de inmediato, sin volver a desplegar.
  • Elegir el subdominio (Scale o superior): elegir el nombre del subdominio, al crear o más tarde (PATCH /v1/apps/{id}/network/subdomain). Sin esta función, el usuario puede publicar, pero no puede elegir el nombre.
  • Dominios personalizados (Intermediary o superior): apuntar a la aplicación los dominios que tienes, tantos como permita el plan (ver Dominios personalizados).

​
Cuenta sin plan activo

Una cuenta sin plan activo no puede crear aplicaciones ni bases de datos, ni publicar un sitio: esas peticiones se rechazan con PLAN_REQUIRED (403). Suscríbete a un plan, a partir de Economy, para continuar.
  • Los proyectos sin conexión durante 30 días o más se eliminan automáticamente, con un snapshot previo
  • Notificaciones por correo los días 7, 23 y 27 antes de la eliminación

​
Periodos de facturación y pago

  • Periodos: 1, 3 o 12 meses. Una compra de 3 meses tiene un descuento del 5 % y una de 12 meses un descuento del 15 % sobre el precio mensual. Economy es solo mensual.
  • Métodos de pago: PIX o tarjeta de crédito (Visa y Mastercard). Economy acepta solo PIX, por lo que nunca se renueva por sí solo. Un cupón puede restringir un pedido a un único método.
  • Los precios están siempre en R$. El sitio muestra un importe aproximado en dólares estadounidenses junto al precio (≈ $) solo como referencia; el cobro es en reales.
  • Tarjeta = renovación automática. La tarjeta se guarda en la cuenta y el plan se renueva con la tarjeta predeterminada, sin periodo de fidelidad. Tres días antes de que el plan caduque se cobra la tarjeta y el mismo día se envía un correo. Si el cobro falla, se reintenta en cada uno de los 2 días siguientes y el día de caducidad; si fallan todos los intentos, el plan caduca con normalidad. Si el banco pide confirmación, recibes un correo para confirmar el pago. Para detener la renovación automática, usa Cancelar renovación en la tarjeta del plan, en Facturación: el plan sigue activo hasta su fecha de caducidad y la tarjeta permanece guardada.
  • PIX no se renueva. Solo recibes el aviso habitual de caducidad y vuelves a pagar cuando quieras.
  • Los pedidos sin pagar caducan. Un pedido que no se paga permanece abierto durante 72 horas desde su creación; después caduca y ya no se puede pagar. Recibes un correo cuando un pedido queda abierto, y recordatorios con 48 horas y 24 horas restantes.
  • Los códigos QR de PIX duran hasta 30 minutos. Si un código QR caduca mientras el pedido sigue abierto, genera uno nuevo para el mismo pedido.
  • Los datos de facturación son obligatorios para comprar un plan. Son necesarios para emitir la factura de servicio (NFS-e). En Brasil: nombre, CPF o CNPJ y la dirección completa (CEP, calle, número y barrio; la ciudad y el estado se rellenan a partir del CEP). Fuera de Brasil: nombre, calle, ciudad, país y código postal. El teléfono es opcional. Defínelos en Facturación; si faltan, el proceso de pago los pide antes del pago. Por la API, un pedido sin ellos falla con BILLING_DETAILS_INCOMPLETE.
  • Dónde están los datos de pago. El número de la tarjeta, la caducidad y el CVV se escriben en un campo de Stripe y se tokenizan en el navegador; nunca llegan a Vertra. Los datos de facturación (nombre, dirección, teléfono, CPF/CNPJ) los almacena Stripe, no Vertra. Vertra guarda solo la marca de la tarjeta, los últimos 4 dígitos y la caducidad, para listar las tarjetas guardadas.
  • Reembolsos. La primera compra de un plan de pago puede reembolsarse íntegramente en un plazo de 7 días. Una renovación automática con tarjeta también puede reembolsarse íntegramente en un plazo de 7 días desde el cobro; el plan vuelve a su fecha de caducidad anterior. Las renovaciones que haces tú mismo, las mejoras y los cambios de plan no son reembolsables. Las solicitudes van a [email protected].
  • Facturas (NFS-e): la factura de servicio brasileña (NFS-e) se emite automáticamente para cada pedido pagado y se entrega por correo electrónico, a nombre y con el CPF/CNPJ de tus datos de facturación. Un reembolso total anula la factura.

​
5. Tipos de aplicación

El límite del nombre visible de una aplicación, una base de datos y un workspace es de 50 caracteres como máximo. El tipo no se decide de una vez por todas al crear la aplicación. Una aplicación creada sin publicación web puede publicarse más tarde (POST /v1/apps/{id}/network/publish) y volver a dejarse sin publicar (DELETE /v1/apps/{id}/network/publish), lo que cambia el tipo entre 1 y 2. Hay dos consecuencias que hay que comunicar a los usuarios:
  • Activarla y desactivarla vuelve a crear el contenedor, así que la aplicación se reinicia: las reglas de red y el puerto expuesto solo existen desde el momento en que se crea el contenedor.
  • Al desactivarla, el subdominio queda libre: no hay reserva, así que otra persona puede reclamarlo. También se elimina cada dominio personalizado, y sus registros CNAME y TXT de validación permanecen en el proveedor DNS del usuario hasta que el usuario los borre.
Publicar requiere 512 MB de RAM. En este flujo la RAM no aumenta por sí sola: con menos que eso, la llamada devuelve MEMORY_BELOW_MINIMUM con details: { current_mb, minimum_mb }. Aplicaciones desde una imagen Docker personalizada. En Enterprise 28, Enterprise 30 y Enterprise 32, una aplicación puede ejecutarse desde una imagen construida a partir del Dockerfile propio del cliente. Se crea con POST /v1/apps/image, y puede ser un Bot (web: false) o un Sitio web (web: true). Reglas que hay que enunciar con exactitud:
  • Contexto de build: ZIP de hasta 100 MB, o un repositorio de GitHub, con un archivo llamado exactamente Dockerfile en la raíz. Hasta 20 imágenes por cuenta, contando todos los estados. Plataforma linux/amd64.
  • Build: entorno de build aislado, límite de tiempo de 26 minutos, imagen construida de hasta 10 GB sin comprimir (IMAGE_TOO_LARGE). Los archivos .env* se eliminan del contexto.
  • Runtime: siempre con el usuario 1000:1000. /app es el disco persistente; /tmp, /var/tmp y /run se pueden escribir pero son temporales; lo demás es de solo lectura. El puerto es el primer EXPOSE o 80, inyectado como PORT.
  • Rechazado: un # syntax= distinto del frontend oficial, RUN --security=insecure, RUN --network=host, --mount=type=ssh, --mount=type=secret. Advertido: WORKDIR /app, .env* en el contexto, COPY/ADD de .env, VOLUME fuera de /app.
  • Actualizaciones: nuevo build mediante subida, commit (sobre el contexto actual) o push a una rama de GitHub vinculada. Un nuevo build nunca reinicia las aplicaciones. Cada aplicación conserva 30 releases durante 30 días, y el rollback usa una versión ya construida.
  • Los snapshots guardan los datos de /app y la versión de la imagen; al restaurar se puede volver opcionalmente a esa versión.
  • Eliminar una imagen elimina todas las aplicaciones creadas a partir de ella. Los planes inferiores a Enterprise 28 no pueden crear ni volver a construir imágenes; el cambio a un plan con menos plazas que las imágenes en uso (propias y de plantillas de imagen) se rechaza: elimina imágenes antes.
Imágenes y plantillas. Una plantilla de imagen ocupa una ranura de imagen por cada imagen distinta en uso, nunca una por aplicación: tres aplicaciones de la misma plantilla ocupan una sola ranura, y una nueva versión de la plantilla conserva la misma ranura. Una plantilla de código no ocupa ninguna. La ranura se libera cuando se elimina la última aplicación que usa la imagen. POST /v1/apps/image rechaza una imagen que pertenece a una plantilla (IMAGE_TEMPLATE_ONLY): la única forma de ejecutarla es a través de la plantilla. Una imagen que es el origen de una de tus plantillas privadas no se puede eliminar antes de quitarla de la plantilla (IMAGE_IN_USE). Ver Plantillas y stacks. Guía: Imágenes Docker personalizadas.

​
Almacenamiento

Cada aplicación recibe 10 GB de almacenamiento, sin importar la RAM asignada (antes del 14 de septiembre de 2026 el límite era 6 GB + 2 GB por cada 2 GB de RAM). Superar el límite rechaza las escrituras; reducir la RAM no baja el límite de almacenamiento, que es fijo por aplicación.

​
Límites de ancho de banda según la memoria

Por encima de 10 GB de RAM, el límite crece en unos 50 Mbit por cada 256 MB adicionales.

​
Ciclo de vida

La creación es asíncrona. POST /v1/apps responde 202 Accepted de inmediato con la aplicación en status: "building"; la instalación y el build siguen en segundo plano con logs en vivo. El estado pasa a up o down cuando termina el build: síguelo con GET /v1/apps/{id} o con el flujo de logs en tiempo real. Mientras el estado es building, iniciar, detener, reiniciar, los despliegues de archivos (subida, commit), el rollback, los snapshots, las restauraciones y los cambios de configuración responden 409 APP_BUILDING; eliminar la aplicación sí está permitido. Si el build no termina, la aplicación sigue en down y aparece BUILD_INTERRUPTED en su log. Cuando falla un build o una instalación, GET /v1/apps/{id} lleva el código en last_build_error (null tras un build correcto). Si la plataforma cancela la creación (por ejemplo, porque la cola está llena), la aplicación deja de existir y GET responde 404.

​
Comando de build (build_command)

Campo opcional por aplicación, disponible en todos los planes. Se ejecuta en cada despliegue (creación, subida de zip, despliegue desde GitHub, reinstalación de dependencias o un cambio en el propio comando), siempre después de instalar las dependencias y antes de que la aplicación arranque. Un simple reinicio no vuelve a ejecutar el build si el build anterior terminó correctamente con el mismo comando. El build se ejecuta en un entorno de build aislado de la aplicación: 2× la RAM de la aplicación (mínimo 1.024 MB, máximo 4.096 MB), con un límite de tiempo de 10 minutos. Si el comando falla, el despliegue falla y la aplicación no arranca (BUILD_FAILED); si se agota el tiempo, BUILD_TIMEOUT. Al crear la aplicación, una instalación o un build fallidos crean igualmente la aplicación, detenida, con la salida en sus logs; el usuario corrige los archivos y la vuelve a iniciar. Cuando la aplicación tiene un comando de build, la instalación de dependencias incluye también devDependencies (Tailwind, TypeScript, PostCSS y herramientas similares funcionan sin tener que pasarlas a dependencies); sin comando de build, solo se instalan dependencies. Puppeteer usa el Chromium que ya está disponible en la imagen de runtime, así que no se descarga ningún navegador durante la instalación. El entorno de build tiene el doble del ancho de banda de la aplicación (la misma tabla de ancho de banda por RAM, ×2): descargar dependencias pesa más que servir tráfico, y la ventana es corta. Superarlo interrumpe el despliegue, igual que ocurre con la aplicación mientras se ejecuta. Ejemplos habituales: La aplicación debe escuchar en el puerto 80; esto aplica a toda aplicación de tipo Sitio web, con o sin build_command. Al crear una aplicación desde el panel a partir de un zip, la plataforma sugiere los comandos de build e inicio de arriba según las dependencias declaradas en package.json (Next.js, Nuxt, SvelteKit, Remix, React Router, Astro, Gatsby y Vite); el usuario puede editar ambos antes de crearla. Un proyecto sin framework reconocido arranca desde el archivo principal, sin comando de build.

​
Archivo de configuración (vertracloud.config)

Un archivo KEY=value opcional en la raíz del zip subido. Solo rellena previamente el formulario de creación o subida; la configuración real está en el panel (pestaña Ajustes). Claves reconocidas: NAME, DESCRIPTION, MAIN, MEMORY, START, BUILD, VERSION, SUBDOMAIN, LANGUAGE; cualquier otra clave (incluida la antigua AUTORESTART) se ignora. VERSION rellena previamente el asistente al subir el zip y se usa al crear desde un snapshot; la versión confirmada en el asistente es la que ejecuta la aplicación, y una versión que no existe para el lenguaje se rechaza con INVALID_VERSION. También se acepta vertracloud.config.json, con claves en minúsculas. Si el zip contiene .env.production, .env.production.local, .env.local o .env (en ese orden), el flujo de creación rellena previamente las variables de entorno a partir del primero que no esté vacío.
El archivo no existe en el volumen de la aplicación (desde el 14 de septiembre de 2026). Se descarta al extraer el zip y se genera desde la base de datos con los valores actuales al descargar el proyecto o al crear un snapshot; por eso un zip descargado o un snapshot restaurado siempre vuelve con la configuración actual. No aparece en el gestor de archivos; un archivo con ese nombre creado a mano se ignora y se sobrescribe al descargar.

​
Subdominios

  • Formato: your-app.vertraweb.app
  • Único por aplicación
  • La publicación web (obtener un subdominio) está disponible desde el plan Pro
  • Elegir el nombre del subdominio requiere el plan Scale o superior; por debajo, la plataforma asigna un nombre al azar
  • Formato aceptado al elegirlo: de 3 a 50 caracteres, ^[a-z0-9][a-z0-9-]*[a-z0-9]$
  • Se puede renombrar después mediante PATCH /v1/apps/{id}/network/subdomain (mínimo 5 minutos entre cambios)

​
Dominios personalizados

  • Disponible desde el plan Intermediary. Dominios por aplicación (el complemento automático www o de la raíz no cuenta): Economy, Pro y Scale 0; Intermediary 1; Enterprise-4 a 8: 2; Enterprise-12 a 24: 5; Enterprise-26 a 32: 20
  • La aplicación debe estar publicada en la web. Añadir, cambiar o quitar un dominio no reinicia ni vuelve a desplegar la aplicación
  • Configura los registros DNS que se muestran para el dominio (un CNAME y, normalmente, un registro de validación del certificado). La configuración automática del DNS todavía no está disponible: POST /v1/apps/{id}/domains/{domain_id}/connect responde siempre DOMAIN_CONNECT_UNAVAILABLE
  • El SSL se aprovisiona automáticamente tras la validación del DNS
  • www automático: añadir example.com añade también www.example.com (y al revés). El complemento redirige al dominio principal con un 308, no cuenta para el límite, se elimina junto con el dominio principal y se puede desactivar con www: false. Cualquiera de los dos puede pasar a ser el dominio principal (primary: true)
  • Los dominios raíz necesitan un proveedor DNS que admita CNAME flattening, ALIAS o ANAME; el panel lo advierte
  • Puerto por dominio: cualquier puerto del 1 al 65535 (por defecto, 80), hasta 5 puertos distintos además del 80 por aplicación (DOMAIN_PORT_LIMIT_REACHED por encima de eso)
  • Prefijo de ruta por dominio (ruta literal como /api, empieza por /, sin / final): se añade delante de cada petición. Recomendado para APIs; un sitio web tiene que ejecutarse bajo esa ruta
  • Redirección por dominio hacia otro dominio de la misma aplicación, con estado 301, 302, 307 o 308 (por defecto, 308), conservando la ruta y la cadena de consulta. Una redirección no puede apuntar a otra redirección
  • Estado por dominio: pending (esperando al DNS), active, moved (el DNS ha dejado de apuntar a Vertra Cloud) o deleted; además del estado del certificado (pending, active, failed)
  • Un dominio que permanezca en pending, moved o deleted durante 14 días se elimina automáticamente y el propietario recibe un correo
  • Dejar de publicar la aplicación elimina todos sus dominios
  • Limpia tu DNS cuando un dominio deje de existir (lo quites tú, al dejar de publicar o por la limpieza de 14 días): borra sus registros CNAME y TXT de validación en tu proveedor DNS. Quitar un dominio no toca tu DNS; si los registros permanecen, el nombre sigue apuntando a Vertra Cloud y otro cliente podría reclamarlo
  • Rutas: GET/POST /v1/apps/{id}/domains, PATCH/DELETE /v1/apps/{id}/domains/{domain_id}, GET /v1/apps/{id}/domains/{domain_id}/dns, POST /v1/apps/{id}/domains/{domain_id}/connect. Las lecturas necesitan el scope apps:read; las escrituras, apps:write

​
6. Reinicio automático y detección de bucles de fallos

  • Los contenedores que fallan se reinician automáticamente: es el comportamiento predeterminado en todos los planes, siempre activo, sin opción para desactivarlo
  • El código de salida 0 (terminación normal) NO provoca un reinicio. Tampoco los errores que un reinicio no puede arreglar: errores de sintaxis, módulos que faltan, falta de memoria, una instalación o un build fallidos, o una pausa de Vertra Shield
  • Cualquier otro fallo se reinicia, incluso si la aplicación solo llevaba unos segundos en ejecución, con una espera creciente entre intentos: de inmediato, y después 10 s, 30 s, 60 s y 2 min
  • Bucle de fallos (crash loop): hasta 5 reinicios automáticos en una ventana de 10 minutos. El sexto fallo en esa ventana suspende el reinicio automático durante 24 horas: la aplicación permanece detenida y el panel indica el motivo
  • Iniciar o reiniciar la aplicación manualmente borra el contador de fallos y levanta la suspensión
  • Una aplicación que permanece en ejecución 10 minutos sale de la ventana, así que los fallos anteriores dejan de contar

​
7. Protecciones de la plataforma (Vertra Shield)

Vertra Shield protege todas las aplicaciones y bases de datos de la plataforma. En situaciones que podrían afectar a la disponibilidad, Shield puede pausar una aplicación temporalmente; el panel muestra el motivo y una cuenta atrás.

​
Límite de peticiones por IP de visitante

Las aplicaciones en *.vertraweb.app y en dominios personalizados tienen un límite de peticiones que puede enviar una única IP de visitante. Un visitante que supere el límite queda bloqueado temporalmente, antes de que el tráfico llegue a la aplicación. Los picos repentinos de tráfico de muchos visitantes distintos no pausan la aplicación. Si tu aplicación recibe legítimamente tráfico de alto volumen desde una sola IP, como una integración servidor a servidor o webhooks, contacta con soporte.

​
Enfriamiento de Shield (pausa visible)

Cuando Shield pausa una aplicación, el panel muestra un aviso con el motivo y el tiempo restante, y las acciones de iniciar y reiniciar dejan de estar disponibles temporalmente. El enfriamiento puede aumentar tras repeticiones, hasta un límite de 1 hora. Shield solo detiene la aplicación: nunca la elimina, ni sus archivos ni sus datos. Iniciar, reiniciar, desplegar, cambiar la configuración y eliminar la aplicación esperan a que termine la pausa: estas acciones responden 403 con el error APP_SHIELD_COOLDOWN, y details incluye el motivo y cuándo termina la pausa.

​
Restricciones de acceso por región (*.vertraweb.app)

  • Bloqueados (sanciones o restricciones regulatorias): Afganistán (AF), Bielorrusia (BY), Cuba (CU), China (CN), Irán (IR), Corea del Norte (KP), Rusia (RU), Siria (SY), la Antártida (AQ) y todos los nodos de salida de Tor (T1).
  • Comprobación en el navegador (por motivos de seguridad): Bangladés (BD), India (IN), Irak (IQ), Filipinas (PH), Ucrania (UA), Venezuela (VE), Vietnam (VN), Indonesia (ID) y Malasia (MY). Solo una persona en un navegador supera la comprobación; los clientes de API y los emisores de webhooks de estos países reciben 403.

​
8. SSL/TLS

  • Todos los sitios reciben certificados SSL/TLS automáticos
  • Renovación automática antes de su caducidad
  • Redirección de HTTP a HTTPS activada por defecto
  • Los dominios personalizados también reciben SSL automático
  • Todas las conexiones a bases de datos requieren TLS

​
9. Snapshots

  • Creación manual de snapshots para aplicaciones y bases de datos: como máximo 1 cada 5 minutos en el mismo proyecto y 10 por hora entre todos los recursos de la cuenta; superar cualquiera de los dos límites devuelve SNAPSHOT_RATE_LIMITED (429) con details: { scope: "resource" | "account", retry_after }
  • Restauración desde cualquier snapshot anterior (enfriamiento de 30 segundos)
  • Descarga el contenido del snapshot como ZIP
  • Disponible desde el plan Scale (copias de seguridad manuales)
  • Eliminar o restablecer una base de datos hace automáticamente un snapshot de seguridad antes de destruir los datos, en todos los planes. Si la copia falla, la acción se bloquea (SNAPSHOT_FAILED) y la base de datos ni se elimina ni se restablece. Este snapshot forzado tiene su propio límite, separado del de creación manual: como máximo 2 intentos por hora en el mismo proyecto, y 10 por hora entre todos los proyectos de la cuenta; superar cualquiera de los dos devuelve FORCED_SNAPSHOT_RATE_LIMIT y también bloquea la acción.
  • Eliminar una aplicación hace el mismo snapshot de seguridad desde el plan Pro en adelante (el plan del propietario). Si falla, la aplicación no se elimina (SNAPSHOT_FAILED); se aplica el mismo límite. En Economy la aplicación se elimina de inmediato sin copia, y el panel ofrece descargar antes el proyecto. Al caducar el plan, se hace snapshot de cada proyecto antes de eliminarlo, en todos los planes.

​
10. Workspaces

Colaboración en equipo con permisos granulares y roles personalizables. Disponible solo en el plan Enterprise. El propietario del workspace conserva el control sobre las acciones de gestión exclusivas del propietario.

​
Los 20 permisos

Acciones solo para el propietario, sea cual sea el rol: vincular o desvincular un proyecto, renombrar o eliminar el workspace, el webhook de despliegue de GitHub y activar o desactivar la publicación web.

​
Roles iniciales

Cada workspace nace con 4 roles, que se pueden renombrar y eliminar (pasan a ser roles normales; cuentan para el límite del nivel igual que cualquier otro):

​
Límite de roles personalizados por nivel (Enterprise)

Los 4 roles iniciales cuentan para el límite.

​
Miembros por nivel (Enterprise)

La progresión nunca disminuye al subir de nivel (5 como mínimo y 24 como máximo). Una invitación pendiente cuenta.

​
Invitaciones

Dos formas, ambas con el permiso members:manage:
  • Correo electrónico: vinculada a una dirección concreta, caduca en 7 días. WORKSPACE_INVITE_EMAIL_MISMATCH si la acepta una cuenta con otro correo.
  • Enlace: de uso múltiple, con caducidad fija de 24 h, max_uses opcional. Revocable en cualquier momento.
Una invitación puede llevar expires_in_days: una caducidad de acceso que se aplica al miembro que se une con ella; null o ausente = sin caducidad. Una invitación pendiente cuenta para el límite de miembros del plan. Cada cuenta tiene el interruptor workspace_invites_enabled (APIUser) para rechazar las invitaciones por correo; cuando está desactivado, una nueva invitación por correo a esa cuenta falla con WORKSPACE_INVITES_DISABLED.

​
Carpetas y favoritos

Las carpetas y los favoritos organizan aplicaciones y bases de datos sin cambiar los recursos. La organización se guarda en la cuenta y tiene dos ámbitos:
  • Personal: la vista individual de la cuenta, devuelta por GET /v1/users/me.
  • Workspace: la vista individual del miembro dentro de un workspace, devuelta por GET /v1/workspaces/:id. No se comparte con los demás miembros.
Una carpeta tiene nombre, color, posición y referencias a aplicaciones o bases de datos. Los colores permitidos son neutral, red, orange, yellow, green, blue y purple. resource_type solo acepta application y database. Los favoritos y las carpetas son independientes entre sí. Crear, editar, eliminar, mover y marcar como favorito genera una actividad. La acción puede venir del panel, de un flujo de trabajo o de un cliente autenticado con una clave de API, como la CLI, el MCP y la extensión de VS Code. El cliente no envía origin ni author_id; la API registra el origen y el autor automáticamente. La lista de proyectos y Flow usan la misma organización guardada. En Flow, la carpeta y el favorito aparecen junto a los recursos, pero los grupos creados en el lienzo siguen siendo locales e independientes. Las carpetas no son grupos de Flow. Un grupo organiza elementos en el lienzo local de Flow, mientras que una carpeta organiza recursos dentro de la cuenta o del workspace. No existe group_id, ni sincronización ni migración entre los dos conceptos.

​
Solicitudes de acción

Un miembro que no tiene el permiso para una acción sensible (app_delete, database_delete, snapshot_create, snapshot_restore) puede abrir una solicitud de acción; quien tenga members:manage y el permiso para esa acción la aprueba o la rechaza. Caduca en 24 h sin decisión (WORKSPACE_ACTION_REQUEST_EXPIRED).

​
Retención

Eliminar un workspace es una eliminación lógica: el nombre vuelve a estar disponible para un nuevo workspace; un plan Enterprise caducado congela las escrituras (invitar, acciones, editar), nunca elimina datos.

​
Ruta → permiso

​
Códigos de error

​
11. Gestor de archivos

  • Disponible desde el plan Pro
  • Explora y edita archivos directamente en el panel
  • Resaltado de sintaxis para todos los lenguajes
  • Subida mediante arrastrar y soltar (archivos o ZIP); el Destino del commit del diálogo de subida empieza en la carpeta abierta y puede apuntar a cualquier otra carpeta, y un ZIP se fusiona en ella
  • Árbol de archivos de hasta 6 niveles de profundidad
  • Crear, editar, mover y eliminar archivos y carpetas
  • Lista todos los directorios del proyecto, incluidas las carpetas de dependencias como node_modules; solo el endpoint del árbol de archivos (GET /v1/apps/{id}/files/tree) omite las carpetas de dependencias y de build para mantenerse ligero
  • vertracloud.config no existe en el volumen: se genera desde la base de datos al descargar y al hacer un snapshot (ver §Archivo de configuración)
  • Almacenamiento: 10 GB fijos por aplicación (ver §5 Almacenamiento)

​
12. Despliegue

​
Métodos

  1. Subida de ZIP desde el panel o la API
  2. Integración con GitHub: selección del repositorio (incluidos los privados)
  3. Webhooks de GitHub: despliegue automático al hacer push a la rama elegida, main o master por defecto (planes Intermediary o superiores)
  4. Extensión de VS Code: desplegar directamente desde el editor

​
Proceso

Subida del código → Instalación de dependencias → Build (si hay un build_command) → Arranque del contenedor → Asignación del subdominio → Aprovisionamiento de SSL

​
Límites de subida

  • Tamaño máximo del ZIP: 100 MB
  • Tiempo máximo de instalación de dependencias: 15 minutos (INSTALL_TIMEOUT si se supera)
  • Tiempo máximo del comando de build: 10 minutos (BUILD_TIMEOUT si se supera)
  • 1 puerto expuesto por aplicación

​
Rollback automático (Intermediary o superior)

Si la nueva versión de una aplicación se detiene en los 60 segundos posteriores a un despliegue, la plataforma vuelve a la versión anterior una sola vez y avisa al propietario, con un enlace al log de la versión fallida. Solo vuelven los archivos de código, no las variables de entorno. Si la versión anterior también se detiene, la aplicación queda detenida y se avisa al propietario. Durante esos 60 segundos el reinicio automático no reinicia la nueva versión, para que ambos no compitan. Un fallo después del primer minuto se trata como un fallo normal. Está desactivado por defecto, también en las aplicaciones creadas antes de esta función (deploy.auto_rollback, false por defecto); el propietario lo activa.

​
Despliegues sin tiempo de inactividad (Enterprise)

En Enterprise, un despliegue puede arrancar la nueva versión junto a la que está en ejecución, esperar a que esté sana y solo entonces cambiar, de modo que una aplicación que recibe tráfico web siga accesible durante el despliegue. El ajuste es deploy.zero_downtime, desactivado por defecto:
  • off (por defecto): detiene primero la versión en ejecución y después arranca la nueva.
  • auto: sin tiempo de inactividad solo para las aplicaciones que reciben tráfico web.
  • on: siempre, incluidas las aplicaciones sin tráfico web, como los bots. Dos procesos de la aplicación se ejecutan juntos durante un tiempo, así que un bot puede responder dos veces al mismo evento.
Comprobación de salud: la plataforma llama a la nueva versión por HTTP en deploy.health_check_path (/ por defecto). Cualquier respuesta HTTP cuenta como sana, incluido 404; una conexión rechazada, un tiempo de espera (5 segundos por intento) o una respuesta 5xx hacen fallar la comprobación. La versión debe responder correctamente dos veces seguidas y seguir en ejecución antes de que el tráfico se mueva. Una aplicación que solo escucha en 127.0.0.1 no supera la comprobación. Límites conocidos:
  • Ambas versiones usan la misma carpeta, y los dos procesos se ejecutan juntos durante unos 2 minutos como máximo. Los datos escritos por ambos a la vez, como un archivo JSON, pueden corromperse; SQLite normalmente lo soporta. Una migración de base de datos que se ejecute al arrancar se ejecuta mientras la versión anterior sigue sirviendo.
  • Una aplicación que lee archivos en cada petición (PHP, sitios estáticos, una aplicación Next.js o Nuxt ya construida, importaciones tardías en Python) puede servir una mezcla de archivos antiguos y nuevos mientras el despliegue instala y construye. Para esos casos, usa off.
  • Si la nueva versión no queda sana en unos 2 minutos, se descarta y la versión anterior sigue en ejecución. El propietario recibe un aviso con el log de la versión descartada.
  • Si en ese momento no se puede arrancar la segunda copia, el despliegue recurre a detener primero la versión en ejecución.
  • Mientras se prepara la nueva versión, la terminal sigue mostrando la versión en ejecución, no el build. Una petición que la versión anterior ya estaba respondiendo cuando se le pidió detenerse puede fallar una vez; gestionar SIGTERM de forma ordenada lo evita.

​
Límite de despliegues por hora

Un límite por cuenta, que se renueva en una ventana de 3.600 segundos. Cuentan: crear una aplicación, subir un zip, desplegar desde GitHub (manualmente o mediante push), reinstalar dependencias y cambiar el comando de build. No cuentan: reiniciar y detener. Si se supera → 429 DEPLOY_RATE_LIMITED con details.limit, details.window_seconds (3.600) y details.retry_after (segundos hasta que se libere). Un push de GitHub que llegue por encima del límite se ignora (no se pone en cola) y aparece en el historial de actividad.

​
Archivos excluidos del ZIP

El panel elimina automáticamente del zip, antes de subirlo: node_modules, .local, venv, .venv, __pycache__, .next, vendor, .bundle, target y .gradle.
  • JavaScript/TypeScript: node_modules, .npm, package-lock.json, .next
  • Python: venv, .venv, .cache, __pycache__, .env
  • Go: vendor
  • Rust: target
  • Java: target, .gradle
  • PHP/Ruby: vendor
dist/ y build/ (salida del build) no se eliminan automáticamente: si tu main/start apunta dentro de ellas (algo común en proyectos que empaquetan antes de desplegar), la plataforma necesita esos archivos. Exclúyelas del zip solo si el punto de entrada real está fuera de ellas.

​
13. Cambio a un plan inferior

  • Disponible desde el panel o la API: POST /v1/users/me/downgrade
  • Fórmula: newDays = remainingDays × (currentPrice / targetPrice)
  • Restricciones: ECONOMY no puede cambiar a un plan inferior
  • Comprobaciones: el uso de memoria y las imágenes Docker en uso (propias y de plantillas de imagen) deben caber en el plan de destino (INSUFFICIENT_MEMORY_FOR_DOWNGRADE, INSUFFICIENT_IMAGE_SLOTS_FOR_DOWNGRADE), y límite de frecuencia (1 vez cada 3 horas)
  • Impacto: límite de memoria reducido, funciones de planes superiores desactivadas, workspaces perdidos al salir de Enterprise. Los ajustes guardados de rollback automático y de despliegues sin tiempo de inactividad permanecen en la aplicación, pero solo actúan en un plan que los incluya

​
14. Extensión de VS Code

  • Disponible en el VS Code Marketplace (busca «Vertra Cloud»)
  • Funciones: despliegue rápido, gestión de aplicaciones, gestión de archivos, monitorización en tiempo real
  • Requisitos: VS Code 1.80 o superior, una cuenta de Vertra activa y conexión a internet
  • Despliegue desde la paleta de comandos: Ctrl+Shift+P → “Vertra: Deploy”

​
15. Métodos de autenticación

  • OAuth de Discord: inicio de sesión y vinculación de cuenta
  • OAuth de GitHub: inicio de sesión y vinculación de cuenta
  • OAuth de Google: inicio de sesión y vinculación de cuenta
  • Magic Link: autenticación sin contraseña por correo electrónico
  • Clave de API: para acceso programático (se gestiona desde la configuración del panel); hasta 10 claves por cuenta, cada una con un nombre, scopes y, opcionalmente, IP permitidas. Formato nuevo: vc_live_ + 48 caracteres hexadecimales, que se muestran una sola vez; las claves antiguas (64 caracteres hex) siguen siendo válidas con todos los scopes. Detalle completo en §16.

​
16. Referencia de la API

​
Autenticación

Envía una clave de API en la cabecera Authorization como token Bearer:

​
Claves de API

Una clave nueva tiene el prefijo vc_live_ seguido de 48 caracteres hexadecimales y se muestra una sola vez, al crearla o rotarla. Las claves antiguas de 64 caracteres hexadecimales siguen siendo válidas. Una cuenta puede tener hasta 10 claves, cada una con un nombre, scopes de acceso y una lista opcional de hasta 20 IP o CIDR permitidos. Una lista vacía permite llamadas desde cualquier dirección IP. La clave necesita el scope que exige el endpoint. Los presets read, write y full seleccionan conjuntos comunes; los scopes también se pueden elegir de forma individual. Los permisos de workspace también se aplican a las llamadas autenticadas con clave. La gestión de claves, la navegación por la pestaña Datos, el cambio a un plan inferior, las nuevas invitaciones, decidir sobre solicitudes de acción y consultar o exportar actividades requieren una sesión del panel. Una clave sin el scope necesario recibe 403 API_KEY_SCOPE_DENIED; una IP no permitida recibe 403 API_KEY_IP_DENIED. Una clave no válida recibe 401 API_KEY_INVALID. La gestión de claves se hace desde el panel.

​
Límites de peticiones

La API aplica límites fijos por ruta, además de límites por cuenta por minuto y por día para las llamadas con clave de API. La cuota diaria se renueva a medianoche, hora de Brasilia. Las respuestas autenticadas con clave incluyen x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, x-quota-limit, x-quota-remaining y x-quota-reset. Cuando se alcanza un límite, la respuesta es 429 RATE_LIMIT_EXCEEDED o 429 DAILY_QUOTA_EXCEEDED, con detalles y el tiempo para reintentar. Los límites fijos por ruta cubren las operaciones del ciclo de vida, el restablecimiento de bases de datos, los cambios de subdominio, las consultas de datos y la exportación de actividad.

​
Formato de respuesta

  • Éxito: { "response": { ... } }
  • Error: { "code": "ERROR_CODE", "message": "..." }

​
Códigos de error comunes

​
Endpoints principales

La lista siguiente corresponde a los endpoints públicos de la API. Los esquemas de petición y respuesta están en la Referencia de la API. Los límites por ruta se detallan en Limitaciones de la API.

​
Aplicaciones

​
Bases de datos

​
Usuarios y cuenta

​
Workspaces

​
Facturación

​
Canje

​
Servicios

​
17. Variables de entorno

  • Se inyectan en el contenedor al arrancar
  • Se gestionan desde el panel o la API
  • Límites: máximo 256 variables, la clave de hasta 255 caracteres y el valor de hasta 3.072 caracteres
  • Cifradas en reposo
  • Claves prohibidas: PORT, HOST, PATH, HOME, USER, SHELL
  • La plataforma define PORT=80 y HOST=0.0.0.0 en el contenedor

​
18. Limpieza automática (cuentas sin plan)

En una cuenta sin plan activo, los proyectos que permanecen sin conexión durante más de 30 días se eliminan automáticamente, con un snapshot previo:

​
19. Problemas frecuentes y soluciones

​
Plataforma

  • La aplicación se cae / OOMKilled: memoria insuficiente. Aumenta la RAM asignada. Java y Puppeteer necesitan 512 MB o más.
  • Bucle de fallos (reinicio automático desactivado): 5 fallos en 10 min. Revisa los logs, corrige el error de fondo y vuelve a desplegar.
  • La aplicación se detiene de inmediato (código de salida 0): el proceso no tiene nada que lo mantenga activo. Asegúrate de que el bot haya iniciado sesión o de que el servidor esté escuchando.
  • ZIP demasiado grande: excluye node_modules, venv, .git, vendor, target, __pycache__.
  • La instalación de dependencias supera los 15 minutos (INSTALL_TIMEOUT): elimina las dependencias innecesarias.
  • El comando de build supera los 10 minutos (BUILD_TIMEOUT): simplifica el build_command o el paso de build del framework.
  • El sitio agota el tiempo de espera: enlaza a 0.0.0.0 (no a localhost). Usa el valor de PORT.
  • El dominio personalizado no funciona: plan Intermediary o superior, CNAME correcto, espera a que se propague el DNS. Un dominio raíz necesita un proveedor DNS con CNAME flattening. Un dominio sin DNS durante 14 días se elimina; después borra sus registros CNAME y TXT en tu proveedor DNS.
  • Conexión a la base de datos rechazada: se requiere TLS. Descarga los certificados desde el panel.
  • PLAN_REQUIRED: la cuenta no tiene un plan activo. Suscríbete a un plan (Economy o superior) para crear aplicaciones y bases de datos o publicar un sitio.
  • No llega el correo: revisa el spam. Prueba con otro método (Discord, GitHub, Google).

​
Node.js / JavaScript

  • Cannot find module 'xxx': el paquete no está en dependencies de package.json (puede estar en devDependencies y la aplicación no tiene comando de build, ya que devDependencies solo se instalan cuando existe uno).
  • missing script: start: añade "start": "node index.js" en scripts dentro de package.json.
  • Cannot use import statement outside a module: añade "type": "module" a package.json, o usa require().
  • ERR_REQUIRE_ESM: el paquete solo admite ESM. Usa ESM o una versión anterior (por ejemplo: node-fetch@2).
  • ERESOLVE dependency tree: crea .npmrc con legacy-peer-deps=true.
  • EADDRINUSE: el puerto ya está en uso. Solo debe haber un app.listen() en el código.
  • Fallan los módulos nativos (better-sqlite3): no subas node_modules/. La plataforma compila para Linux.

​
TypeScript

  • tsx / ts-node: command not found: añade tsx a dependencies.
  • TSError: Unable to compile: incluye tsconfig.json. Corrige los errores de TS antes de desplegar.

​
Python

  • ModuleNotFoundError: el módulo no está en requirements.txt. Genéralo con pip freeze > requirements.txt.
  • requirements.txt no encontrado: revisa el nombre exacto y la extensión (cuidado con .txt.txt en Windows).
  • SyntaxError: invalid syntax: la versión de Python seleccionada no admite la función usada. Actualiza la versión.
  • UnicodeDecodeError: guarda los archivos en UTF-8. Usa encoding='utf-8' al abrir archivos.
  • Flask/Django no accesibles: usa Gunicorn: gunicorn app:app --bind 0.0.0.0:80.

​
Go

  • go.mod not found: ejecuta go mod init y go mod tidy. Incluye go.mod y go.sum.
  • Binario incompatible: compila para Linux: GOOS=linux GOARCH=amd64 go build.

​
Java

  • no main manifest attribute: configura la herramienta de build para crear un JAR con todas las dependencias y con Main-Class.
  • OutOfMemoryError: Java necesita 512 MB o más. Usa las opciones: -Xmx256m -Xms128m.

​
Discord Bots

  • Invalid token / Improper token: genera un token nuevo en el Developer Portal. Defínelo como variable de entorno.
  • DisallowedIntents: activa los intents privilegiados en el Developer Portal (Message Content, Server Members, Presence).
  • ClientMissingIntents: especifica los intents en tu código: new Client({ intents: [...] }).
  • El bot se desconecta aleatoriamente: memoria insuficiente o discord.js/discord.py desactualizado.
  • on_message no se dispara (discord.py): falta intents.message_content = True y activarlo en el Developer Portal.

​
Variables de entorno

  • Valores undefined/null: configúralos desde el panel, no dependas de un archivo .env.
  • .env no funciona: la plataforma no lee .env. Usa la interfaz de variables del panel.

​
20. Cupones de descuento

Un cupón puede ser un porcentaje o un importe fijo (se aplica una sola vez al total, sin dejar nunca el precio en negativo), puede tener un periodo de validez, un límite de canjes y restricciones de plan o de duración. Un pedido de R$0 (un cupón del 100 %) se entrega al instante, sin PIX. Un cupón rechazado en el pago devuelve uno de los códigos COUPON_INVALID, COUPON_INACTIVE, COUPON_NOT_STARTED, COUPON_EXPIRED, COUPON_EXHAUSTED, COUPON_USER_LIMIT, COUPON_AUDIENCE, COUPON_PLAN, COUPON_DURATION. Un cupón que excluye el método de pago elegido devuelve COUPON_PAYMENT_METHOD. Los descuentos por periodo de facturación (3 meses −5 %, 12 meses −15 %) se aplican antes del cupón.

​
21. Retención de datos

Qué guarda Vertra Cloud sobre tu cuenta y tus proyectos, y durante cuánto tiempo. El texto legal es la Política de privacidad; esta tabla es el resumen práctico. Tus peticiones con claves de API son visibles para ti en el panel, y el historial de actividad recoge los eventos del ciclo de vida, los cambios en el gestor de archivos, los snapshots restaurados, los dominios, los incidentes de protección, las compras, los canjes de código y las acciones iniciadas por un agente conectado.

​
22. Blob Storage

Blob Storage guarda archivos (imágenes, vídeos, copias de seguridad y otros recursos) para tus proyectos. Los archivos públicos tienen una URL pública, los privados se leen mediante enlaces temporales o páginas de compartición, y a los mismos archivos se puede acceder con un cliente compatible con S3. Está disponible desde Economy. El uso de Blob y su cuota pertenecen al propietario del workspace, así que un workspace usa la cuota de su propietario.

​
Cuota y límites por plan

​
Funciones según el plan

Las transformaciones de imagen se aplican mediante parámetros de URL (w, h, fit, format, q) en las imágenes públicas. Cada transformación distinta cuenta una vez al mes. Por encima del límite mensual se sirve la imagen original, sin error.

​
Límites para todos los planes

  • Subida simple: una petición de hasta 100 MB por archivo.
  • Subida directa: hasta 10 GB por objeto, enviado en partes directamente al almacenamiento, con reanudación y cancelación.
  • Ruta: de 1 a 1.024 caracteres, hasta 16 carpetas, cada parte de hasta 255 caracteres entre letras, dígitos, ., _, - y espacio. Todo archivo necesita una extensión.
  • Tipos bloqueados: exe, msi, dll, bat, cmd, com, scr, cpl, pif, hta, vbs, vbe, jse, wsf, wsh, msc, reg, lnk, sys, drv, ps1, apk, xpi, dmg, pkg, deb, rpm y appimage. Los ejecutables también se detectan por su contenido.
  • HTML, HTM, SVG, XML y XHTML siempre se descargan (attachment), nunca se muestran dentro de la página.
  • Reglas de carpeta definen valores por defecto para una carpeta: visibilidad, caducidad, tamaño máximo, extensiones, Cache-Control y eliminación tras un número de días (de 1 a 3.650).

​
Cuota, cambios a un plan inferior y periodo de gracia

  • Una escritura que supere la cuota de la cuenta se bloquea con STORAGE_QUOTA_EXCEEDED. Eliminar objetos libera espacio.
  • Tras un cambio a un plan inferior, tus archivos se mantienen. Si ocupan más que la nueva cuota, se bloquean las nuevas subidas y el exceso se cobra a R$0,20 por cada GB iniciado en la siguiente renovación.
  • Cuando el plan caduca, la cuenta entra en un periodo de gracia de 72 horas: las subidas y demás escrituras se bloquean (BLOB_NAMESPACE_SUSPENDED), mientras los archivos públicos, los enlaces temporales y las páginas de compartición siguen funcionando. Renovar dentro de esas 72 horas reactiva todo. Una suspensión por abuso es distinta: los archivos quedan fuera de línea de inmediato.
  • Tras el periodo de gracia, los archivos se eliminan. La eliminación es permanente y no hay copia de seguridad.
  • Las páginas de compartición se abren en el sitio web. Una compartición puede tener caducidad, un límite de descargas y, desde Enterprise-12, una contraseña. Una compartición no protege un objeto público.

​
Acceso

  • Scopes de clave de API: blob:read y blob:write. Permisos de workspace: blob:read y blob:manage. Una clave con solo scopes blob:* puede restringirse a una carpeta (blob_prefix, una ruta que termina en /): solo llega a los objetos, subidas y comparticiones dentro de esa carpeta, y las credenciales S3 derivadas de ella heredan el límite. Todo lo demás (reglas, dominios, estadísticas) responde 403 BLOB_PREFIX_DENIED. Un stack crea su propia clave restringida para su carpeta de Blob.
  • Token de subida: un token vcup_ de vida corta para navegadores. Fija la ruta o carpeta, el tamaño, las extensiones y la visibilidad, y solo se acepta en las rutas de subida.
  • Acceso compatible con S3: GET /v1/s3/credentials, limitado a 10 llamadas por hora. Revocar la clave de API que lo creó corta el acceso S3 de inmediato. Peticiones S3 por cada 10 segundos y por cuenta: Economy/Pro 100, Scale/Intermediary 200, Enterprise-4 a 8: 400, Enterprise-12 o más: 600; CopyObject/UploadPartCopy 20. Por encima: 503 SlowDown.
  • Cada ruta está documentada en su propia página, en Referencia de la API > Blob Storage.

​
Códigos de error de Blob

​
23. Plantillas y stacks

Una plantilla es una receta que crea software ya hecho (o un proyecto inicial) en una sola operación, tras unas cuantas preguntas. Un stack es el grupo de aplicaciones, bases de datos y carpetas de Blob que van juntas; una plantilla con más de un servicio crea uno. Guías: Plantillas.

​
Orígenes

Los usuarios no publican en el catálogo público desde el panel. Las plantillas privadas se crean en planes que pueden crear imágenes Docker, hasta 5 por cuenta; en un workspace solo el propietario las crea y gestiona. Un miembro del workspace no despliega plantillas en él: solo lo hace el propietario (WORKSPACE_OWNER_ONLY).

​
Plantillas de código e imagen

En ambos casos, /app es el disco persistente y el resto del sistema de archivos es de solo lectura; el usuario es 1000:1000.

​
Plan requerido

El plan necesario se calcula a partir de la plantilla y de tus respuestas, y puede subir por un min_plan que declara el autor: memoria libre para la suma de la memoria mínima de cada servicio, publicación web cuando un servicio la necesita, un plan con imágenes Docker y una ranura libre para una plantilla de imagen, un plan con Blob cuando la plantilla tiene una carpeta de Blob, y los límites de la cuenta de aplicaciones, bases de datos y despliegues por hora. Cuando no cabe, la API responde TEMPLATE_PLAN_REQUIRED, TEMPLATE_RAM_INSUFFICIENT o TEMPLATE_IMAGE_SLOTS_EXHAUSTED y el panel explica el motivo.

​
Uso de una plantilla

  • POST /v1/templates/{id}/deploy inicia un trabajo (202) que valida el plan y la memoria, crea las bases de datos y espera a que estén listas, crea las aplicaciones, escribe las variables, lo arranca todo y espera a la comprobación de salud. Cualquier fallo deshace todo lo que creó el trabajo (TEMPLATE_DEPLOY_FAILED, details.step); antes de eliminar una aplicación o una base de datos, la reversión toma un snapshot de seguridad. Una plantilla de un workspace solo se despliega dentro de ese workspace, y solo por su propietario. Envía un Idempotency-Key para que sea seguro repetirlo. Solo se ejecuta un despliegue de la misma plantilla a la vez (TEMPLATE_DEPLOY_IN_PROGRESS).
  • Las preguntas tienen tipos (text, secret, select, boolean, number, url, email); los secretos pueden generarse por ti. Las salidas, como la dirección o un token generado, se muestran al final; una salida secreta se muestra una sola vez.
  • Las actualizaciones nunca son automáticas: una versión nueva muestra Nueva versión disponible; actualizar toma antes un snapshot de seguridad, actualiza los servicios uno a uno y, si alguno falla, restaura todos. Los permisos nunca se vuelven más estrictos en una aplicación existente. Algunas plantillas bloquean el despliegue blue-green (dos copias en ejecución a la vez las romperían) y exigen que el rollback restaure también los datos (TEMPLATE_ROLLBACK_REQUIRES_DATA).
  • Cambiar el código de una aplicación de una plantilla abierta la desvincula de la plantilla; la API pide antes confirm_detach (TEMPLATE_DETACH_CONFIRMATION_REQUIRED).

​
Stacks

  • Las aplicaciones de un stack llegan a las bases de datos a través de la dirección pública, con certificados de cliente gestionados por la plataforma y excluidos de las descargas, los snapshots y «guardar como plantilla». Un modo de red distinto de public devuelve STACK_NETWORK_MODE_UNAVAILABLE.
  • Una conexión vincula una aplicación con una base de datos, una carpeta de Blob u otra aplicación. Sus variables están gestionadas: se actualizan cuando cambian la contraseña, el certificado o el host de la base de datos, y se marcan en el panel. Editarlas a mano las convierte en una variable normal. La API devuelve restart_required y apps_to_restart cuando las aplicaciones deben reiniciarse.
  • Un recurso pertenece como máximo a un stack, dentro de la misma cuenta o workspace que el stack. Un stack puede crearse desde una plantilla, desde el flujo /new, añadiendo una base de datos a una aplicación, o transformando una carpeta que contiene una aplicación y una base de datos.
  • Salir de un stack: conservar la conexión (las variables pasan a ser normales, con la dirección pública) o eliminarlas. Al eliminar un stack se pregunta si solo se deshace (los recursos se mantienen) o si se elimina todo; para la carpeta de Blob, la opción es keep (por defecto) o delete.
  • Las carpetas organizan, los stacks conectan: un stack tiene su propia tarjeta en la lista y su propio recuadro con las conexiones en Flow, y puede estar dentro de una carpeta.

​
Enlaces para compartir

Revocar un enlace detiene los nuevos usos y deja de ofrecer actualizaciones; lo que ya se creó sigue en ejecución, y eliminar la imagen, la plantilla o la cuenta originales no afecta a las copias. La vista previa muestra el autor, lo que se va a crear y No verificado por Vertra. Los enlaces pueden tener max_uses y una caducidad (SHARE_LINK_REVOKED, SHARE_LINK_EXPIRED, SHARE_LINK_EXHAUSTED). Usa Denunciar en una vista previa o en una aplicación creada; para casos graves con pruebas, escribe a [email protected]. Una aplicación que procede de un enlace de uso no se puede guardar como plantilla ni compartir (TEMPLATE_SAVE_NOT_ALLOWED).

​
Plantillas cerradas

Una plantilla privada puede cerrarse: quien la usa puede iniciar, detener, reiniciar, leer logs y métricas, crear snapshots y restaurarlos (solo en una aplicación de la misma plantilla), hacer rollback, responder a las preguntas, cambiar la memoria cuando se permita y actualizar. No pueden usar el gestor de archivos, descargar la aplicación o sus snapshots, crear variables libres, editar comandos, abrir una terminal, desplegar código, guardarla como plantilla ni desvincularla. La API lo aplica en todas las rutas (TEMPLATE_CLOSED); un snapshot de una aplicación cerrada nunca puede descargarse. Las bases de datos nunca se cierran. Las variables que el autor oculta (env_hidden, solo permitido en una plantilla cerrada) se inyectan y nunca se devuelven (MANAGED_ENV_READONLY); desvincular de la plantilla la aplicación o el stack elimina los valores ocultos.

​
Límites del manifiesto

vertracloud.template.yaml: hasta 40 preguntas, 16 salidas, 8 servicios y 10 etiquetas. Nombre de hasta 50 caracteres, descripción de hasta 128. El JSON Schema público es /templates/schema/v1.json. Los marcadores se resuelven en el servidor; un marcador o un servicio desconocido hace que el manifiesto no sea válido (TEMPLATE_MANIFEST_INVALID).

​
Códigos de error de plantillas y stacks

​
24. Glosario

Última modificación el 30 de octubre de 2026