Pular para o conteúdo principal
Esta página reúne, em um único documento, tudo o que a Vertra Cloud faz e com quais limites — planos e preços, linguagens e bancos de dados suportados, MCP, snapshots, workspaces, API, códigos de erro e soluções para os problemas mais comuns. Ela é a fonte da qual as demais páginas desta documentação são derivadas, e foi escrita para ser lida tanto por pessoas quanto por assistentes de IA.
Espelho: plans-and-limits publica as tabelas de limites de plano, runtime, banco, aba Data e deploy desta página de forma resumida. Mudou um número aqui? Atualize plans-and-limits, overview e api-reference/limitations na mesma rodada.

​
1. Visão geral

A Vertra Cloud é uma plataforma brasileira de hospedagem em nuvem para fazer deploy de aplicações e bancos de dados gerenciados. Ela suporta 13 linguagens, 4 tipos de banco de dados, monitoramento em tempo real, domínios personalizados, um servidor MCP para o seu agente de IA, workspaces colaborativos e uma extensão para VSCode. SLA: 99,99% de disponibilidade, em todos os planos. Este é o único número de SLA que a plataforma declara — o marketing, os cards de planos, a página do Enterprise, os Termos de Uso e a documentação pública dizem 99,99% e nada além disso.
  • Site: https://vertracloud.app
  • Dashboard: https://vertracloud.app/dashboard
  • API: https://api.vertracloud.app
  • Documentação: https://docs.vertracloud.app
  • CLI (guia): curl -fsSL https://cli.vertracloud.app/install | sh no macOS/Linux, irm https://cli.vertracloud.app/install | iex no Windows (PowerShell)
  • Servidor MCP (guia): endpoint remoto https://mcp.vertracloud.app/mcp (OAuth), ou local com npx -y @vertracloud/mcp e um VERTRA_API_KEY
  • SDKs (guia): npm install @vertracloud/sdk-api · pip install vertracloud-api · go get github.com/vertracloud/sdk-api-go
  • Extensão do VS Code (guia): code --install-extension VertraCloud.vertra-cloud
  • GitHub Actions (guia): vertracloud/github-action

​
2. Linguagens suportadas

As versões são atualizadas regularmente com atualizações de segurança. Uma versão que chegou ao fim do suporte é removida da lista. Se a versão salva em uma aplicação não estiver mais disponível, a plataforma usa a release mais nova da mesma linha (por exemplo, 3.11 roda na 3.11.17); se a linha inteira foi removida, ela volta para a versão recommended.

​
Detecção de linguagem

A plataforma detecta a linguagem pelos arquivos de manifesto na raiz do projeto, verificando cada ecossistema antes do package.json: um projeto Python, PHP (Laravel) ou Ruby (Rails) que também tenha um package.json de front-end continua sendo Python, PHP ou Ruby. O bun.lock é reconhecido como Bun, e projetos Java também são reconhecidos por build.gradle.kts, settings.gradle(.kts), mvnw e gradlew. MAIN=./src/index.js (com o ./ inicial) é aceito. Para forçar uma linguagem, defina LANGUAGE=<slug> em vertracloud.config (por exemplo LANGUAGE=deno) ou envie language em POST /v1/apps. Em vertracloud.config.json a chave é "language". A precedência é: campo da API, depois o arquivo de configuração, depois a detecção. Um valor desconhecido é recusado com INVALID_LANGUAGE (HTTP 400).

​
Deno, .NET e Elixir

O Phoenix é suportado: defina SECRET_KEY_BASE e PHX_HOST como variáveis de ambiente. Execute mix assets.deploy antes de gerar o zip, ou use um projeto sem assets.

​
3. Bancos de dados

Você escolhe a versão ao criar um banco (o seletor no dashboard, ou version na API); a recomendada é a padrão. Bancos existentes mantêm a versão principal, e as atualizações de segurança (releases de patch) são aplicadas automaticamente sempre que o banco é reiniciado (parar e depois iniciar, no dashboard). Se você usar índices btree_gist em colunas float ou índices ltree no PostgreSQL, execute REINDEX neles após o reinício. Bancos MySQL 8.0 existentes continuam na 8.0, que não está disponível para novos bancos. Bancos Redis 7.4 existentes continuam na 7.4. Um banco criado a partir de um snapshot nasce na versão principal do snapshot (um snapshot de MySQL 8.0 cria um banco MySQL 8.4, e um snapshot de Redis 7.4 cria um Redis 8.2); version pode ser igual ou mais nova, nunca mais antiga (SNAPSHOT_VERSION_NEWER). Restaurar um snapshot feito em uma versão mais nova em um banco mais antigo é recusado com o mesmo código, e nada é alterado. vertracloud é o usuário dos bancos criados a partir da v26.4.8, e não é superusuário. Bancos mais antigos mantêm o usuário do motor: postgres (banco postgres), default no MongoDB (banco de autenticação admin) e no Redis, e root (banco default) no MySQL. O campo username do banco na API indica qual usar. A porta é única por banco — não é a padrão do motor — e aparece na página do banco. Todos os bancos geram certificados TLS automaticamente (CA, servidor, cliente). Todo motor exige TLS e certificado de cliente — só a senha nunca conecta.

​
Como conectar a cada banco

  • Host: <database-id-sem-hifens>.db.usa1.vertraweb.app. Porta: única por banco (não 5432/27017/6379/3306) — copie-a na página do banco ou em GET /v1/databases/{id}.
  • Arquivos (aba Certificados ou GET /v1/databases/{id}/credentials/certificate): certificate-<id>.crt = certificado de cliente, certificate-<id>.key = chave privada do cliente, certificate-<id>.pem = pacote com a chave privada do cliente + certificado do cliente + a CA. Use o .pem como arquivo de CA em todos os lugares, e como arquivo de chave e certificado no MongoDB.
  • O certificado do servidor corresponde ao host, então a verificação completa funciona.
Exemplos em Node.js para cada driver (pg, mongodb, ioredis, mysql2) estão na página Bancos de dados. RAM mínima: 1.024 MB para PostgreSQL, MongoDB e MySQL; 512 MB para Redis. Armazenamento: 6 GB + 1 GB a cada 512 MB de RAM alocada, arredondado para cima em GB, ou 3× a RAM quando esse valor for maior (a partir de 6 GB de RAM) — a cota é sempre um número inteiro de GB (ex.: 512 MB → 7 GB; 1 GB → 8 GB; 2 GB → 10 GB; 4 GB → 14 GB; 8 GB → 24 GB). Nenhum banco existente perde espaço quando a fórmula muda — o teto só aumenta. Operações: Iniciar, Parar, Reiniciar, Redefinir (ação destrutiva, limitada a 1 por hora), Redefinir senha, Redefinir certificados, Download/Restauração de snapshot.

​
Gerenciador de dados (a aba “Data”)

Navegue e edite o conteúdo do banco pelo dashboard, sem expor a senha nem a string de conexão. Somente no dashboard; não está disponível pela API. SQL: schemas, tabelas, colunas, índices, linhas e um console SQL. MongoDB: coleções, índices e documentos. Redis: chaves via SCAN, valor por tipo, TTL. Plano mínimo: Intermediary. A aba inteira é liberada a partir do Intermediary. A verificação considera o plano do dono do banco, não o plano de quem está acessando — um membro do workspace sem plano pode usar a aba Data em um banco cujo dono tem o plano exigido, e um dono sem plano não ganha o recurso convidando alguém de um plano superior. Abaixo disso, o dashboard mostra o card de plano em vez do explorador. Permissão: o acesso de leitura é concedido a qualquer membro do workspace; o acesso de escrita e o console SQL são exclusivos do dono ou de admin (o dono do banco sempre pode fazer). Toda alteração vira uma atividade no log do banco, com a operação e o objeto — nunca o conteúdo. O que deliberadamente não existe: comando administrativo ou execução de código arbitrário no console do Redis ou do Mongo. No SQL, o limite é tempo, tamanho e concorrência.

