Base de conhecimento
Todos os números da LumaHost Cloud numa página, gerados das mesmas regras que o painel e a cobrança usam. A mesma base existe em Markdown, para assistentes de IA, em lumahost.com/llms-full.txt.
O que é a LumaHost Cloud
Hospedagem de apps, bots, sites estáticos e bancos de dados para quem desenvolve sozinho ou com IA. Deploy por .zip, GitHub ou pelo MCP no Claude Code e no Cursor. Cada app ganha nome.lumahost.app com HTTPS. Empresa brasileira: painel, docs e suporte em português; pagamento por Pix ou cartão.
Planos e preços
| Plano | RAM | vCPU máx. | Disco | Mensal | Anual |
|---|---|---|---|---|---|
| Hobby | 1 GB | 1 | 10 GB | R$ 14,90 | R$ 149,00 |
| Dev | 2 GB | 2 | 20 GB | R$ 24,90 | R$ 249,00 |
| Pro | 4 GB | 3 | 40 GB | R$ 44,90 | R$ 449,00 |
| Studio | 8 GB | 4 | 80 GB | R$ 79,90 | R$ 799,00 |
- A RAM e o disco são uma cota da conta: você divide entre apps e bancos como quiser. Apps ilimitados dentro da cota.
- CPU compartilhada: 1 vCPU por GB de RAM alocado ao recurso, até o máximo do plano.
- No anual, dois meses saem de graça. Upgrade vale na hora; para reduzir, o que está alocado precisa caber no plano menor.
- Garantia de 30 dias: devolução via Pix do primeiro pagamento.
- Sem plano grátis.
- Incluso: Apps ilimitados dentro da cota de RAM
- Incluso: Deploy por .zip, GitHub ou MCP (Claude Code, Cursor)
- Incluso: Postgres, MySQL, Redis e MongoDB gerenciados
- Incluso: Templates de 1 clique: Activepieces, Evolution API, Uptime Kuma, Open WebUI, agentes de IA e bots
- Incluso: Pasta persistente por app (sessão de bot, SQLite, uploads)
- Incluso: Snapshot antes de excluir e na hora, guardado por 7 dias
- Incluso: Backup diário de Postgres, MySQL e MongoDB, 7 dias de retenção
- Incluso: Endereço meuapp.lumahost.app com HTTPS
- Incluso: Domínio próprio com certificado automático
- Incluso: Logs, variáveis de ambiente e métricas de CPU e RAM
Limites
| Item | Valor |
|---|---|
| RAM mínima por app | 256 MB |
| RAM mínima por banco | 512 MB |
| Disco padrão de app novo | 2 GB |
| Disco padrão de banco novo | 5 GB |
| Upload de .zip | até 100 MB |
| Tempo máximo de build | 15 min, um build por vez |
| Executar uma vez | até 10 min; 20 por hora na conta |
| antesDeIniciar (migrations) | até 5 min por deploy |
| Deploys | 30 por hora na conta, somando API, MCP, painel e push do GitHub (os que falharam também contam) |
| Requisições à API | 60 por minuto por token; 120 por minuto na conta somando tudo |
| Loop de reinício | 5 reinícios em 10 min param o app (status PARADO, com a linha do log no ultimoErro); a plataforma tenta de novo sozinha em 1 h, 6 h e 24 h. Novo deploy ou a ação iniciar retomam na hora |
| Conta nova | nos primeiros 7 dias, até 3 apps (ou 1 por GB de RAM nos planos maiores), contando os apagados; o suporte libera antes se precisar. Estourou: LIMITE_TAXA (429) com Retry-After |
| Saída de internet dos apps | sem cota de volume (uso justo, medido por conta); velocidade com teto de 50 Mbit/s por GB de RAM do plano. Visitas aos sites não passam pelo teto. Tráfego com padrão de ataque (mais de 20000 pacotes/s ou 30000 conexões novas/min por 2 min) corta a saída da conta automaticamente; os sites seguem no ar e o suporte libera |
| Consulta pelo painel (aba Dados) | 20 s e 500 linhas por consulta |
| Arquivo pelo painel (aba Arquivos) | até 10 MB por envio ou download |
| Snapshots manuais | 10 por dia na conta |
- Sem Docker Compose, sem modo privilegiado e sem montar pastas do servidor: um Dockerfile por app.
- SMTP bloqueado (25, 465 e 587, exceto 587 para o e-mail da LumaHost): use uma API de e-mail por HTTPS.
- Sem terminal no container; para comandos avulsos, "Executar uma vez".
- Limite estourado: HTTP 429, código LIMITE_TAXA e header Retry-After em segundos. Agente que bate no limite de deploys quase sempre está repetindo um build que falha: pare, leia os logs do build e corrija antes de tentar de novo.
Apps
- Tipos: web (endereço público, escuta na PORT), worker (bot, fila, agente; sem porta) e static (arquivos prontos).
- Build automático por Nixpacks (Node, Python, PHP, Go, Ruby, Java, .NET e outros) ou o Dockerfile do projeto.
- A variável PORT é reservada: o app web deve escutar em 0.0.0.0 na porta dela.
- Origem: .zip (painel, API ou MCP) ou repositório do GitHub (cada push implanta).
- Rollback para qualquer deploy anterior pela aba Deploys.
- lumahost.json opcional na raiz: tipo, porta, build, start, antesDeIniciar, ramMb, buildPack, publicar, volume, deployComPausa.
- Pasta persistente opcional (ex.: /data): sobrevive a deploy e reinício, do tamanho do disco do app, sem backup automático.
- Com pasta persistente, deploy e reinício são com pausa: a versão antiga desliga antes de a nova ligar (alguns segundos fora do ar), para as duas nunca gravarem juntas na pasta. Muda em Configurações › No deploy ou com deployComPausa no lumahost.json.
- Aba Arquivos: ver e editar o código (salvar e implantar) e a pasta persistente pelo painel.
- Para quem usa o ChatGPT: o painel (Novo app e aba Deploys) copia um pedido pronto que faz o ChatGPT preparar o projeto para a Cloud, e o botão "Copiar erro para o ChatGPT" leva o deploy que falhou ou o app em ciclo de reinício, sem valores de variáveis nem senhas. Ver /docs/cloud/chatgpt.
Bancos de dados
- PostgreSQL, MySQL, MongoDB e Redis, na rede privada da conta (URL interna, sem TLS; acesso externo desligado).
- Backup diário de Postgres, MySQL e MongoDB, guardado 7 dias fora do servidor, com download e restauração pelo painel. Redis não tem backup.
- Aba Dados: tabelas e coleções, primeiras linhas e console de consulta (SQL só leitura por padrão).
Templates de 1 clique
| Template | Versão | RAM da cota | Banco | Pasta persistente |
|---|---|---|---|---|
| Activepieces | 0.92.3-hotfix.2 | 2 GB | PostgreSQL | — |
| Evolution API | v2.3.7 | 1 GB | PostgreSQL | /evolution/instances |
| Uptime Kuma | 2.5.9-slim | 0,375 GB | — | /app/data |
| Open WebUI | v0.13.0-slim | 0,75 GB | — | /app/backend/data |
| OpenClaw | 2026.11.1 | 2 GB | — | /home/node/.openclaw |
| Hermes Agent | v0.23.0 | 1 GB | — | /opt/data |
| Bot de Discord | discord.js 14.28.1 | 0,25 GB | — | — (worker, sem endereço) |
| Bot de Telegram | python-telegram-bot 22.8 | 0,25 GB | — | — (worker, sem endereço) |
Nos de IA (Open WebUI, OpenClaw, Hermes Agent) o cliente usa a própria chave: Anthropic, OpenAI ou OpenRouter. No Open WebUI, a chave só vira conexão no primeiro início; depois, troca-se em Painel de administração › Configurações › Conexões. A versão é a slim: sem conversa com documentos (RAG).
Os bots de Discord (Node.js, discord.js, comando /ping) e de Telegram (Python, python-telegram-bot, /start e eco) são código inicial que sobe como worker pelo Nixpacks; o token é obrigatório ao criar (DISCORD_TOKEN, TELEGRAM_BOT_TOKEN). Token errado: o log mostra a recusa e o processo sai.
Evolution API: painel em /manager, chave na variável AUTHENTICATION_API_KEY (cabeçalho apikey), Postgres gerenciado e cache local, sem Redis. Uptime Kuma: alerta por e-mail (SMTP) não funciona na Cloud; use Telegram, Discord ou webhook.
Snapshots e exclusão
- Antes de excluir um app ou banco sai um snapshot (código, pasta, configuração e variáveis; ou o dump), guardado 7 dias. Se falhar, nada é excluído.
- App excluído pode ser recriado igual a partir do snapshot, em Excluídos recentemente.
- Pagamento atrasado: suspensão em D+15; nada é apagado.
- Cancelamento: apps, bancos e dados ficam 30 dias com o backup para baixar e dois avisos por e-mail; depois são excluídos.
API
Base: https://lumahost.com/api/cloud/v1. Autenticação: Authorization: Bearer lh_... (token criado em lumahost.com/tokens). Respostas em JSON; erro como { erro, codigo }.
| Endpoint | O que faz |
|---|---|
GET /conta | Plano, cota (RAM, disco, vCPU) e status. |
GET, POST /apps | Listar e criar apps (web, worker, static; origem zip ou GitHub; volume opcional). |
GET, PATCH, DELETE /apps/:id | Detalhe, mudar recursos e configuração, excluir (com snapshot antes). |
POST /apps/:id/acoes | Iniciar, parar ou reiniciar. |
GET, POST /apps/:id/deploys | Listar deploys; enviar .zip (multipart) ou pedir redeploy/rollback. |
GET /apps/:id/deploys/:deployId/logs | Log de build de um deploy. |
GET /apps/:id/logs | Log de execução do app. |
GET /apps/:id/metricas | CPU e RAM (janelas 15m, 1h, 6h, 24h). |
GET /apps/:id/analytics | Acessos do app (Web Analytics): requisições, visitantes, erros 5xx, tempo de resposta p50/p95, páginas mais acessadas e mais lentas, origens, países e dispositivos. Períodos 24h, 7d, 30d. Sem instalar nada. |
GET, PUT /apps/:id/variaveis | Ler e substituir as variáveis de ambiente. |
GET, POST /apps/:id/dominios | Domínios próprios do app. |
DELETE /apps/:id/dominios/:dominioId | Remover domínio próprio. |
POST /apps/:id/dominios/:dominioId/verificar | Conferir o DNS e emitir o HTTPS. |
GET, POST /apps/:id/execucoes | "Executar uma vez": listar e iniciar. |
GET /apps/:id/execucoes/:execucaoId | Estado, código de saída e saída de uma execução. |
GET /apps/:id/codigo | Árvore do código do app. |
GET, PUT, DELETE /apps/:id/codigo/arquivo | Ler, gravar (e implantar) ou apagar um arquivo do código. |
GET, POST /apps/:id/pasta | Listar a pasta persistente; criar subpasta. |
GET, PUT, DELETE /apps/:id/pasta/arquivo | Ler, gravar ou apagar um arquivo da pasta persistente. |
POST /apps/:id/snapshots | Snapshot do app agora. |
POST /apps/:id/acesso | Link de uso único para o painel do template (OpenClaw). |
GET, POST /bancos | Listar e criar bancos (POSTGRES, MYSQL, REDIS, MONGO). |
GET, PATCH, DELETE /bancos/:id | Detalhe com credenciais, mudar recursos, excluir (com snapshot antes). |
POST /bancos/:id/acoes | Iniciar, parar ou reiniciar o banco. |
GET, POST /bancos/:id/backups | Backups diários; backup agora. |
GET /bancos/:id/backups/:backupId/download | URL temporária do arquivo de backup. |
POST /bancos/:id/backups/:backupId/restaurar | Restaurar um backup diário. |
GET, POST /bancos/:id/dados | Estrutura e primeiras linhas; rodar consulta (só leitura por padrão nos SQL). |
POST /bancos/:id/snapshots | Snapshot (dump) do banco agora. |
GET /snapshots | Snapshots da conta, inclusive de recursos excluídos. |
GET /snapshots/:id/download | URL temporária de uma parte (codigo, pasta, config, dump). |
POST /snapshots/:id/restaurar | Restaurar pasta, código ou banco; recriar app excluído. |
GET /templates | Catálogo de templates (público). |
GET, POST /templates/:id | Detalhe (público); criar a partir do template. |
GET /github/instalado, /github/repositorios, /github/branches | Repositórios liberados para o app da LumaHost no GitHub. |
GET, POST /tokens | Tokens de API (só pelo painel, com sessão). |
DELETE /tokens/:id | Revogar token. |
GET /email | Planos e domínios de e-mail da conta. |
GET, POST /email/caixas | Caixas de e-mail. |
POST /email/caixas/:id/senha | Trocar a senha de uma caixa. |
GET, POST /email/caixas/:id/aliases | Aliases de uma caixa. |
DELETE /email/aliases/:id | Remover alias. |
POST /email/dominios/:dominio/verificar | Conferir os 6 registros DNS do e-mail. |
GET /email/migracoes | Migrações IMAP em andamento. |
Códigos de erro da API
| Código | HTTP | Significado |
|---|---|---|
NAO_AUTENTICADO | 401 | Token ausente, inválido ou revogado. Crie outro em lumahost.com/tokens. |
SEM_CLOUD | 403 | A conta não tem plano Cloud ativo. |
SEM_EMAIL | 403 | A conta não tem plano de e-mail. |
SUSPENSO | 403 | Serviço suspenso por pagamento atrasado: leitura funciona, escrita não. |
NAO_ENCONTRADO | 404 | O app, banco ou recurso não existe nesta conta. |
VALIDACAO | 422 | Pedido inválido; a mensagem diz o campo. |
COTA_RAM | 409 | Falta RAM na cota do plano: reduza outro recurso ou faça upgrade. |
COTA_DISCO | 409 | Falta disco na cota do plano. |
COTA_CPU | 409 | CPU acima do teto do plano. |
SLUG_EM_USO | 409 | O endereço (slug) já é de outro app. |
ZIP_INVALIDO | 422 | O .zip tem caminho absoluto, .., link simbólico ou lumahost.json inválido. |
ZIP_GRANDE | 413 | O .zip passou de 100 MB. |
GITHUB_SEM_ACESSO | 403 | O app da LumaHost no GitHub não tem acesso a esse repositório. |
MOTOR_INDISPONIVEL | 503 | A infraestrutura não respondeu: tente de novo em instantes. |
LIMITE_TAXA | 429 | Limite de uso atingido: 60 requisições por minuto por token, 30 deploys por hora na conta, execuções ou snapshots. O header Retry-After diz em quantos segundos tentar de novo; não repita em loop. |
EXECUCAO_EM_ANDAMENTO | 409 | Já há um "Executar uma vez" aberto neste app. |
SNAPSHOT_FALHOU | 409 | A exclusão parou porque o snapshot de segurança falhou. Repita, ou exclua com ?semSnapshot=1. |
INTERNO | 500 | Erro nosso: o suporte é avisado. |
MCP (@lumahost/mcp)
Instalação no Claude Code: claude mcp add lumahost -e LUMAHOST_TOKEN=lh_... -- npx -y @lumahost/mcp. No Cursor, Windsurf e VS Code: o mesmo comando npx com a variável LUMAHOST_TOKEN.
| Ferramenta | Para quê |
|---|---|
quem_sou | Plano, cota e produtos da conta. |
listar_apps, listar_bancos, listar_repositorios | Ver o que existe. |
criar_app | Criar app (web, worker, static), com pasta persistente opcional. |
deploy_pasta | Compactar uma pasta local e implantar, respeitando o .gitignore. |
status_deploy, logs_deploy, logs | Build e execução. |
analytics | Acessos do app: visitas, erros 5xx, tempo de resposta, páginas mais lentas, origens e países. |
ver_variaveis, definir_variaveis | Variáveis de ambiente. |
adicionar_dominio, verificar_dominio | Domínio próprio. |
criar_banco, credenciais_banco, consultar_banco | Bancos: criar, conectar e consultar. |
pasta_persistente | Listar ou ler a pasta persistente de um app. |
listar_templates, criar_de_template, link_acesso_painel | Templates de 1 clique. |
fazer_snapshot, listar_snapshots | Snapshots antes de mudança arriscada. |
acao_app, rollback, executar_uma_vez, ver_execucao | Operar o app. |
listar_dominios_email, status_dns_email, listar_caixas, criar_caixa, trocar_senha_caixa, criar_alias, remover_alias, status_migracao | E-mail profissional. |
Suporte
Suporte por e-mail e WhatsApp em horário comercial, cobrindo a plataforma (não o código do app). Abuso: abuse@lumahost.com. Documentação: https://lumahost.com/docs/cloud.