# Nebular

> Plataforma de hospedagem. Documentação para pessoas e agents: API pública /v1 (Bearer nbk_) para projetos, serviços, deploys, variáveis com referência, rede privada, volumes, bancos (Postgres, MariaDB, SQLite), domínios, templates (WordPress), galerias e mídia. Páginas marcadas “em construção” ainda não têm API: não invente rotas. Erros: https://docs.nebularws.com/erros/tabela.md

## Início

- [Nebular Docs](https://docs.nebularws.com/index.md): Documentação da plataforma Nebular para pessoas e agents de IA — token, galerias e CDN, erros e referência da API /v1.

## Começar

- [Token de API](https://docs.nebularws.com/comecar/token.md): Crie um token nbk_, escolha os escopos e use somente no cabeçalho Authorization.
- [Conceitos](https://docs.nebularws.com/comecar/conceitos.md): Time, token, projeto (grupo), serviço, fonte, variável, referência, volume, banco, domínio e deploy — o modelo da Nebular.
- [Primeiro deploy](https://docs.nebularws.com/comecar/primeiro-deploy.md): Fluxo canônico ponta a ponta: projeto, serviço, deploy (imagem ou upload), polling com backoff e URL pública.
- [Como um agent usa isto](https://docs.nebularws.com/comecar/como-um-agent-usa-isto.md): Receita de loop para agents — autenticar, agir, esperar, ler o erro e decidir entre repetir, corrigir ou parar; inclui deploy.
- [Convenções da API](https://docs.nebularws.com/comecar/convencoes-da-api.md): Base URL, autenticação, erros JSON, paginação por cursor, idempotência, ids, datas, anti-IDOR e estados de deploy.

## Guias por stack

- [Node.js e Next.js](https://docs.nebularws.com/guia/nodejs-next.md): Deploy de apps Node e Next.js: detecção, PORT, health check, variáveis NEXT_PUBLIC, logs e rollback, com curl exato.
- [Go](https://docs.nebularws.com/guia/go.md): Deploy de serviços Go: detecção, porta, health check, variáveis, logs e rollback, com curl exato.
- [Rust](https://docs.nebularws.com/guia/rust.md): Deploy de serviços Rust: detecção do Cargo.toml, porta, health check, variáveis, logs e rollback, com curl exato.
- [Python (FastAPI)](https://docs.nebularws.com/guia/python.md): Deploy de serviços Python/FastAPI: detecção, uvicorn, porta, variáveis, logs e rollback, com curl exato.
- [Site estático](https://docs.nebularws.com/guia/site-estatico.md): Deploy de sites estáticos: detecção do index.html e da pasta de saída, build opcional, variáveis, logs e rollback.
- [Dockerfile](https://docs.nebularws.com/guia/dockerfile.md): Deploy com Dockerfile próprio: dockerfile_path, multi-stage, usuário não-root, porta e limites do build.
- [Imagem pública](https://docs.nebularws.com/guia/imagem-publica.md): Rode uma imagem de registry público (Docker Hub, GHCR, Quay) sem build: digest, porta e usuário não-root.
- [WordPress](https://docs.nebularws.com/guia/wordpress.md): WordPress por template: um POST cria o MariaDB e o app com volume, segredos gerados e cron; polling dos deploys e atualização por troca de imagem.
- [Monorepo](https://docs.nebularws.com/guia/monorepo.md): Vários serviços a partir de um repositório: root_dir, watch_paths, auto-deploy por git e deploy de grupo na ordem das referências.

## Bancos

- [PostgreSQL](https://docs.nebularws.com/bancos/postgres.md): Criar e operar um banco PostgreSQL gerenciado — criação, variáveis entregues, cota, conexão, rotação e exclusão.
- [MariaDB](https://docs.nebularws.com/bancos/mariadb.md): Criar e operar um banco MariaDB gerenciado — criação, variáveis entregues, cota, conexão, rotação e exclusão.
- [SQLite (libSQL)](https://docs.nebularws.com/bancos/sqlite.md): Criar e operar um banco SQLite (libSQL) gerenciado — criação, variáveis entregues, cota, conexão, rotação e exclusão.
- [Conexão e referências](https://docs.nebularws.com/bancos/conexao-e-referencias.md): Como um serviço app recebe as credenciais do banco por referência ${{db.VAR}}, por que o banco não está na rede privada e como conectar com TLS.
- [Backup e restore](https://docs.nebularws.com/bancos/backup-restore.md): Backups diários e sob demanda, retenção, restore para banco novo ou no mesmo, polling do job e o que muda em cada motor.
- [Migrações](https://docs.nebularws.com/bancos/migracoes.md): Como aplicar migrations do app no banco gerenciado de forma reversível e segura.

## Serviços conectados

- [Front, back e banco](https://docs.nebularws.com/conectados/front-back-db.md): Receita ponta a ponta: front Next.js público, back Go privado e Postgres, ligados por referências e deploy de grupo.
- [Variáveis e referências](https://docs.nebularws.com/conectados/variaveis-e-referencias.md): Variáveis por serviço e compartilhadas no projeto, referências ${{svc.VAR}} e ${{shared.VAR}}, variáveis automáticas e erros de resolução.
- [Rede privada](https://docs.nebularws.com/conectados/rede-privada.md): Como serviços do mesmo projeto se falam por nome, sem rota pública, e o que nunca é alcançável.
- [Volumes](https://docs.nebularws.com/conectados/volumes.md): Volume persistente de um serviço: criar, montar, tamanho, sobrevivência a redeploy e remoção.
- [Sugestões de persistência](https://docs.nebularws.com/conectados/sugestoes-de-persistencia.md): Como a plataforma detecta que um app precisa de disco persistente (volume) ou banco gerenciado, sugere criar o recurso e espera sua autorização — nunca cria sozinha. Inclui como um agent lê e descarta sugestões pela API.

## Domínios

- [Domínio próprio](https://docs.nebularws.com/dominios/dominio-proprio.md): Adicionar um domínio ao serviço, criar os registros DNS e o TXT de posse, acompanhar os estados e resolver conflitos.
- [Subdomínio gerado](https://docs.nebularws.com/dominios/subdominio-gerado.md): Todo serviço público recebe <slug>.<domínio de apps>; serviços privados não. Como escolher o slug e o que fazer se estiver em uso.
- [TLS](https://docs.nebularws.com/dominios/tls.md): Como o HTTPS dos domínios é emitido e o que o agent precisa (e não precisa) fazer.
- [Redirecionamentos](https://docs.nebularws.com/dominios/redirecionamentos.md): Redirecionar um domínio para outro domínio do mesmo projeto (por exemplo, www para o apex).
- [Problemas comuns](https://docs.nebularws.com/dominios/problemas-comuns.md): Diagnóstico do domínio parado em pending_dns, verifying ou error, pelo motivo devolvido pela verificação de DNS.

## CDN e imagens

- [CDN e galerias: visão geral](https://docs.nebularws.com/cdn/visao-geral.md): O que é uma galeria, URL imutável e URL alias, e como tudo é varrido antes de publicar.
- [Galerias e arquivos](https://docs.nebularws.com/cdn/galerias.md): Crie galerias, envie e versione arquivos, espere uploads pending e use receitas prontas. Exemplos executados como teste.
- [Transformar imagens](https://docs.nebularws.com/cdn/transformar-imagens.md): Parâmetros w e q, larguras permitidas e negociação de formato AVIF/WebP.
- [Classes de arquivo e varredura](https://docs.nebularws.com/cdn/classes-de-arquivo-e-varredura.md): Como cada classe de arquivo é servida, como funciona a varredura e quarentena, e como reexportar um SVG recusado.
- [Cache e purge](https://docs.nebularws.com/cdn/cache-e-purge.md): URL imutável (1 ano) e URL alias (60 s): quando usar cada uma e como o cache é invalidado.

## Operação

- [Rollback](https://docs.nebularws.com/operacao/rollback.md): Voltar um serviço para um deploy anterior, com as variáveis daquela versão.
- [Logs](https://docs.nebularws.com/operacao/logs.md): Logs de build (por deploy) e de execução (por serviço), com cursor e since.
- [Deploys e status](https://docs.nebularws.com/operacao/deploys-e-status.md): Estados de um deploy, polling com backoff, deploy de grupo, estado blocked e auto-deploy por git.
- [Limites e cotas](https://docs.nebularws.com/operacao/limites-e-cotas.md): Limites de arquivo, cota por time, regras de nome e rate limit.
- [Escala e recursos](https://docs.nebularws.com/operacao/escala-e-recursos.md): Memória e CPU por serviço via PATCH, valores padrão e máximos por plano.
- [App pronto para a Nebular e para escalar](https://docs.nebularws.com/operacao/app-pronto-para-escalar.md): Como escrever um app que roda bem na Nebular hoje (container efêmero, disco somente leitura, blue/green) e já nasce pronto para réplicas, que ainda não existem na plataforma.

## Segurança

- [Isolamento](https://docs.nebularws.com/seguranca/isolamento.md): Como a plataforma isola serviços, redes, volumes, bancos e times, e o que isso muda para quem escreve o app ou o agent.
- [O que não é permitido](https://docs.nebularws.com/seguranca/o-que-nao-e-permitido.md): Usos proibidos na plataforma, o que ela bloqueia por construção e o que acontece se você violar.
- [Tokens e escopos](https://docs.nebularws.com/seguranca/tokens-e-escopos.md): Escopos de token, validade, restrição por projeto e galeria, env:reveal e boas práticas de guarda.
- [Reportar abuso](https://docs.nebularws.com/seguranca/reportar-abuso.md): Denuncie conteúdo malicioso na CDN: rota pública, sem token.

## Erros

- [Tabela de erros](https://docs.nebularws.com/erros/tabela.md): Cada código de erro da API, o HTTP, a causa e a ação esperada do agent: repetir, corrigir ou parar e pedir uma pessoa.
- [Rate limit e retry](https://docs.nebularws.com/erros/rate-limit-e-retry.md): Quando repetir uma requisição, quanto esperar, polling de deploy com backoff e como usar Idempotency-Key para repetir com segurança.
- [Fluxo de diagnóstico](https://docs.nebularws.com/erros/fluxo-de-diagnostico.md): Árvore de decisão para o agent: dado um erro, repetir, corrigir ou parar e pedir uma pessoa.

## Receitas

- [Do zero ao ar com um agent](https://docs.nebularws.com/receitas/do-zero-ao-ar-com-um-agent.md): Prompt pronto para colar e a sequência token, projeto, serviço, deploy, verificação e domínio, com links para cada guia.
- [Agente sobe imagens na galeria](https://docs.nebularws.com/receitas/agente-sobe-imagens.md): Receita ponta a ponta para um agent criar uma galeria, enviar imagens, esperar a varredura e usar a URL devolvida em um serviço.
- [CI com GitHub Actions](https://docs.nebularws.com/receitas/ci-github-actions.md): Workflow que dispara o deploy de um serviço pela API e espera o resultado, com o token em secret do GitHub.
- [Migrar de outro host](https://docs.nebularws.com/receitas/migrar-de-outro-host.md): Checklist para trazer um app de outro provedor: variáveis, banco, domínio e virada, usando só as rotas documentadas.

## Referência da API

- [Autenticação e visão geral (referência)](https://docs.nebularws.com/referencia/autenticacao.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Conta (referência)](https://docs.nebularws.com/referencia/conta.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Projetos (referência)](https://docs.nebularws.com/referencia/projetos.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Serviços (referência)](https://docs.nebularws.com/referencia/servicos.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Deploys (referência)](https://docs.nebularws.com/referencia/deploys.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Logs (referência)](https://docs.nebularws.com/referencia/logs.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Variáveis (referência)](https://docs.nebularws.com/referencia/variaveis.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Volumes (referência)](https://docs.nebularws.com/referencia/volumes.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Bancos (referência)](https://docs.nebularws.com/referencia/bancos.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Domínios (referência)](https://docs.nebularws.com/referencia/dominios.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Templates (referência)](https://docs.nebularws.com/referencia/templates.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Galerias e arquivos (referência)](https://docs.nebularws.com/referencia/arquivos.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Abuso (referência)](https://docs.nebularws.com/referencia/abuso.md): Referência gerada da OpenAPI /v1 (13.0.0). Não edite à mão.
- [Changelog da API](https://docs.nebularws.com/referencia/changelog.md): Mudanças na API pública /v1 por versão.

## Para agents

- [Para agents](https://docs.nebularws.com/agents/index.md): Como consumir esta documentação como agent de IA — llms.txt, llms-full.txt, Markdown cru e regras de faça e não faça.
- [Contrato de App Nebular (para agents)](https://docs.nebularws.com/agents/contrato-app.md): Documento único e normativo para adequar um app à Nebular: porta, disco somente leitura, config por ambiente, banco por referência, variáveis automáticas e a tabela de erros de deploy com culpa e correção.
- [Deploy de aplicações com vários serviços (guia para agentes)](https://docs.nebularws.com/agents/deploy-multi-servico.md): Passo a passo por curl para subir um app com front, API, worker e bancos no mesmo projeto: referências, deploy em grupo, domínios, rollback, erros reais e o que ainda não existe (manifesto, réplicas).
- [Como corrigir cada erro de deploy (cookbook)](https://docs.nebularws.com/agents/corrigir-deploy.md): Um remédio por código de erro de deploy da Nebular: o que significa, como corrigir em passos concretos e de quem é a culpa (código do app ou configuração da plataforma). O link fix_url de cada erro aponta para a âncora #<error_code> desta página.

## Optional

- [Documentação completa em texto puro](https://docs.nebularws.com/llms-full.txt): todas as páginas concatenadas, na ordem de tutorial, sem navegação nem HTML.