​
4. Planos e preços

Nenhum plano tem teto de quantidade. O limite real é a RAM do plano, e o que recusa uma criação é MEMORY_LIMIT_EXCEEDED — uma aplicação de 100 MB cabe 10 vezes em um plano Pro. Mínimos que consomem essa RAM: aplicação 100 MB, Redis 512 MB, Postgres/MySQL/Mongo 1.024 MB.

​
vCPU por aplicação

A coluna vCPU da tabela acima é o teto por aplicação no plano, não um total dividido entre os projetos da conta. Dentro desse teto, o vCPU de um projeto cresce com a RAM do projeto:
  • Crescimento: em planos com até 2 vCPU, +1 vCPU a cada 512 MB de RAM; em planos com mais de 2 vCPU, +1 vCPU a cada 1 GB (1.024 MB).
  • Piso: um projeto com 512 MB ou mais recebe pelo menos 2 vCPU; abaixo de 512 MB, pelo menos 1 vCPU.
  • Teto: nunca mais que o vCPU do plano. Economy (0,3) e Pro (0,5) sempre dão ao projeto o vCPU total do plano.
A mesma regra vale para os bancos de dados. Mais RAM nunca resulta em menos vCPU. Uma mudança passa a valer na próxima vez que o projeto reiniciar ou receber um deploy.

​
Agentes de IA (MCP)

A Vertra não hospeda chat nem modelo de IA. Conecte Claude, Codex, Cursor ou outro cliente MCP ao servidor oficial para operar aplicações, bancos de dados, arquivos, logs e deploys com a sua chave de API. As validações internas acontecem durante o ciclo de vida da aplicação, como deploy, rebuild e restart; elas não são uma superfície de produto separada.

​
Preços do Enterprise

​
Nomes dos planos

A API identifica um plano pelo seu nome; não existe ID numérico de plano. GET /v1/users/me retorna plan com name, memory, expires_at e duration, ou plan: null para uma conta sem plano ativo. Aplicações, bancos e workspaces carregam o plano do dono em owner_plan (o nome, ou null). Compare planos pelo nome, nunca pela posição nesta lista. Código que lia plan_id, plan.id ou owner_plan_id deve ler plan.name e owner_plan (quebra de compatibilidade da API, dos SDKs, da CLI e do MCP).

​
Recursos por plano

Versões anteriores mantidas conta as versões além da que está rodando agora. Validade da versão conta a partir do momento em que uma versão deixa de ser a que está rodando; a versão em execução nunca expira. O Enterprise mantém 15 versões nos níveis E-4, E-6 e E-8, 20 em E-12, E-14 e E-16, 25 de E-18 a E-24, e 30 de E-26 a E-32.
Rollback automático e Deploys sem downtime são configurações de deploy, alteradas nas configurações da aplicação ou com PATCH /v1/apps/{id}/config (deploy). Pedir qualquer uma delas em um plano que não a inclui falha com 403 PLAN_DOES_NOT_SUPPORT_AUTO_ROLLBACK ou 403 PLAN_DOES_NOT_SUPPORT_ZERO_DOWNTIME; desligá-las é sempre permitido.
O gerenciador de arquivos é a aba Arquivos do dashboard e as suas rotas HTTP; as regras de propriedade e de caminho seguem as mesmas na API, na CLI e no MCP.
Três coisas diferentes que a documentação costuma misturar:
  • Publicar (Pro+) — ter um site: a aplicação recebe um subdomínio *.vertraweb.app e fica acessível pela internet. No Pro, o subdomínio é atribuído aleatoriamente pela plataforma. No Pro, as páginas HTML do site também exibem o selo “Powered by Vertra Cloud” no canto inferior direito; a partir do Scale ele não aparece. Trocar de plano liga ou desliga o selo imediatamente, sem novo deploy.
  • Escolher o subdomínio (Scale+) — escolher o nome do subdomínio, na criação ou depois (PATCH /v1/apps/{id}/network/subdomain). Sem isso, o usuário pode publicar, mas não pode escolher o nome.
  • Domínios personalizados (Intermediary+) — apontar domínios que você possui para a aplicação, quantos o plano permitir (veja Domínios personalizados).

​
Conta sem plano ativo

Uma conta sem plano ativo não pode criar aplicações ou bancos de dados nem publicar um site: essas requisições são recusadas com PLAN_REQUIRED (403). Assine um plano, a partir do Economy, para continuar.
  • Projetos offline há 30 dias ou mais são excluídos automaticamente, com um snapshot feito antes
  • Notificações por e-mail nos dias 7, 23 e 27 antes da exclusão

​
Períodos de cobrança e pagamento

  • Períodos: 1, 3 ou 12 meses. Uma compra de 3 meses tem 5% de desconto e uma compra de 12 meses tem 15% de desconto sobre o preço mensal. O Economy é somente mensal.
  • Formas de pagamento: PIX ou cartão de crédito (Visa e Mastercard). O Economy aceita somente PIX, então nunca renova sozinho. Um cupom pode restringir um pedido a uma forma de pagamento.
  • Preços são sempre em R$. O site mostra um valor aproximado em dólar americano ao lado do preço (≈ $) apenas como referência; a cobrança é em reais.
  • Cartão = renovação automática. Um cartão é salvo na conta e o plano renova no cartão padrão, sem período de fidelidade. Três dias antes de o plano expirar, o cartão é cobrado e um e-mail é enviado no mesmo dia. Se a cobrança falhar, ela é tentada novamente em cada um dos 2 dias seguintes e no dia do vencimento; se todas as tentativas falharem, o plano expira normalmente. Se o banco pedir confirmação, você recebe um e-mail para confirmar o pagamento. Para parar a renovação automática, use Cancelar renovação no card do Plano em Faturamento: o plano continua ativo até a data de expiração e o cartão continua salvo.
  • PIX não renova. Você só recebe o aviso de expiração habitual e paga de novo quando quiser.
  • Pedidos não pagos expiram. Um pedido que não é pago fica aberto por 72 horas após a criação; depois disso expira e não pode mais ser pago. Você recebe um e-mail quando um pedido fica aberto, e lembretes com 48 horas e 24 horas restantes.
  • QR codes PIX valem até 30 minutos. Se um QR code expirar enquanto o pedido ainda estiver aberto, gere um novo para o mesmo pedido.
  • Dados de cobrança são obrigatórios para comprar um plano. Eles são necessários para emitir a nota fiscal de serviço (NFS-e). No Brasil: nome, CPF ou CNPJ e o endereço completo (CEP, rua, número e bairro; cidade e estado são preenchidos pelo CEP). Fora do Brasil: nome, rua, cidade, país e código postal. O telefone é opcional. Preencha-os em Faturamento; se estiverem faltando, o checkout pede antes do pagamento. Pela API, um pedido sem eles falha com BILLING_DETAILS_INCOMPLETE.
  • Onde ficam os dados de pagamento. Número do cartão, validade e CVV são digitados em um campo da Stripe e tokenizados no navegador; eles nunca chegam à Vertra. Os dados de cobrança (nome, endereço, telefone, CPF/CNPJ) são armazenados pela Stripe, não pela Vertra. A Vertra guarda apenas a bandeira do cartão, os 4 últimos dígitos e a validade, para listar os cartões salvos.
  • Reembolsos. A primeira compra de um plano pago pode ser reembolsada integralmente em até 7 dias. Uma renovação automática no cartão também pode ser reembolsada integralmente em até 7 dias após a cobrança; o plano volta à data de expiração anterior. Renovações que você faz manualmente, upgrades e mudanças de plano não são reembolsáveis. Solicitações vão para [email protected].
  • Notas fiscais (NFS-e): a nota fiscal de serviço brasileira (NFS-e) é emitida automaticamente para cada pedido pago e enviada por e-mail, em nome e com o CPF/CNPJ dos seus dados de cobrança. Um reembolso total cancela a nota fiscal.

​
5. Tipos de aplicação

Limite de nome de exibição para aplicação, banco de dados e workspace: no máximo 50 caracteres. O tipo não é decidido de uma vez por todas na criação. Uma aplicação criada sem publicação web pode ser publicada depois (POST /v1/apps/{id}/network/publish) e despublicada novamente (DELETE /v1/apps/{id}/network/publish), o que alterna o tipo entre 1 e 2. Duas consequências que os usuários precisam conhecer:
  • Ligar e desligar recria o container, então a aplicação reinicia — regras de rede e a porta exposta só existem a partir do momento em que o container é criado.
  • Ao desligar, o subdomínio é liberado: não há reserva, e outra pessoa pode reivindicá-lo. Todo domínio personalizado também é removido, e seus registros CNAME e TXT de validação permanecem no provedor de DNS do usuário até que ele os apague.
A publicação exige 512 MB de RAM. A RAM não aumenta sozinha neste fluxo: com menos que isso, a chamada retorna MEMORY_BELOW_MINIMUM com details: { current_mb, minimum_mb }. Aplicações a partir de uma imagem Docker personalizada. No Enterprise 28, Enterprise 30 e Enterprise 32, uma aplicação pode rodar a partir de uma imagem construída a partir do Dockerfile do próprio cliente. Ela é criada com POST /v1/apps/image, e pode ser um Bot (web: false) ou um Website (web: true). Regras a declarar com precisão:
  • Contexto de build: ZIP de até 100 MB, ou um repositório do GitHub, com um arquivo chamado exatamente Dockerfile na raiz. Até 20 imagens por conta, contando todos os estados. Plataforma linux/amd64.
  • Build: ambiente de build isolado, limite de tempo de 26 minutos, imagem construída de até 10 GB descompactada (IMAGE_TOO_LARGE). Arquivos .env* são removidos do contexto.
  • Runtime: sempre o usuário 1000:1000. /app é o disco persistente; /tmp, /var/tmp e /run são graváveis, mas temporários; todo o resto é somente leitura. A porta é a primeira EXPOSE ou 80, injetada como PORT.
  • Recusado: um # syntax= diferente do frontend oficial, RUN --security=insecure, RUN --network=host, --mount=type=ssh, --mount=type=secret. Gera aviso: WORKDIR /app, .env* no contexto, COPY/ADD de .env, VOLUME fora de /app.
  • Atualizações: rebuild por upload, commit (sobre o contexto atual) ou push para uma branch do GitHub vinculada. Um rebuild nunca reinicia aplicações. Cada aplicação mantém 30 releases por 30 dias, e o rollback usa uma versão já construída.
  • Snapshots guardam os dados de /app e a versão da imagem; a restauração pode, opcionalmente, voltar para essa versão.
  • Excluir uma imagem exclui todas as aplicações criadas a partir dela. Planos abaixo do Enterprise 28 não podem criar nem reconstruir imagens; o downgrade para um plano com menos vagas que as imagens em uso (próprias e de templates de imagem) é recusado: apague imagens antes.
Imagens e templates. Um template de imagem ocupa um slot de imagem por imagem distinta em uso, nunca um por aplicação: três aplicações a partir do mesmo template usam um slot, e uma nova versão do template mantém o mesmo slot. Um template de código não usa nenhum. O slot é liberado quando a última aplicação que usa a imagem deixa de existir. POST /v1/apps/image recusa uma imagem que pertence a um template (IMAGE_TEMPLATE_ONLY): a única forma de rodá-la é pelo template. Uma imagem que é a origem de um dos seus templates privados não pode ser excluída antes que você a remova do template (IMAGE_IN_USE). Veja Templates e stacks. Guia: Imagens Docker personalizadas.

​
Armazenamento

Toda aplicação recebe 10 GB de armazenamento, independentemente da RAM alocada (antes de 14/09/2026 o teto era 6 GB + 2 GB a cada 2 GB de RAM). Ultrapassar o teto recusa gravações; reduzir a RAM não diminui o teto de armazenamento, que é fixo por aplicação.

​
Limites de banda por memória

Acima de 10 GB de RAM, o limite cresce cerca de 50 Mbit a cada 256 MB adicionais.

​
Ciclo de vida

A criação é assíncrona. POST /v1/apps responde 202 Accepted imediatamente com a aplicação em status: "building"; a instalação e o build continuam em segundo plano, com logs ao vivo. O status vira up ou down quando o build termina — acompanhe-o com GET /v1/apps/{id} ou pelo stream de logs em tempo real. Enquanto o status for building, iniciar, parar, reiniciar, deploys de arquivos (upload, commit), rollback, snapshots, restaurações e alterações de configuração respondem 409 APP_BUILDING; excluir a aplicação é permitido. Se o build não terminar, a aplicação permanece down e BUILD_INTERRUPTED aparece no log dela. Quando um build ou uma instalação falha, GET /v1/apps/{id} traz o código em last_build_error (null após um build bem-sucedido). Se a plataforma cancelar a criação (por exemplo, quando a fila está cheia), a aplicação deixa de existir e GET responde 404.

​
Comando de build (build_command)

Campo opcional por aplicação, disponível em todos os planos. Ele roda a cada deploy — criação, upload de zip, deploy do GitHub, reinstalação de dependências ou alteração do próprio comando —, sempre depois da instalação de dependências e antes de a aplicação iniciar. Um restart simples não roda o build de novo se o build anterior teve sucesso com o mesmo comando. O build roda em um ambiente de build isolado da aplicação: 2× a RAM da aplicação (mínimo 1.024 MB, máximo 4.096 MB), com limite de tempo de 10 minutos. Se o comando falhar → o deploy falha e a aplicação não inicia (BUILD_FAILED); se estourar o tempo → BUILD_TIMEOUT. Na criação, uma instalação ou build com falha ainda cria a aplicação, parada, com a saída nos logs; o usuário corrige os arquivos e a inicia novamente. Quando a aplicação tem um comando de build, a instalação de dependências também inclui devDependencies (Tailwind, TypeScript, PostCSS e ferramentas semelhantes funcionam sem precisar movê-las para dependencies); sem comando de build, só dependencies são instaladas. O Puppeteer usa o Chromium já disponível na imagem de runtime, então nenhum navegador é baixado durante a instalação. O ambiente de build tem o dobro da banda da aplicação (a mesma tabela de banda por RAM, ×2) — baixar dependências pesa mais que servir tráfego, e a janela é curta. Ultrapassar o limite interrompe o deploy, da mesma forma que acontece com a aplicação enquanto ela está rodando. Exemplos comuns: A aplicação precisa escutar na porta 80 — isso vale para toda aplicação do tipo Website, com ou sem build_command. Ao criar uma aplicação pelo dashboard a partir de um zip, a plataforma sugere os comandos de build e start acima com base nas dependências declaradas no package.json (Next.js, Nuxt, SvelteKit, Remix, React Router, Astro, Gatsby e Vite); o usuário pode editar os dois antes de criá-la. Um projeto sem framework reconhecido inicia pelo arquivo principal, sem comando de build.

​
Arquivo de configuração (vertracloud.config)

Um arquivo opcional KEY=value na raiz do zip enviado. Ele apenas preenche previamente o formulário de criação/upload — a configuração de fato fica no dashboard (aba Configurações). Chaves reconhecidas: NAME, DESCRIPTION, MAIN, MEMORY, START, BUILD, VERSION, SUBDOMAIN, LANGUAGE; qualquer outra chave (inclusive a antiga AUTORESTART) é ignorada. VERSION preenche previamente o assistente no upload do zip e é usada na criação a partir de um snapshot; a versão confirmada no assistente é a que a aplicação roda, e uma versão que não existe para a linguagem é recusada com INVALID_VERSION. vertracloud.config.json também é aceito, com chaves em minúsculas. Se o zip tiver .env.production, .env.production.local, .env.local ou .env (nessa ordem), o fluxo de criação preenche previamente as variáveis de ambiente com as da primeira que não estiver vazia.
O arquivo não existe no volume da aplicação (desde 14/09/2026). Ele é descartado quando o zip é extraído e gerado a partir do banco de dados com os valores atuais ao baixar o projeto ou criar um snapshot — por isso um zip baixado ou um snapshot restaurado sempre volta com a configuração atual. Ele não aparece no gerenciador de arquivos; um arquivo com esse nome criado manualmente é ignorado e sobrescrito no download.

​
Subdomínios

  • Formato: your-app.vertraweb.app
  • Único por aplicação
  • Publicação web (obter um subdomínio) disponível a partir do plano Pro
  • Escolher o nome do subdomínio exige o plano Scale+; abaixo disso a plataforma atribui um nome aleatório
  • Formato aceito na escolha: de 3 a 50 caracteres, ^[a-z0-9][a-z0-9-]*[a-z0-9]$
  • Pode ser renomeado depois via PATCH /v1/apps/{id}/network/subdomain (mínimo de 5 minutos entre alterações)

​
Domínios personalizados

  • Disponível a partir do plano Intermediary. Domínios por aplicação (o www ou o domínio raiz automático não conta): Economy, Pro e Scale 0; Intermediary 1; Enterprise-4 a 8: 2; Enterprise-12 a 24: 5; Enterprise-26 a 32: 20
  • A aplicação precisa estar publicada na web. Adicionar, alterar ou remover um domínio não reinicia nem faz redeploy dela
  • Configure os registros de DNS exibidos para o domínio (um CNAME e, normalmente, um registro de validação de certificado). A configuração automática de DNS ainda não está disponível: POST /v1/apps/{id}/domains/{domain_id}/connect sempre responde DOMAIN_CONNECT_UNAVAILABLE
  • SSL provisionado automaticamente após a validação do DNS
  • www automático: adicionar example.com também adiciona www.example.com (e vice-versa). O domínio complementar redireciona para o domínio principal com 308, não conta no limite, é removido junto com o domínio principal e pode ser desativado com www: false. Qualquer um dos dois pode virar o domínio principal (primary: true)
  • Domínios raiz precisam de um provedor de DNS que suporte CNAME flattening, ALIAS ou ANAME; o dashboard avisa sobre isso
  • Porta por domínio: qualquer porta de 1 a 65535 (padrão 80), até 5 portas diferentes além da 80 por aplicação (DOMAIN_PORT_LIMIT_REACHED acima disso)
  • Prefixo de caminho por domínio (caminho literal como /api, começa com /, sem / no final): adicionado antes de toda requisição. Recomendado para APIs; um site precisa rodar sob esse caminho
  • Redirecionamento por domínio para outro domínio da mesma aplicação, com status 301, 302, 307 ou 308 (padrão 308), mantendo o caminho e a query string. Um redirecionamento não pode apontar para outro redirecionamento
  • Status por domínio: pending (aguardando DNS), active, moved (o DNS deixou de apontar para a Vertra Cloud) ou deleted; além do estado do certificado (pending, active, failed)
  • Um domínio que fica em pending, moved ou deleted por 14 dias é removido automaticamente e o dono é avisado por e-mail
  • Despublicar a aplicação remove todos os seus domínios
  • Limpe o seu DNS depois que um domínio deixar de existir (removido por você, por despublicação ou pela limpeza de 14 dias): apague os registros CNAME e TXT de validação no seu provedor de DNS. Remover um domínio não mexe no seu DNS; se os registros permanecerem, o nome continua apontando para a Vertra Cloud e outro cliente pode reivindicá-lo
  • Rotas: 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. Leituras precisam do escopo apps:read; escritas precisam de apps:write

​
6. Reinício automático e detecção de crash loop

  • Containers que travam são reiniciados automaticamente — o padrão em todos os planos, sempre ativo, sem opção de desligar
  • O código de saída 0 (término normal) NÃO dispara um reinício. Também não disparam erros que um reinício não resolve: erros de sintaxe, módulos ausentes, falta de memória, uma instalação ou build com falha, ou uma pausa do Vertra Shield
  • Todo outro crash é reiniciado, mesmo que a aplicação tenha ficado no ar por apenas alguns segundos, com espera crescente entre as tentativas: imediatamente, depois 10 s, 30 s, 60 s e 2 min
  • Crash loop: até 5 reinícios automáticos em uma janela de 10 minutos. O 6º crash nessa janela suspende o reinício automático por 24 horas: a aplicação fica parada e o dashboard informa o motivo
  • Iniciar ou reiniciar a aplicação manualmente zera a contagem de crashes e levanta a suspensão
  • Uma aplicação que fica no ar por 10 minutos sai da janela, então os crashes antigos deixam de contar

​
7. Proteções da plataforma (Vertra Shield)

O Vertra Shield protege todas as aplicações e bancos de dados da plataforma. Em situações que possam afetar a disponibilidade, o Shield pode pausar uma aplicação temporariamente; o dashboard mostra o motivo e uma contagem regressiva.

​
Limite de requisições por IP de visitante

Aplicações em *.vertraweb.app e em domínios personalizados têm um limite de quantas requisições um único IP de visitante pode enviar. Um visitante que ultrapassa o limite é bloqueado temporariamente, antes que o tráfego chegue à aplicação. Picos repentinos de tráfego de muitos visitantes diferentes não pausam a aplicação. Se a sua aplicação recebe legitimamente um volume alto de tráfego de um único IP, como uma integração servidor a servidor ou webhooks, entre em contato com o suporte.

​
Cooldown do Shield (pausa visível)

Quando o Shield pausa uma aplicação, o dashboard mostra um aviso com o motivo e o tempo restante, e as ações de start e restart ficam temporariamente indisponíveis. O cooldown pode crescer após ocorrências repetidas, até o limite de 1 hora. O Shield apenas para a aplicação — ele nunca a exclui, nem os seus arquivos ou dados. Start, restart, deploy, alterações de configuração e exclusão da aplicação aguardam o fim da pausa: essas ações respondem 403 com o erro APP_SHIELD_COOLDOWN, e details traz o motivo e o momento em que a pausa termina.

​
Restrições de acesso por região (*.vertraweb.app)

  • Bloqueados (sanções ou restrições regulatórias): Afeganistão (AF), Belarus (BY), Cuba (CU), China (CN), Irã (IR), Coreia do Norte (KP), Rússia (RU), Síria (SY), Antártida (AQ) e todos os nós de saída do Tor (T1).
  • Verificação de navegador (motivos de segurança): Bangladesh (BD), Índia (IN), Iraque (IQ), Filipinas (PH), Ucrânia (UA), Venezuela (VE), Vietnã (VN), Indonésia (ID) e Malásia (MY). Só passa pela verificação uma pessoa em um navegador; clientes de API e remetentes de webhooks desses países recebem 403.

​
8. SSL/TLS

  • Todos os sites recebem certificados SSL/TLS automáticos
  • Renovação automática antes do vencimento
  • Redirecionamento de HTTP → HTTPS habilitado por padrão
  • Domínios personalizados também recebem SSL automático
  • Todas as conexões com bancos de dados exigem TLS

​
9. Snapshots

  • Criação manual de snapshots para aplicações e bancos — no máximo 1 a cada 5 minutos no mesmo projeto e 10 por hora em todos os recursos da conta; ao exceder qualquer um dos dois, a resposta é SNAPSHOT_RATE_LIMITED (429) com details: { scope: "resource" | "account", retry_after }
  • Restauração de qualquer snapshot anterior (cooldown de 30 segundos)
  • Download do conteúdo do snapshot como ZIP
  • Disponível a partir do plano Scale (backups manuais)
  • Excluir ou redefinir um banco faz automaticamente um snapshot de segurança antes de destruir os dados, em todos os planos. Se o backup falhar, a ação é bloqueada (SNAPSHOT_FAILED) e o banco não é excluído nem redefinido. Este snapshot forçado tem um teto próprio, separado do da criação manual: no máximo 2 tentativas por hora no mesmo projeto, e 10 por hora em todos os projetos da conta — ao exceder qualquer um dos dois, a resposta é FORCED_SNAPSHOT_RATE_LIMIT e a ação também é bloqueada.
  • Excluir uma aplicação faz o mesmo snapshot de segurança a partir do plano Pro (o plano do dono). Se ele falhar, a aplicação não é excluída (SNAPSHOT_FAILED); o mesmo teto se aplica. No Economy a aplicação é excluída na hora, sem cópia, e o dashboard oferece baixar o projeto antes. A expiração do plano ainda faz snapshot de todos os projetos antes de removê-los, em todos os planos.

​
10. Workspaces

Colaboração em equipe com permissões granulares e papéis personalizáveis. Disponível somente no plano Enterprise. O dono do workspace mantém o controle das ações de gestão exclusivas do dono.

​
As 20 permissões

Ações que são exclusivas do dono, independentemente de qualquer papel: vincular/desvincular um projeto, renomear/excluir o workspace, o webhook de deploy do GitHub e ligar/desligar a publicação web.

​
Papéis iniciais

Todo workspace nasce com 4 papéis, que podem ser renomeados e excluídos (eles viram papéis comuns e contam para o teto do nível como qualquer outro):

​
Teto de papéis personalizados por nível (Enterprise)

Os 4 papéis iniciais contam para o teto.

​
Membros por nível (Enterprise)

A progressão nunca diminui ao subir de nível (5 no mínimo e 24 no máximo). Um convite pendente conta.

​
Convites

Duas formas, ambas exigindo members:manage:
  • E-mail: vinculado a um endereço específico, expira em 7 dias. WORKSPACE_INVITE_EMAIL_MISMATCH se for aceito por uma conta com outro e-mail.
  • Link: de uso múltiplo, com expiração fixa de 24 h, max_uses opcional. Pode ser revogado a qualquer momento.
Um convite pode trazer expires_in_days — uma expiração de acesso aplicada ao membro que entra por ele; null/ausente = sem expiração. Um convite pendente conta no limite de membros do plano. Toda conta tem a opção workspace_invites_enabled (APIUser) para recusar convites por e-mail; quando ela está desligada, um novo convite por e-mail para essa conta falha com WORKSPACE_INVITES_DISABLED.

​
Pastas e favoritos

Pastas e favoritos organizam aplicações e bancos sem alterar os recursos. A organização é persistida na conta e tem dois escopos:
  • Pessoal: a visão individual da conta, retornada por GET /v1/users/me.
  • Workspace: a visão individual do membro dentro de um workspace, retornada por GET /v1/workspaces/:id. Não é compartilhada com os outros membros.
Uma pasta tem nome, cor, posição e referências a aplicações ou bancos. As cores permitidas são neutral, red, orange, yellow, green, blue e purple. resource_type aceita somente application e database. Favoritos e pastas são independentes entre si. Criar, editar, excluir, mover e favoritar gera uma atividade. A ação pode vir do dashboard, de um workflow ou de um cliente autenticado com chave de API, como a CLI, o MCP e a extensão do VS Code. O cliente não envia origin nem author_id; a API registra a origem e o autor automaticamente. A lista de projetos e o Flow usam a mesma organização persistida. No Flow, a pasta e o favorito aparecem junto dos recursos, mas os grupos criados no canvas continuam locais e independentes. Pastas não são grupos do Flow. Um grupo organiza elementos no canvas local do Flow, enquanto uma pasta organiza recursos dentro da conta ou do workspace. Não existe group_id, sincronização nem migração entre os dois conceitos.

​
Solicitações de ação

Um membro que não tem a permissão para uma ação sensível (app_delete, database_delete, snapshot_create, snapshot_restore) pode abrir uma solicitação de ação; quem tiver members:manage e a permissão para essa ação aprova ou rejeita. Ela expira em 24 h sem decisão (WORKSPACE_ACTION_REQUEST_EXPIRED).

​
Retenção

Excluir um workspace é uma exclusão lógica: o nome volta a ficar disponível para um novo workspace. Um plano Enterprise expirado congela as gravações (convites, ações, edições), mas nunca apaga dados.

​
Rota → permissão

​
Códigos de erro

​
11. Gerenciador de arquivos

  • Disponível a partir do plano Pro
  • Navegue e edite arquivos diretamente no dashboard
  • Realce de sintaxe para todas as linguagens
  • Upload por arrastar e soltar (arquivos ou ZIP); o Destino do commit do diálogo de upload começa na pasta aberta e pode apontar para qualquer outra pasta, e um ZIP é mesclado nela
  • Árvore de arquivos de até 6 níveis de profundidade
  • Criar, editar, mover e excluir arquivos e pastas
  • Lista todas as pastas do projeto, incluindo pastas de dependências como node_modules; somente o endpoint da árvore de arquivos (GET /v1/apps/{id}/files/tree) pula as pastas de dependências e de build para ficar pequeno
  • vertracloud.config não existe no volume: ele é gerado a partir do banco no download e no snapshot (veja §Arquivo de configuração)
  • Armazenamento: 10 GB fixos por aplicação (veja §5 Armazenamento)

​
12. Deploy

​
Métodos

  1. Upload de ZIP pelo dashboard ou pela API
  2. Integração com GitHub — seleção do repositório (inclusive os privados)
  3. Webhooks do GitHub — deploy automático a cada push na branch escolhida, main ou master por padrão (planos Intermediary+)
  4. Extensão do VSCode — faça o deploy direto do editor

​
Processo

Upload do código → Instalação de dependências → Build (se houver build_command) → Inicialização do container → Atribuição de subdomínio → Provisionamento de SSL

​
Limites de upload

  • Tamanho máximo do ZIP: 100 MB
  • Tempo máximo de instalação de dependências: 15 minutos (INSTALL_TIMEOUT se exceder)
  • Tempo máximo do comando de build: 10 minutos (BUILD_TIMEOUT se exceder)
  • 1 porta exposta por aplicação

​
Rollback automático (Intermediary+)

Se a nova versão de uma aplicação parar em até 60 segundos após um deploy, a plataforma volta para a versão anterior uma vez e avisa o dono, com um link para o log da versão que falhou. Só os arquivos de código voltam, não as variáveis de ambiente. Se a versão anterior também parar, a aplicação fica parada e o dono é avisado. Durante esses 60 segundos, o reinício automático não reinicia a nova versão, para que os dois não disputem. Um crash depois do primeiro minuto é tratado como um crash normal. O recurso vem desligado por padrão, inclusive para aplicações criadas antes dele (deploy.auto_rollback, false por padrão); o dono o liga.

​
Deploys sem downtime (Enterprise)

No Enterprise, um deploy pode iniciar a nova versão ao lado da que está rodando, esperar que ela esteja saudável e só então trocar, de modo que uma aplicação que recebe tráfego web continue acessível durante o deploy. A configuração é deploy.zero_downtime, desligada por padrão:
  • off (padrão): para a versão em execução primeiro e depois inicia a nova.
  • auto: sem downtime apenas para aplicações que recebem tráfego web.
  • on: sempre, inclusive para aplicações sem tráfego web, como bots. Dois processos da aplicação rodam juntos por um tempo, então um bot pode responder o mesmo evento duas vezes.
Verificação de saúde: a plataforma chama a nova versão via HTTP em deploy.health_check_path (/ por padrão). Qualquer resposta HTTP conta como saudável, inclusive 404; uma conexão recusada, um timeout (5 segundos por tentativa) ou uma resposta 5xx reprovam a verificação. A versão precisa responder bem duas vezes seguidas e continuar rodando antes que o tráfego seja transferido. Uma aplicação que escuta apenas em 127.0.0.1 falha na verificação. Limites conhecidos:
  • As duas versões usam a mesma pasta, e os dois processos rodam juntos por até cerca de 2 minutos. Dados gravados pelos dois ao mesmo tempo, como um arquivo JSON, podem ser corrompidos; o SQLite normalmente lida bem. Uma migração de banco executada na inicialização roda enquanto a versão anterior ainda está atendendo.
  • Uma aplicação que lê arquivos a cada requisição (PHP, sites estáticos, uma aplicação Next.js ou Nuxt já buildada, imports tardios em Python) pode servir uma mistura de arquivos antigos e novos enquanto o deploy instala e faz o build. Para elas, use off.
  • Se a nova versão não ficar saudável em cerca de 2 minutos, ela é descartada e a versão anterior continua rodando. O dono recebe um aviso com o log da versão descartada.
  • Se a segunda cópia não puder ser iniciada naquele momento, o deploy volta a parar a versão em execução primeiro.
  • Enquanto a nova versão é preparada, o terminal ainda mostra a versão em execução, não o build. Uma requisição que a versão antiga já estava respondendo quando recebeu o pedido de parada pode falhar uma vez; tratar o SIGTERM de forma graciosa evita isso.

​
Limite de deploys por hora

Um teto por conta, renovado em uma janela de 3.600 segundos. Contam: criar uma aplicação, enviar um zip, fazer deploy via GitHub (manual ou por push), reinstalar dependências e alterar o comando de build. Não contam: reiniciar e parar. Se excedido → 429 DEPLOY_RATE_LIMITED com details.limit, details.window_seconds (3.600) e details.retry_after (segundos até liberar). Um push no GitHub que chegar além do limite é ignorado (não entra em fila) e aparece no histórico de atividades.

​
Arquivos excluídos do ZIP

Antes do upload, o dashboard remove automaticamente do zip: node_modules, .local, venv, .venv, __pycache__, .next, vendor, .bundle, target e .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/ e build/ (saída de build) não são removidos automaticamente — se o seu main/start aponta para dentro deles (comum em projetos que empacotam antes do deploy), a plataforma precisa desses arquivos. Exclua-os do zip apenas se o ponto de entrada real estiver fora deles.

​
13. Downgrade de plano

  • Disponível pelo dashboard ou pela API: POST /v1/users/me/downgrade
  • Fórmula: newDays = remainingDays × (currentPrice / targetPrice)
  • Restrições: o ECONOMY não pode fazer downgrade
  • Verificações: o uso de memória e as imagens Docker em uso (próprias e de templates de imagem) precisam caber no plano de destino (INSUFFICIENT_MEMORY_FOR_DOWNGRADE, INSUFFICIENT_IMAGE_SLOTS_FOR_DOWNGRADE); rate limit (1 vez a cada 3 horas)
  • Impacto: limite de memória reduzido, recursos de planos superiores desativados, workspaces perdidos ao sair do Enterprise. As configurações salvas de rollback automático e de deploy sem downtime permanecem na aplicação, mas só atuam em um plano que as inclua

​
14. Extensão do VSCode

  • Disponível no VS Code Marketplace (pesquise por “Vertra Cloud”)
  • Recursos: deploy rápido, gerenciamento de aplicações, gerenciamento de arquivos, monitoramento em tempo real
  • Requisitos: VS Code 1.80+, conta Vertra ativa, conexão com a internet
  • Deploy pela paleta de comandos: Ctrl+Shift+P → “Vertra: Deploy”

​
15. Métodos de autenticação

  • Discord OAuth — login e vínculo de conta
  • GitHub OAuth — login e vínculo de conta
  • Google OAuth — login e vínculo de conta
  • Magic Link — autenticação sem senha por e-mail
  • Chave de API — para acesso programático (gerenciada nas configurações do dashboard); até 10 chaves por conta, cada uma com um nome, escopos e IPs permitidos opcionais. Formato novo vc_live_ + 48 caracteres hexadecimais, exibido apenas uma vez; chaves antigas (64 hex) continuam válidas com todos os escopos. Detalhes completos em §16.

​
16. Referência da API

​
Autenticação

Envie uma chave de API no header Authorization como Bearer token:

​
Chaves de API

Uma nova chave tem o prefixo vc_live_ seguido de 48 caracteres hexadecimais e é exibida apenas uma vez, na criação ou na rotação. Chaves antigas, com 64 caracteres hexadecimais, continuam válidas. Uma conta pode ter até 10 chaves, cada uma com um nome, escopos de acesso e uma lista opcional de até 20 IPs ou CIDRs permitidos. Uma lista vazia permite chamadas de qualquer endereço IP. A chave precisa do escopo exigido pelo endpoint. As predefinições read, write e full selecionam conjuntos comuns; os escopos também podem ser escolhidos individualmente. As permissões do workspace também valem para chamadas autenticadas por chave. Gerenciamento de chaves, navegação na aba Data, downgrade, novos convites, decisões sobre solicitações de ação e consulta/exportação de atividades exigem uma sessão do dashboard. Uma chave sem o escopo exigido recebe 403 API_KEY_SCOPE_DENIED; um IP não permitido recebe 403 API_KEY_IP_DENIED. Uma chave inválida recebe 401 API_KEY_INVALID. O gerenciamento de chaves é feito pelo dashboard.

​
Rate limiting

A API aplica limites fixos por rota, além de limites por minuto e por dia por conta para chamadas com chave de API. A cota diária é renovada à meia-noite, no horário de Brasília. Respostas autenticadas por chave incluem x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, x-quota-limit, x-quota-remaining e x-quota-reset. Quando um limite é atingido, a resposta é 429 RATE_LIMIT_EXCEEDED ou 429 DAILY_QUOTA_EXCEEDED, com detalhes e o tempo para tentar de novo. Os limites fixos por rota cobrem operações de ciclo de vida, reset de banco, alterações de subdomínio, consultas de dados e exportação de atividades.

​
Formato da resposta

  • Sucesso: { "response": { ... } }
  • Erro: { "code": "ERROR_CODE", "message": "..." }

​
Códigos de erro comuns

​
Principais endpoints

A lista abaixo corresponde aos endpoints públicos da API. Os schemas de requisição e resposta estão na Referência da API. Os limites por rota estão detalhados em Limitações da API.

​
Aplicações

​
Bancos de dados

​
Usuários e conta

​
Workspaces

​
Faturamento

​
Resgate

​
Serviços

​
17. Variáveis de ambiente

  • Injetadas no container na inicialização
  • Gerenciadas pelo dashboard ou pela API
  • Limites: no máximo 256 variáveis, chave com até 255 caracteres, valor com até 3.072 caracteres
  • Criptografadas em repouso
  • Chaves proibidas: PORT, HOST, PATH, HOME, USER, SHELL
  • A plataforma define PORT=80 e HOST=0.0.0.0 no container

​
18. Limpeza automática (contas sem plano)

Em uma conta sem plano ativo, projetos que ficam offline por mais de 30 dias são excluídos automaticamente, com um snapshot feito antes:

​
19. Problemas comuns e soluções

​
Plataforma

  • Aplicação caindo / OOMKilled: memória insuficiente. Aumente a RAM alocada. Java/Puppeteer precisam de 512 MB+.
  • Crash loop (reinício automático desativado): 5 crashes em 10 min. Verifique os logs, corrija o erro raiz e faça um novo deploy.
  • Aplicação para imediatamente (código de saída 0): o processo não tem nada que o mantenha vivo. Confirme que o bot está logado ou que o servidor está escutando.
  • ZIP grande demais: exclua node_modules, venv, .git, vendor, target, __pycache__.
  • Instalação de dependências passa de 15 minutos (INSTALL_TIMEOUT): remova as dependências desnecessárias.
  • Comando de build passa de 10 minutos (BUILD_TIMEOUT): simplifique o build_command ou a etapa de build do framework.
  • Site com timeout: faça o bind em 0.0.0.0 (não em localhost). Use o valor de PORT.
  • Domínio personalizado não funciona: plano Intermediary+, CNAME correto, aguarde a propagação do DNS. Um domínio raiz precisa de um provedor de DNS com CNAME flattening. Um domínio sem DNS por 14 dias é removido; depois disso, apague os registros CNAME e TXT no seu provedor de DNS.
  • Conexão com o banco recusada: TLS é obrigatório. Baixe os certificados no dashboard.
  • PLAN_REQUIRED: a conta não tem plano ativo. Assine um plano (Economy ou superior) para criar aplicações e bancos ou publicar um site.
  • E-mail não recebido: verifique a caixa de spam. Tente outro método (Discord, GitHub, Google).

​
Node.js / JavaScript

  • Cannot find module 'xxx': o pacote não está em dependencies do package.json (pode estar em devDependencies, e a aplicação não tem comando de build, pois devDependencies só são instaladas quando há um).
  • missing script: start: adicione "start": "node index.js" em scripts no package.json.
  • Cannot use import statement outside a module: adicione "type": "module" ao package.json, ou use require().
  • ERR_REQUIRE_ESM: o pacote só suporta ESM. Use ESM ou uma versão mais antiga (ex.: node-fetch@2).
  • ERESOLVE dependency tree: crie um .npmrc com legacy-peer-deps=true.
  • EADDRINUSE: porta já em uso. Mantenha apenas um app.listen() no código.
  • Módulos nativos falham (better-sqlite3): não envie node_modules/. A plataforma compila para Linux.

​
TypeScript

  • tsx / ts-node: command not found: adicione tsx em dependencies.
  • TSError: Unable to compile: inclua o tsconfig.json. Corrija os erros de TS antes do deploy.

​
Python

  • ModuleNotFoundError: o módulo não está no requirements.txt. Gere-o com pip freeze > requirements.txt.
  • requirements.txt não encontrado: confira o nome exato e a extensão (cuidado com .txt.txt no Windows).
  • SyntaxError: invalid syntax: a versão de Python selecionada não suporta o recurso usado. Atualize a versão.
  • UnicodeDecodeError: salve os arquivos em UTF-8. Use encoding='utf-8' ao abrir arquivos.
  • Flask/Django não acessível: use o Gunicorn: gunicorn app:app --bind 0.0.0.0:80.

​
Go

  • go.mod not found: execute go mod init e go mod tidy. Inclua go.mod e go.sum.
  • Binário incompatível: compile para Linux: GOOS=linux GOARCH=amd64 go build.

​
Java

  • no main manifest attribute: configure a ferramenta de build para criar um fat JAR com Main-Class.
  • OutOfMemoryError: Java precisa de 512 MB+. Use as flags: -Xmx256m -Xms128m.

​
Bots do Discord

  • Invalid token / Improper token: gere um novo token no Developer Portal. Defina-o como variável de ambiente.
  • DisallowedIntents: ative os intents privilegiados no Developer Portal (Message Content, Server Members, Presence).
  • ClientMissingIntents: especifique os intents no código: new Client({ intents: [...] }).
  • Bot fica offline aleatoriamente: memória insuficiente ou discord.js/discord.py desatualizado.
  • on_message não dispara (discord.py): falta intents.message_content = True + ativá-lo no Developer Portal.

​
Variáveis de ambiente

  • Valores undefined/null: configure pelo dashboard; não dependa de um arquivo .env.
  • .env não funciona: a plataforma não lê .env. Use a interface de variáveis do dashboard.

​
20. Cupons de desconto

Um cupom pode ser percentual ou de valor fixo (aplicado uma vez sobre o total, nunca deixando o preço negativo), pode ter uma janela de validade, limite de resgates e restrições de plano ou de duração. Um pedido de R$ 0 (cupom de 100%) é entregue na hora, sem PIX. Um cupom recusado no checkout retorna um dos códigos COUPON_INVALID, COUPON_INACTIVE, COUPON_NOT_STARTED, COUPON_EXPIRED, COUPON_EXHAUSTED, COUPON_USER_LIMIT, COUPON_AUDIENCE, COUPON_PLAN, COUPON_DURATION. Um cupom que exclui a forma de pagamento escolhida retorna COUPON_PAYMENT_METHOD. Os descontos por período de cobrança (3 meses −5%, 12 meses −15%) são aplicados antes do cupom.

​
21. Retenção de dados

O que a Vertra Cloud guarda sobre a sua conta e os seus projetos, e por quanto tempo. O texto jurídico é a Política de Privacidade; esta tabela é o resumo prático. As requisições feitas com as suas chaves de API ficam visíveis para você no dashboard, e o histórico de atividades lista eventos de ciclo de vida, alterações no gerenciador de arquivos, snapshots restaurados, domínios, incidentes de proteção, compras, resgates de códigos e ações iniciadas por um agente conectado.

​
22. Blob Storage

O Blob Storage guarda arquivos (imagens, vídeos, backups e outros ativos) dos seus projetos. Arquivos públicos recebem uma URL pública, arquivos privados são lidos por meio de links temporários ou páginas de compartilhamento, e os mesmos arquivos podem ser acessados com um cliente compatível com S3. Está disponível a partir do Economy. O uso do Blob e a sua cota pertencem ao dono do workspace, então um workspace usa a cota do seu dono.

​
Cota e limites por plano

​
Recursos que dependem do plano

As transformações de imagem são aplicadas por parâmetros de URL (w, h, fit, format, q) em imagens públicas. Cada transformação distinta conta uma vez por mês. Acima do limite mensal, a imagem original é servida, sem erro.

​
Limites para todos os planos

  • Upload simples: uma requisição de até 100 MB por arquivo.
  • Upload direto: até 10 GB por objeto, enviado em partes diretamente ao storage, com retomada e cancelamento.
  • Caminho: de 1 a 1.024 caracteres, até 16 pastas, cada parte com até 255 caracteres de letras, dígitos, ., _, - e espaço. Todo arquivo precisa de uma extensão.
  • 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 e appimage. Executáveis também são detectados pelo conteúdo.
  • HTML, HTM, SVG, XML e XHTML são sempre baixados (attachment), nunca exibidos dentro da página.
  • Regras de pasta definem padrões para uma pasta: visibilidade, expiração, tamanho máximo, extensões, Cache-Control e exclusão após um número de dias (1 a 3.650).

​
Cota, downgrades e período de carência

  • Uma gravação que levaria a conta além da cota é bloqueada com STORAGE_QUOTA_EXCEEDED. Excluir objetos libera espaço.
  • Após um downgrade, os seus arquivos permanecem. Se eles usarem mais que a nova cota, novos uploads são bloqueados e o excedente é cobrado a R$ 0,20 por GB iniciado na próxima renovação.
  • Quando o plano expira, a conta entra em um período de carência de 72 horas: uploads e outras gravações são bloqueados (BLOB_NAMESPACE_SUSPENDED), enquanto arquivos públicos, links temporários e páginas de compartilhamento continuam funcionando. Renovar dentro dessas 72 horas reativa tudo. Uma suspensão por abuso é diferente: os arquivos saem do ar imediatamente.
  • Após o período de carência, os arquivos são excluídos. A exclusão é permanente e não há backup.
  • As páginas de compartilhamento abrem no site. Um compartilhamento pode ter expiração, limite de downloads e, a partir do Enterprise-12, senha. Um compartilhamento não protege um objeto público.

​
Acesso

  • Escopos da chave de API: blob:read e blob:write. Permissões de workspace: blob:read e blob:manage. Uma chave apenas com escopos blob:* pode ser restrita a uma pasta (blob_prefix, um caminho terminado em /): ela alcança somente objetos, uploads e compartilhamentos dentro dessa pasta, e as credenciais S3 derivadas dela herdam o limite. Todo o resto (regras, domínios, estatísticas) responde 403 BLOB_PREFIX_DENIED. Uma stack cria a sua própria chave restrita para a pasta de Blob dela.
  • Token de upload: um token vcup_ de vida curta para navegadores. Ele fixa o caminho ou a pasta, o tamanho, as extensões e a visibilidade, e é aceito somente nas rotas de upload.
  • Acesso compatível com S3: GET /v1/s3/credentials, limitado a 10 chamadas por hora. Revogar a chave de API que o criou corta o acesso S3 imediatamente. Requisições S3 a cada 10 segundos por conta: Economy/Pro 100, Scale/Intermediary 200, Enterprise-4 a 8: 400, Enterprise-12+: 600; CopyObject/UploadPartCopy 20. Acima disso: 503 SlowDown.
  • Cada rota está documentada na própria página, em Referência da API > Blob Storage.

​
Códigos de erro do Blob

​
23. Templates e stacks

Um template é uma receita que cria um software pronto (ou um projeto inicial) em uma única operação, depois de algumas perguntas. Uma stack é o grupo de aplicações, bancos e pastas de Blob que pertencem juntos; um template com mais de um serviço cria uma. Guias: Templates.

​
Origens

Os usuários não publicam no catálogo público pelo dashboard. Templates privados são criados em planos que podem criar imagens Docker, até 5 por conta; em um workspace, somente o dono cria e gerencia esses templates. Um membro de workspace não faz deploy de templates nele: só o dono faz (WORKSPACE_OWNER_ONLY).

​
Templates de código e de imagem

Nos dois casos, /app é o disco persistente e o restante do sistema de arquivos é somente leitura; o usuário é 1000:1000.

​
Plano necessário

O plano necessário é calculado a partir do template e das suas respostas, e pode ser elevado por um min_plan que o autor declara: RAM livre para a soma da memória mínima de cada serviço, publicação web quando um serviço precisa dela, um plano com imagens Docker e um slot livre para um template de imagem, um plano com Blob quando o template tem uma pasta de Blob, e os limites da conta de aplicações, bancos e deploys por hora. Quando não cabe, a API responde TEMPLATE_PLAN_REQUIRED, TEMPLATE_RAM_INSUFFICIENT ou TEMPLATE_IMAGE_SLOTS_EXHAUSTED, e o dashboard explica o motivo.

​
Usando um template

  • POST /v1/templates/{id}/deploy inicia um job (202) que valida o plano e a memória, cria os bancos e aguarda por eles, cria as aplicações, grava as variáveis, inicia tudo e aguarda o health check. Qualquer falha desfaz tudo o que o job criou (TEMPLATE_DEPLOY_FAILED, details.step); antes de excluir uma aplicação ou um banco, a reversão faz um snapshot de segurança. Um template de workspace só faz deploy dentro desse workspace, e somente pelo dono. Envie um Idempotency-Key para torná-lo seguro para repetir. Apenas um deploy do mesmo template roda por vez (TEMPLATE_DEPLOY_IN_PROGRESS).
  • As perguntas têm tipos (text, secret, select, boolean, number, url, email); segredos podem ser gerados para você. Saídas, como o endereço ou um token gerado, são mostradas no final; uma saída secreta é mostrada uma única vez.
  • As atualizações nunca são automáticas: uma nova versão mostra Nova versão disponível; a atualização faz um snapshot de segurança antes, atualiza os serviços um a um e, se algum falhar, restaura todos. As permissões nunca se tornam mais restritas em uma aplicação existente. Alguns templates bloqueiam o deploy blue-green (duas cópias rodando ao mesmo tempo quebrariam o funcionamento) e exigem que o rollback também restaure os dados (TEMPLATE_ROLLBACK_REQUIRES_DATA).
  • Alterar o código de uma aplicação a partir de um template aberto a desvincula do template; a API pede confirm_detach antes (TEMPLATE_DETACH_CONFIRMATION_REQUIRED).

​
Stacks

  • Aplicações em uma stack alcançam os bancos pelo endereço público, com certificados de cliente gerenciados pela plataforma e deixados de fora de downloads, snapshots e “salvar como template”. Um modo de rede diferente de public responde STACK_NETWORK_MODE_UNAVAILABLE.
  • Uma conexão liga uma aplicação a um banco, a uma pasta de Blob ou a outra aplicação. Suas variáveis são gerenciadas: atualizadas quando a senha, o certificado ou o host do banco mudam, e marcadas no dashboard. Editar uma delas à mão a transforma em uma variável normal. A API retorna restart_required e apps_to_restart quando aplicações precisam reiniciar.
  • Um recurso pertence a no máximo uma stack, na mesma conta ou workspace da stack. Uma stack pode ser criada a partir de um template, pelo fluxo /new, adicionando um banco a uma aplicação, ou transformando uma pasta que contém uma aplicação e um banco.
  • Saindo de uma stack: mantenha a conexão (as variáveis viram normais, com o endereço público) ou remova-as. Excluir uma stack pergunta se você quer apenas desfazê-la (os recursos permanecem) ou excluir tudo; para a pasta de Blob, a escolha é keep (padrão) ou delete.
  • Pastas organizam, stacks conectam: uma stack tem seu próprio card na lista e sua própria caixa com as conexões no Flow, e pode ficar dentro de uma pasta.
Revogar um link interrompe novos usos e não oferece mais atualizações; o que já foi criado continua rodando, e excluir a imagem original, o template ou a conta não afeta as cópias. A prévia mostra o autor, o que será criado e Não verificado pela Vertra. Os links podem ter max_uses e uma expiração (SHARE_LINK_REVOKED, SHARE_LINK_EXPIRED, SHARE_LINK_EXHAUSTED). Use Denunciar em uma prévia ou em uma aplicação criada; para casos graves, com evidências, escreva para [email protected]. Uma aplicação criada a partir de um link de uso não pode ser salva como template nem compartilhada (TEMPLATE_SAVE_NOT_ALLOWED).

​
Templates fechados

Um template privado pode ser fechado: quem o usa pode iniciar, parar, reiniciar, ler logs e métricas, criar snapshots e restaurá-los (somente em uma aplicação do mesmo template), fazer rollback, responder às perguntas, alterar a memória quando permitido e atualizar. Não podem usar o gerenciador de arquivos, baixar a aplicação ou os seus snapshots, criar variáveis livres, editar comandos, abrir um terminal, fazer deploy de código, salvá-la como template ou desvinculá-la. A API aplica isso em todas as rotas (TEMPLATE_CLOSED); um snapshot de uma aplicação fechada nunca pode ser baixado. Bancos nunca são fechados. Variáveis que o autor oculta (env_hidden, permitido somente em um template fechado) são injetadas e nunca retornadas (MANAGED_ENV_READONLY); desvincular a aplicação ou a stack do template exclui os valores ocultos.

​
Limites do manifesto

vertracloud.template.yaml: até 40 perguntas, 16 saídas, 8 serviços e 10 tags. Nome de até 50 caracteres, descrição de até 128. O JSON Schema público é /templates/schema/v1.json. Os placeholders são resolvidos no servidor; um placeholder ou serviço desconhecido torna o manifesto inválido (TEMPLATE_MANIFEST_INVALID).

​
Códigos de erro de template e stack

​
24. Glossário

Última modificação em 30 de outubro de 2026