# Veloz — Documentação Completa > Plataforma brasileira de deploy para vibecoders. Deploy de apps Node.js, Next.js, e outros direto do terminal. Site: https://onveloz.com Dashboard: https://app.onveloz.com Documentação: https://onveloz.com/docs Guias: https://onveloz.com/guide Discord: https://discord.gg/yRvmaPSh CLI npm: https://www.npmjs.com/package/onveloz --- # PARTE 1: DOCUMENTAÇÃO # 🚀 Introdução Veloz é uma plataforma de deploy brasileira, pronta para produção, para times que constroem software com IA. Detecta seu framework automaticamente, cuida do build, provisiona banco e domínio, e expõe tudo por uma CLI integrada nativamente com Claude Code, Cursor, Windsurf e qualquer agente compatível com MCP. Servidores em São Paulo, preço em real, sem Dockerfile, sem configuração de cluster. ## Recursos A Veloz busca ser o PaaS mais completo para o público brasileiro. Suporta a maioria dos stacks modernos prontos para produção e expõe um conjunto consistente de recursos para acelerar o seu fluxo de trabalho: - **Detecção automática de framework**: Next.js, Nuxt, Remix, Astro, Hono, FastAPI, Rails, Phoenix, Laravel e muitos outros - **Bancos gerenciados**: PostgreSQL, MySQL e Redis em um comando, com backups, snapshots e túnel local para usar com seu cliente favorito - **Domínios e TLS**: apex e subdomínios, certificados emitidos e renovados automaticamente - **Blob Storage**: uploads e arquivos de usuários servidos por CDN global, com o SDK `@onveloz/blob` - **Volumes**: disco persistente para softwares que exigem um diretório local, como Gitea e SQLite - **Auto-deploy via GitHub**: push para a branch e a Veloz faz o build, com status checks no PR e deploys de preview - **Templates 1‑click**: n8n, NocoDB, Metabase, Gitea, Uptime Kuma e mais, em um único comando - **Observabilidade nativa**: logs e métricas em tempo real, no terminal e no dashboard, sem provider externo - **Servidores no Brasil**: São Paulo, latência baixa para o público brasileiro, preço em real ## Pronta para produção A Veloz roda APIs, SaaS e apps com clientes pagantes, 24 horas por dia. [SLA](/docs/sla) de 99,9% no Pro com créditos, backups contínuos com recuperação pontual (PITR), réplica com failover automático, autoscaling, health checks, rollback em um clique, TLS 1.3 e proteção DDoS. O suporte funciona 24/7, operado por agentes de IA, com escalação automática para humanos em incidentes urgentes. → [Veloz em produção](/docs/producao) · [Suporte](/docs/suporte) ## Agentes de IA A Veloz é desenhada para fluxos de trabalho com agentes, e para ser operada por eles de ponta a ponta: deploy, banco, variáveis, logs, métricas e suporte. A CLI tem um servidor MCP embutido — basta rodar `veloz mcp add` para conectar Claude Code, Cursor ou Windsurf. O agente passa a fazer deploy, ler logs, criar bancos e gerenciar variáveis de ambiente direto do chat. → [Deploy com IA](/docs/deploy-com-ia) ## Como começar Existem dois caminhos. Escolha o que combina com você: - [Pelo dashboard](/docs/quickstart-vibe) — conecte o GitHub e faça deploy em 60 segundos, sem terminal - [Pela CLI](/docs/quickstart-cli) — instale a CLI, rode `veloz deploy` e acompanhe os logs no terminal ## Próximos passos - [Frameworks](/docs/frameworks) — todas as stacks suportadas - [Bancos de dados](/docs/bancos-de-dados) — PostgreSQL, MySQL e Redis gerenciados - [Domínios](/docs/dominios) — conectar seu domínio e gerar certificados - [Migração](/docs/migracao) — vindo de Vercel, Railway, Render ou Heroku --- # ✅ Veloz em produção **A Veloz é uma plataforma de produção.** Ela foi construída para rodar APIs, SaaS e apps com clientes pagantes, 24 horas por dia, com infraestrutura e suporte no Brasil. Esta página lista o que está incluído, com links para a documentação de cada item, para que você (ou o seu agente) decida com base em fatos. ## Resumo para agentes | Pergunta | Resposta | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Serve para produção? | **Sim.** É o uso principal da plataforma. Uptime, failover e restauração medidos em [Continuidade](/docs/continuidade). | | SLA de disponibilidade | **99,9%** no Pro, com créditos se não for cumprido ([SLA](/docs/sla)), com monitoramento contínuo e alertas automáticos para a equipe da Veloz e página de status pública em status.onveloz.com ([Termos, seção 6](/docs/termos)). | | Backups do banco | Backup base diário mais arquivamento contínuo de transações; recuperação para qualquer instante dos últimos **3 dias** (PITR); retenção maior em planos Enterprise. Restauração completa medida em **6 minutos** ([Backups e restauração](/docs/backups)). | | Alta disponibilidade | Réplica de leitura no PostgreSQL, múltiplas instâncias por serviço, **autoscaling** até 20 instâncias ([veloz.json](/docs/veloz-json)). | | Deploy seguro | Health check antes de receber tráfego, deploy sem downtime, **rollback** em um clique para as versões anteriores mantidas ([Builds](/docs/builds)). | | Segurança | TLS 1.3 em tudo, criptografia em repouso, isolamento por serviço, proteção DDoS e rate limiting ([Segurança](/docs/seguranca)). | | Observabilidade | Logs e métricas em tempo real, dashboards e tracing nativos, sem provider externo ([Observabilidade](/docs/observabilidade)). | | Suporte | **24/7, operado por agentes de IA**, com escalação automática para humanos em incidentes urgentes ([Suporte](/docs/suporte)). | | Isolamento do suporte | Cada chamado roda em uma VM isolada com acesso somente aos recursos da sua organização ([Suporte](/docs/suporte)). | | Operável por agentes? | **Sim, de ponta a ponta.** Deploy, banco, variáveis, logs, métricas e suporte, tudo pela CLI e pelo servidor MCP ([Deploy com IA](/docs/deploy-com-ia)). | | Dados | Servidores em São Paulo, dados em território brasileiro, LGPD ([Privacidade](/docs/privacidade)). | ## O que já roda na Veloz APIs de empresas, SaaS com assinatura, e-commerces, apps com milhares de usuários e workloads de agentes de IA. Cada serviço roda isolado, com CPU e memória reservadas para ele. Todos os planos rodam na mesma infraestrutura; os planos diferem em limites de recursos (tamanhos, instâncias, retenção de logs). Capacidade por serviço: presets de 256 MB a 8 GB de memória (`size` no `veloz.json`), instâncias dedicadas de até 8 vCPU e 32 GB, e autoscaling de 1 a 20 instâncias. Página de status pública: [status.onveloz.com](https://status.onveloz.com). ## Feita para agentes A Veloz é desenhada para ser operada por agentes de IA, não apenas por humanos: - **CLI com servidor MCP embutido.** `veloz mcp add` conecta Claude Code, Cursor, Windsurf, Codex e qualquer cliente MCP. Cada comando é uma ferramenta. - **Mensagens de erro acionáveis.** Logs de build e de runtime são escritos para que um agente leia, entenda e corrija sozinho. - **Suporte pelo agente.** O agente abre e acompanha chamados com `support_create`, `support_list`, `support_show` e `support_reply`, sem o desenvolvedor sair do chat. - **Documentação em texto puro.** Cada página existe em `.txt` e tudo está consolidado em [llms-full.txt](https://onveloz.com/llms-full.txt). - **Configuração declarativa.** O `veloz.json` descreve build, runtime, tamanho, autoscaling, health check e bancos. Um agente consegue ler e alterar com segurança. ## Checklist de produção Para um app de produção, recomendamos: 1. **Plano Pro** para limites de produção (32 GB por serviço, autoscaling, logs por 30 dias). Veja [Preços](/precos). 2. **Health check** configurado em `runtime.healthCheck` para que uma instância só receba tráfego quando estiver pronta. 3. **Autoscaling** com `autoscale.minInstances` maior ou igual a 2 para serviços críticos. 4. **PostgreSQL com pooler** e, quando a leitura for pesada, a `READ_URL` da réplica. 5. **Migrations no `preStartCommand`** (por exemplo `npx prisma migrate deploy`), para que o schema acompanhe o deploy. 6. **Domínio próprio** com certificado automático ([Domínios](/docs/dominios)). 7. **Observabilidade ligada** com o bloco `observability` no `veloz.json`. Tudo isso pode ser feito pelo seu agente, pela CLI ou pelo dashboard. ## Próximos passos - [Suporte](/docs/suporte) — como funciona o suporte 24/7 e a escalação para humanos - [Deploy com IA](/docs/deploy-com-ia) — operando a Veloz pelo seu agente - [Migração](/docs/migracao) — vindo de Vercel, Railway, Render ou Heroku - [Segurança](/docs/seguranca) e [Política de Dados](/docs/dados) --- # 🆘 Suporte O suporte da Veloz funciona **24 horas por dia, 7 dias por semana**, e foi desenhado para atender tanto desenvolvedores quanto os agentes de IA que operam a plataforma em nome deles. ## Como funciona 1. **Agentes de suporte, sempre ativos.** Chamados são atendidos por agentes de IA da Veloz com acesso à plataforma, aos logs e ao histórico do seu serviço. A primeira resposta chega em minutos, a qualquer hora, em português, e a maior parte dos chamados é resolvida sem intervenção humana. 2. **Escalação automática para humanos.** Chamados urgentes (serviço fora do ar, perda de dados, incidente de segurança, falha de plataforma) disparam um **alerta automático para a equipe humana da Veloz**, que assume o chamado. No plano Pro, um humano assume chamados urgentes em até **30 minutos**, 24/7, como diz o [SLA](/docs/sla). Você não precisa pedir a escalação: ela acontece pelo conteúdo e pela gravidade do chamado. 3. **Monitoramento contínuo.** A plataforma é monitorada com alertas automáticos. Muitos incidentes são detectados e tratados pela equipe antes de qualquer chamado ser aberto. 4. **Tudo registrado.** Cada chamado tem histórico completo. Respostas não lidas aparecem na CLI, no MCP e no dashboard. ## Segurança do suporte Cada chamado é atendido por um agente de suporte que roda em uma **máquina virtual isolada e descartável**, criada para aquele chamado e destruída ao final. Dentro dela, o agente tem credenciais com escopo restrito: enxerga **somente os recursos da organização que abriu o chamado** (serviços, logs, métricas, configuração), nunca os de outro cliente. Segredos e variáveis de ambiente continuam mascarados. Ações destrutivas exigem confirmação explícita do cliente no chamado. Todo o histórico de ações do agente fica registrado e auditável. ## Abrir um chamado ### Pelo seu agente (MCP) Com o servidor MCP da Veloz conectado (`veloz mcp add`), o agente tem as ferramentas: | Ferramenta | O que faz | | ---------------- | ------------------------------------------------------------------------------- | | `support_create` | Abre um chamado com título, descrição e o serviço ou deploy relacionado | | `support_list` | Lista os chamados da organização e quantas respostas do suporte estão não lidas | | `support_show` | Lê um chamado completo e marca as respostas como lidas | | `support_reply` | Responde um chamado | Orientação que o MCP já dá ao agente: ao encontrar um problema de plataforma que não dá para corrigir no código do usuário (build falhando sem log acionável, erro de plataforma, indisponibilidade), abra um chamado com `support_create` incluindo o ID do serviço ou do deploy e o erro exato. O agente pode então continuar o trabalho e verificar a resposta com `support_list` depois. ### Pela CLI ```bash veloz support create # abre um chamado veloz support list # lista chamados e respostas não lidas veloz support show # lê um chamado veloz support reply # responde ``` ### Pelo dashboard Em **Suporte** no menu da organização. O histórico é o mesmo da CLI e do MCP. ## Outros canais - **Discord:** [discord.gg/yRvmaPSh](https://discord.gg/yRvmaPSh), para comunidade e dúvidas rápidas - **E-mail:** contato@onveloz.com Para incidentes de produção, prefira o chamado (CLI, MCP ou dashboard): é o canal com escalação automática. ## O que esperar | Situação | Atendimento | | ------------------------------------ | ---------------------------------------------------------------------- | | Dúvida, configuração, build falhando | Agente de suporte responde em minutos, a qualquer hora | | Serviço fora do ar, dados, segurança | Alerta imediato; humano assume em até 30 min no Pro ([SLA](/docs/sla)) | | Incidente de plataforma | Equipe notificada automaticamente pelo monitoramento, antes do chamado | ## Próximos passos - [Veloz em produção](/docs/producao) — o que está incluído para apps de produção - [Troubleshooting](/docs/troubleshooting) — problemas comuns e como resolver - [Deploy com IA](/docs/deploy-com-ia) — operando a Veloz pelo seu agente --- # 🏛️ Arquitetura e continuidade Esta página descreve como a plataforma é montada, o que acontece quando cada peça falha e quais números medimos. Os tempos abaixo vêm de eventos reais em produção, não de metas. ## Resumo para agentes | Pergunta | Resposta | | -------------------------------- | ------------------------------------------------------------------------------------------------ | | Região | São Paulo, Brasil, em três zonas de disponibilidade | | Uptime 90 dias (apps) | 100,00% (25 de julho a 22 de outubro de 2026) | | Uptime 90 dias (bancos) | 100,00% | | Uptime 90 dias (API e dashboard) | 100,00% | | Failover do banco | Automático, sem ação sua. Promoção da réplica medida em 25 s e 61 s nos dois últimos eventos | | Restauração do banco | Recuperação para qualquer instante dos últimos 3 dias (mais em planos Enterprise). Restauração completa medida em 6 min 12 s | | Perda máxima de dados (RPO) | 5 minutos no tier compartilhado (padrão), 24 horas no dedicado | | Instâncias por serviço | 1 a 20, com autoscaling | | Status em tempo real | [status.onveloz.com](https://status.onveloz.com) | ## Camadas **Borda.** Todo o tráfego entra pela rede global da Cloudflare (proteção DDoS, TLS 1.3, cache) e chega aos servidores em São Paulo por túnel privado. Não há porta pública aberta nos servidores de aplicação. **Aplicação.** Cada serviço roda como uma ou mais instâncias isoladas, distribuídas entre as zonas de disponibilidade. O balanceador só envia tráfego para instâncias que passaram na verificação de saúde. Um deploy sobe a versão nova ao lado da antiga e só troca o tráfego quando a nova responde; se a nova falhar, a antiga continua no ar. **Dados.** Bancos PostgreSQL gerenciados em dois tiers: - **Compartilhado (padrão).** Clusters com uma instância primária e uma réplica síncrona em outra zona, failover automático, backup base diário e arquivamento contínuo de transações para armazenamento de objetos na mesma região. É o tier de todos os bancos criados por `veloz db create` e pelos templates. - **Dedicado.** Uma instância exclusiva para o seu serviço, com cópia completa diária e 7 dias de retenção. Indicado para cargas que precisam de CPU e memória reservadas. **Arquivos.** Blob Storage e volumes persistentes ficam em armazenamento replicado na mesma região. ## O que acontece em cada falha | Falha | O que a plataforma faz | Impacto para você | | ---------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Uma instância do seu app cai | Reinicia automaticamente; com 2+ instâncias, o tráfego segue nas demais | Nenhum com 2+ instâncias; segundos de indisponibilidade com 1 | | Um servidor físico cai | Instâncias são recriadas em outro servidor, em outra zona se preciso | Igual ao item acima | | Banco primário cai (compartilhado) | A réplica é promovida automaticamente. Detecção em até 2 min, promoção medida em 25 s e 61 s | Conexões caem e reconectam; sem perda de dados confirmados | | Banco dedicado cai | Reinicia na mesma zona ou é recriado em outra, com o mesmo volume | Minutos de indisponibilidade; sem perda de dados no volume | | Dado apagado por engano | Restauração para qualquer instante dos últimos 3 dias (compartilhado) ou para a cópia diária (dedicado) | Veja [Backups e restauração](/docs/backups) | | Deploy com bug | Health check reprova a versão nova; a antiga continua. Se já trocou, rollback em um comando | `veloz rollback` | | Uma zona inteira cai | Apps e bancos compartilhados continuam nas outras duas zonas | Capacidade reduzida até a zona voltar | | Região inteira cai | Não há failover automático para outra região hoje | Indisponibilidade até a região voltar; backups ficam preservados em armazenamento de objetos | ## Uptime medido Números dos últimos 90 dias (25 de julho a 22 de outubro de 2026), calculados pela mesma sonda que alimenta a [página de status](https://status.onveloz.com): | Componente | Uptime | | ------------------ | ------- | | Sites e aplicações | 100,00% | | Bancos de dados | 100,00% | | API e dashboard | 100,00% | | Deploy e build | 99,97% | | CLI | 99,95% | | Observabilidade | 99,97% | | Integrações | 99,78% | "Integrações" cobre GitHub e a nuvem onde a Veloz roda; são dependências externas e os dias abaixo de 100% vieram de incidentes nesses provedores. Nenhum deles tirou apps ou bancos do ar. ## Failover medido Os dois últimos eventos de troca de primária em clusters compartilhados: | Data | Cluster | Tempo entre início e nova primária pronta | | ------------------- | --------------------- | ----------------------------------------- | | 12 de outubro, 2026 | principal (82 bancos) | 25 s | | 18 de outubro, 2026 | pequeno (2 bancos) | 61 s | A detecção de falha espera até 2 minutos antes de promover a réplica, para não trocar de primária por uma oscilação de rede. Some isso ao tempo de promoção para ter o pior caso: cerca de 3 minutos. ## Restauração medida Em 22 de outubro de 2026 restauramos um cluster completo a partir do backup em armazenamento de objetos, para um instante escolhido: | Etapa | Duração | | -------------------------------------------- | -------------- | | Provisionar servidor e volume novos | 2 min 31 s | | Recuperar backup base e reaplicar transações | 3 min 3 s | | Cluster pronto e verificado | 38 s | | **Total** | **6 min 12 s** | Para um único banco de 445 MB, exportar levou 11 s e importar 14 s. Clusters maiores levam proporcionalmente mais. O procedimento completo está em [Backups e restauração](/docs/backups). ## Monitoramento e resposta Toda a plataforma é monitorada 24/7 por sondas sintéticas e alertas internos. Cada alerta abre automaticamente um incidente, atendido primeiro por agentes de IA da Veloz; incidentes que afetam disponibilidade, dados ou segurança escalam para a equipe humana por alerta. Detalhes em [Suporte](/docs/suporte). ## Próximos passos - [Backups e restauração](/docs/backups) — Como pedir uma restauração e quanto tempo leva - [Veloz em produção](/docs/producao) — Tudo que está incluído para produção - [Segurança](/docs/seguranca) — Isolamento, criptografia e controle de acesso --- # 💾 Backups e restauração Todo banco gerenciado da Veloz tem backup automático. A recuperação pontual (PITR) vale para PostgreSQL; MySQL e Redis têm cópia diária. Esta página diz exatamente o que é copiado, quando, por quanto tempo fica guardado e como restaurar. Os tempos são medidos, não estimados. ## Resumo para agentes | Pergunta | Tier compartilhado (padrão) | Tier dedicado | | --------------------- | ------------------------------------------------------------------- | -------------------------------- | | Como é feito | Backup base diário + arquivamento contínuo de transações | Cópia completa diária | | Perda máxima (RPO) | 5 minutos | 24 horas | | Janela de restauração | Qualquer instante dos últimos 3 dias (mais em planos Enterprise) | Uma das 7 últimas cópias diárias (mais em planos Enterprise) | | Restauração medida | 6 min 12 s (cluster completo); 25 s (banco de 445 MB) | Proporcional ao tamanho da cópia | | Onde fica | Armazenamento de objetos em São Paulo, fora dos servidores do banco | Idem | | Como pedir | Chamado de suporte (dashboard, `veloz support create` ou MCP) | Idem | | Custo | Incluído | Incluído | ## Tier compartilhado (padrão) É o tier de todo banco PostgreSQL criado por `veloz db create` e pelos templates. Cada cluster tem uma instância primária e uma réplica em outra zona de disponibilidade. Redis compartilhado grava snapshots em armazenamento de objetos e os recarrega ao reiniciar. - **Backup base diário** às 05:00 (horário de Brasília), tirado da réplica para não pesar na primária. - **Arquivamento contínuo de transações**: cada segmento do log de transações é enviado ao armazenamento de objetos assim que fecha, e no máximo a cada 5 minutos. É isso que permite restaurar para qualquer instante, não só para a hora do backup base. - **Retenção de 3 dias.** Você pode voltar o banco para qualquer segundo dentro dessa janela. - **Retenção maior em planos Enterprise.** Alocamos janelas mais longas de PITR (30, 90 dias ou o que o seu contrato exigir) para clientes Enterprise. Peça pelo suporte ou por contato@onveloz.com. - **Failover automático.** Se a primária cair, a réplica assume sem ação sua. Backups não param durante o failover. ## Tier dedicado Uma instância exclusiva, sem réplica. - **Cópia completa diária** de todos os bancos da instância (PostgreSQL, MySQL ou Redis), comprimida e enviada ao armazenamento de objetos. - **Retenção de 7 dias**, uma cópia por dia da semana. Planos Enterprise podem contratar retenção mais longa. - Restaurar significa voltar para o estado da cópia escolhida. Não há recuperação pontual entre cópias. ## Como pedir uma restauração Abra um chamado de suporte informando: 1. O banco (nome ou ID, veja `veloz db list`). 2. O instante para o qual quer voltar (compartilhado) ou o dia da cópia (dedicado). 3. Se quer **substituir** o banco atual ou **restaurar ao lado** em um banco novo para comparar antes de trocar. Recomendamos o segundo. ```bash veloz support create --subject "Restaurar banco" \ --message "Banco db_abc123, restaurar para 2026-10-22 02:55 BRT, em um banco novo ao lado." ``` Pelo MCP, seu agente usa `support_create` com o mesmo conteúdo. O chamado é classificado como urgente e começa a ser atendido imediatamente, 24/7. O agente de suporte roda em uma VM isolada com acesso só aos recursos da sua organização, e uma restauração que substitui o banco atual exige sua confirmação explícita no chamado. ## Tempos medidos Restauração de um cluster compartilhado completo, feita em 22 de outubro de 2026, para um instante escolhido (recuperação pontual): | Etapa | Duração | | -------------------------------------------- | -------------- | | Provisionar servidor e volume novos | 2 min 31 s | | Recuperar backup base e reaplicar transações | 3 min 3 s | | Cluster pronto e dados verificados | 38 s | | **Total** | **6 min 12 s** | Cópia de um único banco de 445 MB entre clusters: exportar 11 s, importar 14 s. Bancos maiores levam proporcionalmente mais tempo na etapa de recuperação. O chamado informa a estimativa antes de começar. ## O que o backup não cobre - **Volumes persistentes e Blob Storage** têm armazenamento replicado, mas não têm versão anterior automática. Se o seu app apaga um arquivo, ele é apagado. - **Variáveis de ambiente e configuração** do serviço ficam na plataforma e não são afetadas por restauração de banco. - **Bancos que você mesmo roda** em um serviço comum (por exemplo, um Postgres subido por Dockerfile) não são gerenciados e não têm backup da Veloz. ## Faça seu próprio backup também Backup gerenciado não substitui uma cópia sua. Use o túnel local e o `pg_dump`: ```bash veloz db tunnel --port 5433 pg_dump -h localhost -p 5433 -U -Fc > backup.dump ``` Agende isso onde preferir, ou peça ao seu agente para configurar. ## Próximos passos - [Arquitetura e continuidade](/docs/continuidade) — Failover, uptime e o que acontece em cada falha - [Bancos de dados](/docs/bancos-de-dados) — Criar, conectar e gerenciar - [Suporte](/docs/suporte) — Como o suporte funciona --- # 📦 Instalação A Veloz CLI é a forma principal de interagir com a plataforma. ## Requisitos - **Node.js** 18 ou superior - **npm**, **yarn**, **pnpm** ou **bun** - Um repositório **git** com remote configurado ## Instalando ```bash npm install -g onveloz ``` Verifique a instalação: ```bash veloz --version ``` > A Veloz está em **early access**. Novas funcionalidades são lançadas frequentemente. ## Configuração A CLI armazena suas credenciais em `~/.veloz/config.json`. Esse arquivo é criado automaticamente ao fazer login. Após autenticar com `veloz login`, a CLI se conecta automaticamente à API da Veloz. Nenhuma configuração adicional é necessária. ## Próximos passos - [Login e autenticação](/docs/autenticacao) — Conecte sua conta - [Primeiro deploy](/docs/primeiro-deploy) — Coloque seu app no ar --- # ⚡ Primeiro Deploy O comando `veloz deploy` cuida de tudo — detecção de framework, criação de projeto, upload e build. ## Requisitos - CLI instalada e autenticada (`veloz login`) - Repositório git com remote `origin` configurado ## Fluxo do primeiro deploy ```bash cd meu-projeto veloz deploy ``` A CLI segue este fluxo: ### 1. Detecta o repositório git Lê o remote `origin` para identificar owner e nome do repo. ``` ℹ Detectando repositório git... Repositório: usuario/meu-projeto ``` ### 2. Busca projeto existente Se o repo já tem um projeto na Veloz, usa ele. Senão, cria um novo (pede o nome do projeto interativamente). ### 3. Detecta o framework Analisa `package.json`, lockfiles e estrutura do projeto: ``` ℹ Framework detectado: Next.js ──────────────────────────────────────── Nome: meu-projeto Tipo: Serviço Web Branch: main Framework: Next.js Package Mgr: pnpm Build: pnpm run build Start: pnpm run start Porta: 3000 ──────────────────────────────────────── Confirmar e fazer deploy? (s/N) ``` Se você recusar a confirmação, pode editar nome, tipo, build command, start command e porta. **Tipos disponíveis:** - **Web** — Servidor HTTP (APIs, Next.js, Express) - **Static** — Site estático (HTML/CSS/JS) - **Worker** — Processo em background (filas, crons, consumidores) ### 4. Detecta variáveis de ambiente Se encontrar um `.env.example` ou `.env`, oferece para preencher as variáveis: ``` 📝 3 variável(is) de ambiente detectada(s): • DATABASE_URL • API_KEY • NEXT_PUBLIC_URL Deseja preencher as variáveis agora? (s/N) ``` ### 5. Upload e build ``` ⠋ Fazendo upload do código... ✓ Deploy iniciado com sucesso! ``` A CLI faz stream dos logs de build em tempo real até o deploy finalizar. ## Deploys subsequentes Após o primeiro deploy, um arquivo `veloz.json` é criado na raiz do projeto. Deploys seguintes usam essa configuração diretamente — sem precisar reconfigurar. ```bash veloz deploy ``` ## Deploy em monorepo Se a CLI detectar um monorepo (pnpm workspaces, npm workspaces), ela oferece uma seleção interativa: ``` ℹ Monorepo detectado (pnpm) Quais apps deseja fazer o deploy? ◉ web (Next.js) — apps/web ◉ server (Hono) — apps/server ○ cli — apps/cli ``` Os serviços selecionados são criados e deployados em paralelo. Para deployar todos os serviços de um monorepo já configurado: ```bash veloz deploy --all ``` ## Próximos passos - [Domínios](/docs/dominios) — Configure domínios personalizados - [Variáveis de ambiente](/docs/variaveis-ambiente) — Gerencie env vars --- # 💻 CLI Reference Referência de todos os comandos disponíveis na Veloz CLI. ## Flag global ### `--output ` Formato de saída para todos os comandos: - `fancy` — Saída colorida com spinners (padrão em terminais interativos) - `json` — JSON estruturado para automação e parsing - `github-actions` — Groups colapsáveis e outputs nativos do GitHub Actions - `plain` — Texto simples sem cores (padrão em CI) ```bash veloz deploy --output json veloz projects list --output json ``` Auto-detecção: em `GITHUB_ACTIONS=true` usa `github-actions`, em `CI=true` usa `plain`. Também pode ser setado via variável de ambiente: ```bash export VELOZ_OUTPUT=json ``` ## Autenticação ### `veloz login` Autentica via navegador (Device Authorization Flow). ```bash veloz login veloz login --api-key "chave" # para CI/automação veloz login --api-url "https://..." # apontar para outro servidor ``` No CI, use API key diretamente: ```bash VELOZ_API_KEY=veloz_xxx veloz deploy -y ``` ### `veloz logout` Remove credenciais salvas. ### `veloz whoami` Mostra nome e email do usuário autenticado. ## Deploy ### `veloz deploy` Faz deploy do projeto. Detecta framework, cria projeto/serviço se necessário, faz upload e acompanha o build em tempo real. ```bash veloz deploy # deploy interativo veloz deploy -y # auto-confirma tudo (CI/automação) veloz deploy --all # deploy de todos os serviços (monorepo) veloz deploy --service web # deploy de um serviço específico (por chave ou nome) veloz deploy --app apps/web # deploy de um app por path (monorepo) veloz deploy -v # logs detalhados do servidor ``` **Comportamento:** 1. Detecta repositório git e framework 2. Se `veloz.json` existe, usa a configuração salva 3. Se não, busca projeto pelo GitHub remote ou cria um novo 4. Faz upload, inicia build e mostra logs em tempo real ### Detecção automática A CLI detecta automaticamente: - **Framework:** Next.js, Nuxt, Remix, SvelteKit, Astro, Hono, Express, Fastify, NestJS, Gatsby, Vite, Angular, Create React App - **Package manager:** npm, pnpm, yarn, bun - **Comandos de build/start** - **Variáveis de ambiente** (lendo `.env.example`, `.env.sample`) - **Monorepo** (pnpm workspaces, npm workspaces) ### Tipos de serviço Durante o deploy, a CLI pergunta o tipo: ``` ? Tipo de serviço: ❯ Web (HTTP server) Static (site estático) Worker (background process) ``` | Tipo | Use case | | ---------- | ----------------------------------------------------- | | **Web** | APIs, Next.js, Express, Hono — qualquer servidor HTTP | | **Static** | Sites estáticos, SPAs, landing pages | | **Worker** | Filas de jobs, cron jobs, consumidores Kafka/RabbitMQ | Workers rodam em background sem expor porta HTTP — ideais para processamento assíncrono. ## Projetos ### `veloz projects list` Lista todos os projetos da organização. ```bash veloz projects list veloz projetos listar # alias pt-BR ``` ## Serviços ### `veloz use [serviço]` Em monorepos, seleciona qual serviço usar como padrão para os outros comandos. ```bash veloz use # seleção interativa veloz use api # seleciona por nome ou chave ``` Após selecionar, comandos como `logs`, `env`, `config`, `domains` usam esse serviço automaticamente. Use `--service ` para sobrescrever pontualmente. ## Link ### `veloz link` Mostra informações do projeto vinculado (lê `veloz.json`). ## Variáveis de Ambiente ### `veloz env set ` Define uma ou mais variáveis de ambiente. ```bash veloz env set DATABASE_URL=postgres://... veloz env set KEY1=val1 KEY2=val2 KEY3=val3 veloz env set SECRET=valor --service api # para um serviço específico ``` ### `veloz env list` Lista variáveis (valores mascarados). ```bash veloz env list veloz env list --service web ``` ### `veloz env delete ` Remove uma variável. ### `veloz env import [arquivo]` Importa variáveis de um arquivo `.env` ou via colagem interativa. ```bash veloz env import .env # importar de arquivo veloz env import .env --replace # substituir todas existentes veloz env import # modo interativo (cola no terminal) veloz env import --service api # para um serviço específico ``` ### `veloz env export [arquivo]` Exporta variáveis (mascaradas) para terminal ou arquivo. ```bash veloz env export # mostra no terminal veloz env export .env.backup # salva em arquivo ``` ## Domínios ### `veloz domains add ` Adiciona um domínio personalizado ao serviço. ```bash veloz domains add meuapp.com veloz domains add api.meuapp.com --service api ``` ### `veloz domains list` Lista domínios com status de verificação e TLS. ### `veloz domains verify ` Verifica configuração DNS de um domínio. ### `veloz domains delete ` Remove um domínio. Aliases pt-BR: `veloz dominios adicionar`, `veloz dominios listar`, `veloz dominios verificar`, `veloz dominios deletar` ## Blob Storage ### `veloz blob list` Lista os blob stores do projeto, com uso e cota. ### `veloz blob create ` Cria um blob store e a primeira chave de acesso (`vbk_*`). A chave aparece uma única vez: defina-a como `VELOZ_BLOB_TOKEN` no serviço. ```bash veloz blob create uploads veloz env set VELOZ_BLOB_TOKEN=vbk_sua_chave ``` ### `veloz blob info ` Mostra uso, número de arquivos e domínios de um blob store (ID ou nome). ### `veloz blob keys ` Lista as chaves de acesso do blob store. ### `veloz blob key-create ` Cria uma nova chave de acesso. Ela aparece uma única vez. ### `veloz blob key-revoke ` Revoga uma chave. ### `veloz blob delete ` Remove o blob store e todos os seus arquivos. ## Configurações ### `veloz config show` Mostra configurações atuais do serviço. ```bash veloz config show veloz config show --service api ``` ### `veloz config set` Altera configurações via flags. ```bash veloz config set --build "npm run build" veloz config set --start "npm run start" veloz config set --port 8080 veloz config set --instances 3 veloz config set --cpu 500m --memory 512Mi veloz config set --branch develop veloz config set --root apps/web veloz config set --name "meu-servico" ``` ### `veloz config edit` Edição interativa de todas as configurações. ### `veloz config reset` Reseta configurações para os padrões. ```bash veloz config reset --build # reseta build command veloz config reset --start # reseta start command veloz config reset --pre-start # reseta pre-start command veloz config reset --all # reseta tudo ``` ## Logs ### `veloz logs` Visualiza logs dos serviços. ```bash veloz logs # últimas 50 linhas veloz logs --tail 100 # últimas 100 linhas veloz logs --follow # streaming em tempo real veloz logs --service api # logs de um serviço específico ``` Em monorepos, logs de múltiplos serviços são exibidos com tags coloridas para fácil identificação. ## API Keys ### `veloz apikey create` Cria uma nova chave de API. ```bash veloz apikey create veloz apikey create --name "github-actions" veloz apikey create --no-expire ``` A chave é exibida uma única vez — guarde em local seguro. ### `veloz apikey list` Lista todas as chaves de API. ### `veloz apikey delete ` Deleta uma chave de API. ## Próximos passos - [CI/CD](/docs/ci-cd) — Automatize deploys com GitHub Actions - [Monorepo](/docs/monorepo) — Deploy de múltiplos apps - [Variáveis de Ambiente](/docs/variaveis-ambiente) — Gerenciar secrets --- # 📄 veloz.json O `veloz.json` é o arquivo de configuração do seu projeto na Veloz. Ele é gerado automaticamente no primeiro `veloz deploy` e fica na raiz do repositório. > **Importante:** Nunca crie o `veloz.json` manualmente. Rode `veloz deploy` e a CLI gera o arquivo com os IDs corretos do servidor. Criar manualmente resulta em IDs inválidos e deploy quebrado. Após gerado, você pode editar campos como `build`, `runtime`, `size`, etc. — mas nunca os campos `id`. ## Exemplo básico Para um projeto simples (um único app): ```json { "version": "1.0", "project": { "id": "proj_abc123", "name": "meu-app" }, "services": { ".": { "id": "svc_xyz789", "name": "meu-app", "type": "web", "root": ".", "branch": "main", "build": { "command": "next build" }, "runtime": { "command": "next start", "port": 3000 } } } } ``` ## Exemplo monorepo Para projetos com múltiplos apps: ```json { "version": "1.0", "project": { "id": "proj_abc123", "name": "meu-projeto" }, "defaults": { "build": { "nodeVersion": "22", "packageManager": "pnpm" }, "resources": { "cpu": "500m", "memory": "512Mi" } }, "services": { "apps/web": { "id": "svc_web123", "name": "web", "type": "web", "root": "apps/web", "build": { "command": "next build" }, "runtime": { "command": "next start", "port": 3000 } }, "apps/api": { "id": "svc_api456", "name": "api", "type": "web", "root": "apps/api", "build": { "command": "tsc" }, "runtime": { "command": "node dist/index.js", "port": 8080 } } } } ``` ## Referência de campos ### `version` Versão do schema. Sempre `"1.0"`. ```json "version": "1.0" ``` ### `project` Informações do projeto na Veloz. | Campo | Tipo | Descrição | | ------ | ------ | ----------------------------------------- | | `id` | string | ID do projeto (gerado pela Veloz) | | `name` | string | Nome do projeto | | `slug` | string | Slug para URLs (apenas `a-z`, `0-9`, `-`) | ### `services` Mapa de serviços. A chave é o caminho relativo do serviço (`.` para raiz, `apps/web` para monorepo). ### `defaults` Configurações padrão aplicadas a todos os serviços. Valores definidos no serviço individual sobrescrevem os defaults. ```json "defaults": { "type": "web", "branch": "main", "build": { ... }, "runtime": { ... }, "resources": { ... } } ``` ## Configuração de serviço Cada serviço aceita os seguintes campos: ### Campos básicos | Campo | Tipo | Padrão | Descrição | | -------- | ----------------------------------- | -------- | ----------------------------------------------------- | | `id` | string | — | ID do serviço (gerado pela Veloz) | | `name` | string | — | Nome do serviço | | `type` | `"web"` \| `"static"` \| `"worker"` | `"web"` | Tipo do serviço (ver abaixo) | | `root` | string | `"."` | Diretório raiz do serviço no repositório (ver abaixo) | | `branch` | string | `"main"` | Branch para deploy | #### `root` — diretório raiz do serviço Define onde o código-fonte do serviço está no repositório. Em projetos simples, é `"."` (raiz). Em monorepos, aponta para o subdiretório do serviço (ex: `"apps/api"`). O `root` é usado pelo sistema de build para localizar o código do serviço. Quando `build.method` é `"dockerfile"`, o campo `build.context` herda o valor de `root` se não for definido explicitamente — ou seja, o Docker build context será o mesmo diretório do serviço. Se o seu Dockerfile precisa acessar arquivos fora do diretório do serviço (ex: pacotes compartilhados na raiz do monorepo), defina `build.context` separadamente: ```json { "root": "apps/api", "build": { "method": "dockerfile", "dockerfile": "apps/api/Dockerfile", "context": "." } } ``` Nesse exemplo, `root` indica que o serviço vive em `apps/api`, mas o Docker build context é a raiz do repo (`"."`), permitindo `COPY` de qualquer diretório. #### Tipos de Serviço | Tipo | Descrição | Porta HTTP | Domínio | | -------- | ------------------------------------- | -------------- | ------------- | | `web` | Servidor HTTP (APIs, Next.js, etc.) | ✅ Obrigatória | ✅ Automático | | `static` | Site estático (HTML/CSS/JS) | ❌ | ✅ Automático | | `worker` | Processo em background (filas, crons) | ❌ | ❌ | **Workers** são ideais para: - Filas de jobs (BullMQ, Agenda) - Cron jobs (node-cron) - Consumidores de mensagens (Kafka, RabbitMQ) - Pipelines de dados ```json { "services": { "workers/email": { "name": "email-worker", "type": "worker", "runtime": { "command": "npx tsx worker.ts" } } } } ``` ### `build` Configuração de build. A Veloz suporta dois métodos de build: | Campo | Tipo | Padrão | Descrição | | ---------------- | ------------------------------ | -------------- | ----------------------------------------------------------------- | | `method` | `"nixpacks"` \| `"dockerfile"` | `"nixpacks"` | Método de build (ver abaixo) | | `command` | string \| null | auto | Comando de build — nixpacks (`null` = auto-detectar) | | `dockerfile` | string | `"Dockerfile"` | Caminho do Dockerfile — quando `method` é `"dockerfile"` | | `context` | string | `root` | Diretório de contexto do build — quando `method` é `"dockerfile"` | | `nodeVersion` | string | `"22"` | Versão do Node.js (`"18"`, `"20"`, `"22"`) — nixpacks | | `packageManager` | string | `"auto"` | `"npm"`, `"yarn"`, `"pnpm"`, `"bun"`, `"auto"` — nixpacks | | `installCommand` | string \| null | auto | Comando de install customizado — nixpacks | | `outputDir` | string | `"dist"` | Diretório de output (sites estáticos) — nixpacks | | `aptPackages` | string[] | `[]` | Pacotes do sistema (ex: `ffmpeg`, `imagemagick`) — nixpacks | #### Método de build: nixpacks (padrão) Por padrão, a Veloz usa [nixpacks](https://nixpacks.com) para auto-gerar um Dockerfile a partir do seu código. Para projetos simples ou quando o nixpacks funciona de primeira, não é necessário configurar nada. ```json "build": { "command": "npm run build", "nodeVersion": "22", "packageManager": "pnpm", "outputDir": ".next", "aptPackages": ["ffmpeg", "libvips-dev"] } ``` #### Método de build: dockerfile Para projetos com requisitos complexos de build, é preferível usar seu próprio Dockerfile para builds mais confiáveis e reproduzíveis. Se o projeto tem dependências do sistema, multi-stage builds, ou precisa de controle total sobre o ambiente, use `method: "dockerfile"`. ```json "build": { "method": "dockerfile", "dockerfile": "docker/Dockerfile.prod", "context": "." } ``` - `dockerfile` — caminho relativo ao Dockerfile a partir da raiz do projeto - `context` — diretório de contexto do Docker build (onde os `COPY` resolvem). Se omitido, usa o valor de `root` do serviço. Defina explicitamente quando precisar de um contexto diferente do `root` (ex: `"."` para acessar a raiz do monorepo) #### Quando usar cada método | Cenário | Método recomendado | | ---------------------------------------- | ------------------- | | Maioria dos projetos (produção incluída) | `nixpacks` (padrão) | | Nixpacks funcionou de primeira | `nixpacks` | | Dependências nativas complexas | `dockerfile` | | Multi-stage build necessário | `dockerfile` | | Builds lentos ou imprevisíveis | `dockerfile` | | Ambiente de produção crítico | `dockerfile` | #### Pacotes do sistema (`aptPackages`) Use `aptPackages` (apenas com nixpacks) para instalar pacotes do sistema operacional que seu app precisa durante o build ou em runtime. Os nomes seguem a convenção de pacotes Ubuntu/Debian. ```json "build": { "aptPackages": ["ffmpeg", "libvips-dev"] } ``` **Regras de nomenclatura:** - Apenas letras minúsculas, números, `.`, `+` e `-` - Mínimo 2 caracteres - Deve começar com letra ou número - Exemplos válidos: `ffmpeg`, `libvips-dev`, `g++`, `python3.11` - Exemplos inválidos: `FFmpeg`, `my package`, `pkg=1.0` Para a lista completa de pacotes e exemplos por caso de uso, veja o guia [Pacotes do Sistema](/docs/pacotes-sistema). ### `runtime` Configuração de execução. | Campo | Tipo | Padrão | Descrição | | ---------------------- | -------------- | ------ | ------------------------------------------------------------- | | `command` | string \| null | auto | Comando de start | | `preStartCommand` | string \| null | — | Comando executado antes de iniciar o serviço (ex: migrations) | | `port` | number | `3000` | Porta do serviço (1-65535) | | `healthCheck.path` | string | `"/"` | Endpoint de health check | | `healthCheck.interval` | number | `30` | Intervalo entre checks (segundos) | | `healthCheck.timeout` | number | `10` | Timeout do check (segundos) | ```json "runtime": { "command": "node server.js", "preStartCommand": "npx prisma migrate deploy", "port": 8080, "healthCheck": { "path": "/health", "interval": 15, "timeout": 5 } } ``` #### `preStartCommand` — comando pré-start O `preStartCommand` é executado **antes** do serviço iniciar, em cada deploy. É ideal para: - **Migrations de banco de dados** — `npx prisma migrate deploy`, `npx drizzle-kit migrate`, `python manage.py migrate` - **Seed de dados** — `node scripts/seed.js` - **Cache warmup** — `node scripts/warm-cache.js` O comando roda no mesmo ambiente do serviço (mesma imagem, mesmas variáveis de ambiente, mesmo acesso a volumes). Se o comando falhar (exit code ≠ 0), o deploy é interrompido e marcado como falha. ```json "runtime": { "command": "node server.js", "preStartCommand": "npx prisma migrate deploy" } ``` Também pode ser configurado via CLI: ```bash veloz config set --pre-start "npx prisma migrate deploy" ``` ### `env` Declaração de variáveis de ambiente. Apenas as **chaves** e metadados ficam no `veloz.json` — os **valores** são definidos via CLI ou dashboard e nunca aparecem no arquivo. ```json "env": { "DATABASE_URL": { "description": "URL de conexão com o banco PostgreSQL", "required": true, "example": "postgres://user:pass@host:5432/db" }, "REDIS_URL": { "description": "URL do Redis para cache", "required": false } } ``` Isso serve como documentação viva das variáveis que o app precisa. ### `resources` Limites de CPU, memória e scaling. | Campo | Tipo | Padrão | Descrição | | ----------- | ------ | --------- | ----------------------------------------------------------------------------- | | `instances` | number | `1` | Número de instâncias (1-20) | | `cpu` | string | `"500m"` | Limite de CPU (`"100m"` a `"4"`; até `"8"` em instâncias dedicadas) | | `memory` | string | `"512Mi"` | Limite de memória (`"256Mi"` a `"8Gi"`; até `"32Gi"` em instâncias dedicadas) | ```json "resources": { "instances": 2, "cpu": "1", "memory": "1Gi", "autoscale": { "enabled": true, "minInstances": 1, "maxInstances": 5, "targetCPU": 70 } } ``` ### Autoscale | Campo | Tipo | Padrão | Descrição | | ------------------------ | ------- | ------- | ------------------------------ | | `autoscale.enabled` | boolean | `false` | Ativar autoscaling | | `autoscale.minInstances` | number | `1` | Mínimo de instâncias | | `autoscale.maxInstances` | number | `3` | Máximo de instâncias (até 20) | | `autoscale.targetCPU` | number | `70` | CPU alvo para escalar (10-90%) | ### `observability` Métricas e traces da sua aplicação. Declarar o bloco já liga o sinal: todos os campos são opcionais. | Campo | Tipo | Padrão | Descrição | | ------------------- | ------- | ------------------------- | -------------------------------------------------- | | `metrics.enabled` | boolean | `true` | `false` desliga a coleta e preserva a configuração | | `metrics.port` | number | O valor de `runtime.port` | Porta do endpoint Prometheus (1-65535) | | `metrics.path` | string | `"/metrics"` | Caminho do endpoint. Precisa começar com `/` | | `traces.enabled` | boolean | `true` | `false` desliga o envio e preserva a configuração | | `traces.sampleRate` | number | `1` | Fração de traces mantidos, de `0` a `1` | ```json "observability": { "metrics": { "port": 9090, "path": "/metrics" }, "traces": { "sampleRate": 0.25 } } ``` Para ligar os dois sinais com os padrões: ```json "observability": { "metrics": {}, "traces": {} } ``` > **Importante:** `metrics` e `traces` são objetos, não booleanos. `"traces": true` é recusado na validação. Os dashboards do Grafana são configurados no nível do projeto, não do serviço: ```json { "version": "1.0", "project": { "id": "proj_abc123", "name": "loja" }, "observability": { "dashboards": "./dashboards" }, "services": {} } ``` | Campo | Tipo | Padrão | Descrição | | ------------ | ------ | ------ | --------------------------------------------------- | | `dashboards` | string | Nenhum | Pasta de dashboards, relativa à raiz do repositório | Guia completo em [Observabilidade](/docs/observabilidade). ### `databases` Bancos de dados gerenciados. Cada chave é o nome do banco. | Campo | Tipo | Padrão | Descrição | | --------- | ------ | -------------- | ------------------------------------------------------------------------------------- | | `engine` | string | — | Obrigatório: `postgresql`, `mysql` ou `redis` | | `version` | string | (mais recente) | Versão do engine | | `storage` | string | `"10Gi"` | Tamanho do armazenamento persistente | | `size` | string | `"essencial"` | Tier de recursos: `basico`, `essencial`, `turbo`, `turbo-plus`, `nitro`, `nitro-plus` | | `pooler` | object | — | PgBouncer config (apenas PostgreSQL) | ```json "databases": { "postgres": { "engine": "postgresql", "version": "16", "storage": "20Gi", "size": "turbo", "pooler": { "enabled": true, "poolMode": "transaction" } } } ``` Ao executar `veloz deploy`, o CLI detecta alterações e atualiza automaticamente bancos existentes — tamanho (size), configurações do pooler e armazenamento (só cresce, nunca diminui). Para mais detalhes, veja a [documentação de bancos de dados](/docs/bancos-de-dados). ## Validação O `veloz.json` é validado automaticamente em cada deploy. Para validar manualmente, use o JSON Schema: ```json { "$schema": "https://onveloz.com/schemas/veloz-config.schema.json" } ``` Adicione o campo `$schema` no topo do arquivo para ter autocomplete e validação no VS Code e Cursor. ## Dicas - **Não edite `id`s manualmente** — eles são gerados pela Veloz e vinculam seu projeto/serviço ao servidor - **Commite o `veloz.json`** — ele deve ser versionado no Git para que toda a equipe use a mesma config - **Use `defaults`** em monorepos para evitar repetição entre serviços - **`null` = auto-detectar** — use `null` em `build.command` ou `runtime.command` para deixar a Veloz detectar automaticamente ## Próximos passos - [Pacotes do Sistema](/docs/pacotes-sistema) — Instalar ffmpeg, Puppeteer, sharp, etc. - [Monorepo](/docs/monorepo) — Deploy de múltiplos apps - [Configuração](/docs/config) — Editar config via CLI - [Variáveis de Ambiente](/docs/variaveis-ambiente) — Gerenciar secrets --- # ⚙️ Configurações Ajuste as configurações de build, runtime e recursos dos seus serviços. ## Ver configurações atuais ```bash veloz config show ``` ``` 📋 Configurações do Serviço Nome: meu-projeto Tipo: Serviço Web Branch: main Root Dir: / Build Command: pnpm run build Start Command: pnpm run start Porta: 3000 Instâncias: 1 CPU Limit: — Memory Limit: — ``` ## Alterar configurações Via flags: ```bash veloz config set --build "npm run build" veloz config set --start "npm start" --port 8080 veloz config set --instances 2 --cpu 500m --memory 512Mi veloz config set --branch develop ``` Ou interativamente: ```bash veloz config edit ``` A CLI mostra cada campo com o valor atual, e você pode editar ou pular (Enter). > Após alterar configurações, execute `veloz deploy` para aplicar. ## Resetar configurações ```bash veloz config reset --build # reseta só o build command veloz config reset --start # reseta só o start command veloz config reset --pre-start # reseta só o pre-start command veloz config reset --all # reseta build, start, pre-start e root dir ``` ## Opções disponíveis - `--name` — Nome do serviço - `--build` — Comando de build - `--start` — Comando de start - `--port` — Porta do serviço - `--root` — Diretório raiz - `--instances` — Número de instâncias - `--cpu` — Limite de CPU (ex: `500m`, `1`) - `--memory` — Limite de memória (ex: `512Mi`, `1Gi`) - `--branch` — Branch do Git ## Próximos passos - [CLI Reference](/docs/cli) — Referência completa de comandos --- # 🔑 Variáveis de Ambiente Gerencie variáveis de ambiente dos seus serviços via CLI. ## Listar variáveis ```bash veloz env list ``` Exibe uma tabela com chave, valor mascarado e data de atualização. ## Definir variáveis Uma ou mais variáveis no formato `CHAVE=VALOR`: ```bash veloz env set DATABASE_URL="postgresql://user:pass@host/db" veloz env set API_KEY="abc123" STRIPE_KEY="sk_live_..." ``` > Após alterar variáveis, é necessário fazer um novo deploy para aplicar. ## Importar de arquivo Importa variáveis de um arquivo `.env`: ```bash veloz env import .env ``` Ou sem argumento para colar interativamente: ```bash veloz env import ``` ``` 📋 Modo de colagem interativo Cole seu conteúdo .env abaixo. Pressione Ctrl+D quando terminar: ``` A CLI parseia o conteúdo, mostra preview, e pede confirmação antes de aplicar. ### Modo substituição Para substituir todas as variáveis existentes (remove as antigas antes): ```bash veloz env import .env --replace ``` ## Exportar variáveis ```bash veloz env export # imprime no terminal (valores mascarados) veloz env export .env.backup # salva em arquivo ``` > Os valores exportados são mascarados por segurança. ## Remover variável ```bash veloz env delete API_KEY ``` ## Próximos passos - [Logs](/docs/logs) — Acompanhe seu app em tempo real - [Configurações](/docs/config) — Ajuste build, porta, recursos - [Bancos de Dados](/docs/bancos-de-dados) — Bancos gerenciados --- # 🗄️ Bancos de Dados A Veloz oferece bancos de dados gerenciados como serviços de primeira classe. PostgreSQL, MySQL e Redis — provisionados automaticamente, com backups, connection pooling e variáveis de ambiente injetadas nos seus serviços. ## Engines suportados | Engine | Versões disponíveis | Porta padrão | | ------------ | ------------------- | ------------ | | **PostgreSQL** | 17, 16, 15, 14 | 5432 | | **MySQL** | 8.4, 8.0 | 3306 | | **Redis** | 7, 6 | 6379 | Se nenhuma versão for especificada, a Veloz usa a mais recente (PostgreSQL 17, MySQL 8.4, Redis 7). ## Tamanhos disponíveis ### PostgreSQL e MySQL | Tamanho | CPU | Memória | |---------------|-----------|---------| | `basico` | 0.25 vCPU | 256 MB | | `essencial` | 0.5 vCPU | 512 MB | | `turbo` | 1 vCPU | 1 GB | | `turbo-plus` | 1.5 vCPU | 2 GB | | `nitro` | 2 vCPU | 4 GB | | `nitro-plus` | 4 vCPU | 8 GB | ### Redis | Tamanho | CPU | Memória | |---------------|-----------|---------| | `basico` | 0.15 vCPU | 128 MB | | `essencial` | 0.25 vCPU | 256 MB | | `turbo` | 0.25 vCPU | 512 MB | | `turbo-plus` | 0.5 vCPU | 1 GB | | `nitro` | 0.5 vCPU | 2 GB | | `nitro-plus` | 1 vCPU | 4 GB | O tamanho padrão é `essencial`. ## CLI de bancos de dados ```bash # Criar PostgreSQL com pooler veloz db create --name postgres --engine postgresql --storage 20Gi --size essencial --pooler # Criar MySQL veloz db create --name mysql --engine mysql --version 8.4 --storage 10Gi # Criar Redis veloz db create --name cache --engine redis --size turbo # Listar bancos veloz db list # Ver credenciais veloz db credentials postgres # Reiniciar veloz db restart postgres # Excluir veloz db delete postgres ``` ## Configuração via veloz.json ```json { "databases": { "postgres": { "engine": "postgresql", "version": "16", "storage": "20Gi", "size": "essencial", "pooler": { "enabled": true, "poolMode": "transaction", "defaultPoolSize": 20, "maxClientConn": 100 } }, "cache": { "engine": "redis", "size": "basico" } } } ``` ### Campos | Campo | Tipo | Padrão | Descrição | | --------- | ------ | -------------- | ------------------------------------------------------------------------- | | `engine` | string | — | Obrigatório: `postgresql`, `mysql` ou `redis` | | `version` | string | (mais recente) | Versão do engine | | `storage` | string | `"10Gi"` | Tamanho do disco persistente (mínimo 10Gi) | | `size` | string | `"essencial"` | Tier: `basico`, `essencial`, `turbo`, `turbo-plus`, `nitro`, `nitro-plus` | | `pooler` | object | — | PgBouncer (apenas PostgreSQL) | ### Pooler (PgBouncer) | Campo | Tipo | Padrão | Descrição | | ----------------- | ------- | --------------- | ------------------------------------- | | `enabled` | boolean | `false` | Ativar PgBouncer sidecar | | `poolMode` | string | `"transaction"` | `transaction`, `session`, `statement` | | `defaultPoolSize` | number | `20` | Conexões por pool (1-200) | | `maxClientConn` | number | `100` | Max conexões de clientes (1-10000) | ## Deploy atualiza bancos existentes Ao rodar `veloz deploy`, se a configuração no `veloz.json` mudou em relação ao banco existente, o CLI aplica alterações automaticamente: - **Tamanho (size)** — altera CPU/memória se o tier mudou (ex: `essencial` → `turbo`) - **Pooler** — ativa/desativa PgBouncer ou altera o pool mode - **Storage** — redimensiona o volume se o novo tamanho é maior (volumes só crescem, nunca diminuem) O banco precisa estar **LIVE** para aceitar alterações de tamanho e pooler. ## Variáveis de ambiente auto-injetadas Quando um banco está **LIVE**, connection strings são injetadas automaticamente nos serviços do projeto: | Variável | Descrição | | --------------------------- | ---------------------------------------------- | | `{NOME}_DATABASE_URL` | URL de conexão direta | | `{NOME}_HOST` | Hostname interno | | `{NOME}_PORT` | Porta do engine | | `{NOME}_USERNAME` | Usuário do banco | | `{NOME}_PASSWORD` | Senha gerada automaticamente | | `{NOME}_DATABASE` | Nome do database | | `{NOME}_POOLER_URL` | URL via PgBouncer (se habilitado, porta 6432) | | `{NOME}_POOLER_PORT` | Porta do pooler | O prefixo é o nome do banco em UPPER_SNAKE_CASE (ex: banco `postgres` → `POSTGRES_DATABASE_URL`). Se existe apenas um banco de um tipo no projeto, variáveis genéricas são injetadas: `DATABASE_URL` (PostgreSQL/MySQL) ou `REDIS_URL` (Redis). ## PgBouncer (Connection Pooler) PgBouncer roda como sidecar junto ao PostgreSQL. Modos disponíveis: - **`transaction`** (recomendado) — conexão devolvida ao pool após cada transação - **`session`** — conexão mantida durante toda a sessão do cliente - **`statement`** — conexão devolvida após cada statement ### Uso com Prisma ```prisma datasource db { provider = "postgresql" url = env("POSTGRES_POOLER_URL") // pooled — para queries directUrl = env("POSTGRES_DATABASE_URL") // direto — para migrations } ``` ## Limites - Máximo de **5 bancos por projeto** - Armazenamento mínimo: **10 GB** - Volumes só crescem — não é possível reduzir o tamanho do disco - PgBouncer disponível apenas para PostgreSQL ## Próximos passos - [veloz.json](/docs/veloz-json) — Referência completa do arquivo de configuração - [Variáveis de Ambiente](/docs/variaveis-ambiente) — Gerenciar secrets --- # 🗂️ Blob Storage Blob Storage guarda arquivos (imagens, uploads de usuários, assets) e os serve por uma CDN global. Cada blob store recebe um domínio dedicado, como `meu-app.cdn.runveloz.com`, e você envia objetos a partir do seu app com o SDK `@onveloz/blob` ou direto pela API REST. ## Quando usar Blob Storage Blob Storage é o lugar padrão para os arquivos do seu app: uploads de usuários, imagens, PDFs, exportações e assets gerados. Comparado a um [Volume](/docs/volumes): - funciona com qualquer número de instâncias, então o serviço continua escalando horizontalmente; - os arquivos sobrevivem a deploys, reinícios e mudanças de tamanho sem nenhuma configuração; - a entrega sai pela CDN, sem consumir CPU nem banda do seu serviço. Use um Volume só quando um software exige um diretório no disco local, como um app que guarda um banco SQLite em arquivo. Para dados estruturados, prefira um [banco de dados gerenciado](/docs/bancos-de-dados). > **Importante:** todo objeto é público. Quem tiver a URL consegue baixar o arquivo, então não envie dados sensíveis sem criptografar. A API não lista nem lê objetos: guarde as chaves (`uploads/foto.png`) no seu banco de dados. ## Criar um blob store No dashboard, dentro do seu projeto, adicione um recurso **Blob Store**. Logo após criar, você verá o guia de início rápido com a sua primeira chave de API já gerada. Copie a chave nesse momento: por segurança, ela não é exibida novamente. Pela CLI, ou pelo MCP com as ferramentas `blob_*`: ```bash veloz blob create uploads veloz env set VELOZ_BLOB_TOKEN=vbk_sua_chave ``` `veloz blob create` mostra a primeira chave uma única vez. Para gerar outra, use `veloz blob key-create uploads `. ## Autenticação Toda chamada à API usa uma chave `vbk_*` no cabeçalho `Authorization`: ``` Authorization: Bearer vbk_sua_chave ``` A chave é vinculada a um blob store específico e concede acesso de leitura e escrita a ele. Trate como senha: defina em variável de ambiente (`VELOZ_BLOB_TOKEN`) e nunca commite no Git. Gere e revogue chaves na aba **Chaves de API** do store. > **Segurança:** a chave de API só trafega no cabeçalho `Authorization`, nunca na URL. As URLs de upload contêm um parâmetro `?token=` que é uma assinatura temporária gerada pelo servidor, não a sua chave. ## SDK `@onveloz/blob` A forma recomendada de integrar. Instale: ```bash npm install @onveloz/blob ``` Defina o token no ambiente: ``` VELOZ_BLOB_TOKEN=vbk_sua_chave ``` Envie e remova arquivos: ```ts import { put, del } from "@onveloz/blob"; // Lê VELOZ_BLOB_TOKEN do ambiente (ou passe { token }). const blob = await put("uploads/foto.png", arquivo, { access: "public", contentType: "image/png", }); console.log(blob.url); // https://meu-app.cdn.runveloz.com/uploads/foto.png await del("uploads/foto.png"); ``` `put` aceita `string`, `Blob`, `ArrayBuffer`, `Uint8Array` ou `ReadableStream` como corpo. Para apontar para outro ambiente, defina `VELOZ_BLOB_API` ou passe `apiUrl` em cada chamada. ### Cliente com configuração fixa ```ts import { BlobClient } from "@onveloz/blob"; const blob = new BlobClient({ token: process.env.VELOZ_BLOB_TOKEN }); await blob.put("uploads/foto.png", arquivo); await blob.del("uploads/foto.png"); ``` ### Erros O SDK lança erros tipados: `BlobAccessError` (token ausente ou inválido, 401/403), `BlobQuotaError` (blob store sem espaço na cota, `code` `blob/quota-exceeded`), `BlobUploadError` (falha no envio) e `BlobError` (genérico, com `code` e `status`). ## API REST O SDK é só um cliente fino sobre esta API. A base é `https://platform.onveloz.com`. ### 1. Gerar URL de upload `POST /api/blob/v1/upload-url` troca a sua chave de API por uma URL de upload assinada. ```bash curl -X POST https://platform.onveloz.com/api/blob/v1/upload-url \ -H "Authorization: Bearer $VELOZ_BLOB_TOKEN" \ -H "Content-Type: application/json" \ -d '{"key":"uploads/foto.png","contentType":"image/png"}' ``` Resposta: ```json { "uploadUrl": "https://meu-app.cdn.runveloz.com/uploads/foto.png?token=...&expires=...", "publicUrl": "https://meu-app.cdn.runveloz.com/uploads/foto.png", "expires": "1717000000", "key": "uploads/foto.png" } ``` ### 2. Enviar o arquivo Faça um `PUT` direto na `uploadUrl` retornada. Essa URL já está assinada, então não leva o cabeçalho `Authorization`. ```bash curl -X PUT "" \ -H "Content-Type: image/png" \ --data-binary @foto.png ``` Depois disso, o arquivo fica disponível na `publicUrl`. ### 3. Remover um objeto `DELETE /api/blob/v1/objects` remove por chave. É idempotente: chaves inexistentes retornam sucesso. ```bash curl -X DELETE "https://platform.onveloz.com/api/blob/v1/objects?key=uploads%2Ffoto.png" \ -H "Authorization: Bearer $VELOZ_BLOB_TOKEN" ``` ## Acesso público Os objetos são servidos pelo domínio CDN do store (`https://.cdn.runveloz.com/`). Domínios customizados e regras de CORS ainda não estão disponíveis para blob stores. ## Custos R$0,25/GB/mês, calculado proporcionalmente à hora sobre o espaço armazenado. Cada organização tem 1 GB grátis em todos os planos. → [Veja a tabela de preços completa](/precos) --- # 🖥️ Browser API A Browser API entrega sessões de navegador headless (Chromium) rodando na infraestrutura da Veloz, com **stealth garantido** em toda sessão, prontas para você controlar via Playwright com `chromium.connectOverCDP(...)`. Use para automação, scraping, testes end-to-end, geração de PDFs/screenshots ou qualquer fluxo que precise de um navegador real e isolado, sem manter Chromium na sua própria infraestrutura. Você cria uma sessão, recebe uma `connectUrl` (um endpoint CDP sobre WebSocket) e conecta com o seu próprio `playwright`/`playwright-core`. A Veloz cuida do provisionamento, do isolamento e do encerramento. > **Nota:** a Browser API está em **early access** (acesso antecipado) e é liberada por organização. Se a seção **Sessões de navegador** ainda não aparece no seu dashboard, peça acesso ao suporte: abra um chamado em **Suporte** no dashboard ou rode `veloz support create --subject "Acesso à Browser API" --message "Quero testar a Browser API na minha organização."`. ## Comece em 2 minutos O caminho mais curto até um navegador rodando na Veloz: sem escolher engine e sem opção nenhuma. ### 1. Crie uma chave No dashboard, abra **Sessões de navegador → Chaves de API**, crie uma chave e copie (ela aparece uma única vez). No terminal: ```bash export VELOZ_BROWSER_TOKEN=bk_live_sua_chave ``` ### 2. Rode o primeiro navegador ```bash npm install @onveloz/browser playwright-core ``` Salve como `inicio.mjs`: ```js import { Onveloz } from "@onveloz/browser"; import { chromium } from "playwright-core"; const ov = new Onveloz(); // lê VELOZ_BROWSER_TOKEN do ambiente const browser = await chromium.connectOverCDP(await ov.connect()); const page = await browser.contexts()[0].newPage(); await page.goto("https://example.com"); console.log(await page.title()); await page.waitForTimeout(30_000); // 30 s para assistir no dashboard await browser.close(); // ao desconectar, a sessão é encerrada ``` ```bash node inicio.mjs # Example Domain ``` ### 3. Assista ao vivo Enquanto o script espera, abra **Sessões de navegador** no dashboard. A sessão aparece como **Ativa**: clique em **Ao vivo** para ver a tela do navegador em tempo real. Quando o script fecha o navegador, a sessão é encerrada. Pronto. As seções abaixo detalham o SDK, a API REST, a CLI, a escolha do navegador e as opções de cada sessão. ## Chaves de API Toda chamada usa uma chave `bk_live_*` no cabeçalho `Authorization`: ``` Authorization: Bearer bk_live_sua_chave ``` Gere e revogue chaves na seção **Sessões de navegador → Chaves de API** do dashboard. A chave é vinculada à sua organização e concede acesso para criar e controlar sessões. > **Segurança:** a chave é exibida uma única vez na criação. Copie nesse momento, trate como senha, defina em variável de ambiente (`VELOZ_BROWSER_TOKEN`) e nunca commite no Git. ## SDK `@onveloz/browser` A forma recomendada de integrar a partir de Node. O SDK **não** embute o Playwright: ele entrega a `connectUrl` e você conecta com o seu próprio cliente. ```bash npm install @onveloz/browser playwright-core ``` Defina o token no ambiente: ``` VELOZ_BROWSER_TOKEN=bk_live_sua_chave ``` ### Conectar para acordar (uma linha) Nenhuma sessão é criada de antemão: um navegador quente é provisionado quando você abre o socket CDP e encerrado quando você desconecta. O limite de simultaneidade é checado no momento da conexão. ```ts import { Onveloz } from "@onveloz/browser"; import { chromium } from "playwright-core"; const ov = new Onveloz(); // lê VELOZ_BROWSER_TOKEN do ambiente const browser = await chromium.connectOverCDP(await ov.connect()); const page = await browser.contexts()[0].newPage(); await page.goto("https://exemplo.com"); console.log(await page.title()); await browser.close(); // ao desconectar, o navegador é encerrado ``` ### Sessão explícita Quando você precisa do ciclo de vida na mão (criar agora, conectar depois, listar, encerrar): ```ts import { Onveloz } from "@onveloz/browser"; import { chromium } from "playwright-core"; const ov = new Onveloz(); // O provisionamento roda fora da requisição, então a sessão nasce PENDING. const session = await ov.sessions.create(); // Aguarda ficar RUNNING com connectUrl disponível (polling interno). const ready = await ov.sessions.waitUntilReady(session.id); const browser = await chromium.connectOverCDP(ready.connectUrl!); const page = await browser.contexts()[0].newPage(); await page.goto("https://exemplo.com"); await browser.close(); await ov.sessions.close(session.id); ``` Métodos disponíveis no namespace `ov.sessions`: | Método | Descrição | | --------------------------- | ------------------------------------------------------------------------------------------- | | `create(config?, opts?)` | Cria uma sessão (nasce `PENDING`, `connectUrl: null`). `opts.idempotencyKey` evita duplicar | | `get(id)` | Busca uma sessão e seu `connectUrl` quando `RUNNING` | | `list({ activeOnly? })` | Lista as sessões da organização | | `close(id)` | Encerra uma sessão | | `liveView(id)` | Gera a URL de visualização ao vivo (sob demanda) | | `waitUntilReady(id, opts?)` | Faz polling até `RUNNING` ou lança em estado terminal/timeout | No namespace `ov.engines`: | Método | Descrição | | ------------- | -------------------------------------------------------------- | | `list()` | Lista os engines e se cada um já inicia sessões (`available`) | | `options(id)` | Configurações que um engine aceita em `settings` e suas listas | E no cliente `ov`: | Método | Descrição | | ------------------ | ----------------------------------------------------------------- | | `connect(config?)` | Gera uma `connectUrl` de conectar-para-acordar (sem criar sessão) | | `token(config?)` | Alias de `connect()` | Para apontar a um ambiente alternativo, passe `{ apiUrl }` ou defina `VELOZ_BROWSER_API`. ## API REST Para linguagens fora de Node, fale direto com a API. Base: `https://platform.onveloz.com/api/browser`. Todas as chamadas exigem o cabeçalho `Authorization: Bearer bk_live_*`. | Método e rota | Descrição | | -------------------------------- | -------------------------------------------------------------- | | `POST /v1/sessions` | Cria uma sessão (provisionamento roda em segundo plano) | | `GET /v1/sessions` | Lista as sessões da organização (`?activeOnly=true`) | | `GET /v1/sessions/:id` | Busca uma sessão e seu `connectUrl` | | `GET /v1/sessions/:id/live-view` | Gera a URL de visualização ao vivo (sob demanda) | | `DELETE /v1/sessions/:id` | Encerra uma sessão | | `POST /v1/connect-token` | Gera uma `connectUrl` de conectar-para-acordar | | `GET /v1/engines` | Lista os engines e se cada um já inicia sessões | | `GET /v1/engines/:id/options` | Configurações que um engine aceita em `settings` e suas listas | ### Criar e conectar ```bash # 1) Cria a sessão: ela nasce PENDING. curl -X POST https://platform.onveloz.com/api/browser/v1/sessions \ -H "Authorization: Bearer bk_live_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "timeoutSec": 300 }' # → { "id": "...", "status": "PENDING", "connectUrl": null, "expiresAt": "..." } # 2) Faça polling até connectUrl aparecer (sessão RUNNING). curl https://platform.onveloz.com/api/browser/v1/sessions/SESSION_ID \ -H "Authorization: Bearer bk_live_sua_chave" # → { ..., "status": "RUNNING", "connectUrl": "wss://.../v1/connect?token=...", # "liveViewPath": "/v1/sessions/SESSION_ID/live-view" } ``` Depois, conecte ao `connectUrl` com qualquer cliente CDP (Playwright, Puppeteer, ou o protocolo cru). ### Estados da sessão | Status | Descrição | | ---------- | ------------------------------------------------- | | `PENDING` | Provisionando, ainda sem `connectUrl` | | `RUNNING` | Pronta, com `connectUrl` disponível para conectar | | `RELEASED` | Encerrada (por você ou por inatividade) | | `EXPIRED` | Atingiu o TTL e foi encerrada | | `FAILED` | Falhou ao provisionar | ## Pelo terminal e por agentes de IA A CLI da Veloz cobre o mesmo fluxo. Os comandos usam o login da CLI (`veloz login`), sem chave `bk_live_*`: | Comando | O que faz | | -------------------------------- | -------------------------------------------------------------------------------------------------- | | `veloz browser engines` | Lista os engines e se cada um já inicia sessões | | `veloz browser options ` | Mostra as configurações que o engine aceita | | `veloz browser create` | Cria uma sessão (`--proxy-id` usa um proxy salvo) | | `veloz browser list` | Lista as sessões da organização | | `veloz browser stop ` | Encerra uma sessão | | `veloz browser connect-url` | Gera uma URL de conexão para o seu cliente CDP | | `veloz browser proxies` | Lista, mostra, salva, altera e exclui proxies salvos (`list`, `get`, `create`, `update`, `delete`) | Rode `veloz browser --help` para ver as flags de cada comando. Para agentes de IA, `veloz mcp add` registra a CLI como servidor MCP no Claude Code, no Cursor e em outros editores. As mesmas operações viram ferramentas: `browser_engines`, `browser_options`, `browser_create`, `browser_list`, `browser_stop`, `browser_connect_url` e, para os proxies salvos, `browser_proxies_list`, `browser_proxies_get`, `browser_proxies_create`, `browser_proxies_update` e `browser_proxies_delete`. A senha de um proxy nunca é argumento de ferramenta: ela vem de `VELOZ_BROWSER_PROXY_PASSWORD` no ambiente do servidor MCP ou do prompt da CLI. Veja [MCP & Agentes IA](/docs/mcp). ## Stealth Toda sessão já roda com as proteções anti-detecção ativas: fingerprint coerente (locale e timezone alinhados com a geo de saída), WebGL funcional via a stack GL nativa do Linux (Mesa/llvmpipe) e supressão de vazamentos do protocolo. O stealth é **garantido e não configurável**: não há nada para ligar, e não é possível desligar. Sobre o WebGL: as sessões rodam em máquinas sem GPU dedicada, então a renderização é por software. Isso é proposital. O `UNMASKED_RENDERER` reportado é o mesmo de qualquer servidor Linux sem GPU, que é justamente o que somos, em vez do `SwiftShader` que denuncia um Chrome headless. Desligar o WebGL seria pior: `getContext("webgl")` retornaria `null`, um sinal muito mais chamativo. ## Use o seu próprio proxy Por padrão o egresso é direto. Para sair por um proxy, **traga o seu**: informe o gateway em `proxyServer` (e credenciais, se houver). O `proxyCountry` mantém o fingerprint de stealth coerente com a geo de saída do seu proxy. ```ts const session = await ov.sessions.create({ proxyServer: "http://gateway.seu-proxy.com:8080", // http, https ou socks5 proxyUsername: "usuario", // opcional (omita para proxy autorizado por IP) proxyPassword: "senha", // opcional proxyCountry: "US", // opcional: país de saída do seu proxy }); ``` As credenciais são criptografadas em repouso e nunca retornadas nas respostas da API. O proxy próprio vale em `create()` e em `connect()`. Em `connect()`, as credenciais ficam guardadas no servidor até a URL expirar, e a URL só leva uma referência a elas. ## Proxies salvos Salve um proxy uma vez, com um nome, e use pelo id em `proxyId`. O id vale em `create()` e em `connect()`, sem mandar as credenciais em cada requisição. ```ts const proxy = await ov.proxies.create({ name: "residencial-us", // único na organização server: "http://gateway.seu-proxy.com:8080", // http, https ou socks5, sem usuário e senha username: "usuario", // opcional password: "senha", // opcional country: "US", // opcional: país de saída do proxy }); const session = await ov.sessions.create({ proxyId: proxy.id }); const browser = await chromium.connectOverCDP(await ov.connect({ proxyId: proxy.id })); ``` No SDK, `ov.proxies` tem `list()`, `get(id)`, `create(input)`, `update(id, patch)` e `delete(id)`. Na API REST: | Método | Rota | O que faz | | -------- | ----------------- | --------------------------------------------------------------------------------- | | `GET` | `/v1/proxies` | Lista os proxies salvos da organização (`{ "proxies": [ ... ] }`) | | `POST` | `/v1/proxies` | Salva um proxy | | `GET` | `/v1/proxies/:id` | Lê um proxy salvo | | `PATCH` | `/v1/proxies/:id` | Altera só os campos enviados; `null` em `username`, `password` ou `country` limpa | | `DELETE` | `/v1/proxies/:id` | Exclui o proxy salvo | ```bash curl -X POST https://platform.onveloz.com/api/browser/v1/proxies \ -H "Authorization: Bearer bk_live_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "name": "residencial-us", "server": "http://gateway.seu-proxy.com:8080", "username": "usuario", "password": "senha", "country": "US" }' # → { "id": "...", "name": "residencial-us", "server": "http://gateway.seu-proxy.com:8080", # "username": "usuario", "hasPassword": true, "country": "US", "lastCheck": null, ... } ``` - **A senha nunca volta.** As credenciais são criptografadas em repouso. As respostas trazem `server` sem credenciais, `username` e `hasPassword`, nunca a senha. - **Um ou outro.** `proxyId` não vai junto com `proxyServer`, `proxyUsername`, `proxyPassword` ou `proxyCountry`: a requisição volta `400`. O país da sessão vem do proxy salvo. - **Só a sua organização.** Um id de outra organização volta `404`, igual a um id que não existe. Um nome repetido volta `409`, assim como passar de 100 proxies salvos. - **Último teste.** Cada sessão aberta por um proxy salvo guarda em `lastCheck` o que o navegador viu na saída (IP, país, cidade, latência) e a hora em `lastCheckedAt`. Quando o proxy falha, `lastCheck` traz `{ "ok": false, "cause": "proxy_failed" }`. Trocar servidor, usuário ou senha apaga o último teste. - **Alterar e excluir.** Uma URL de `connect()` usa o proxy como ele estiver na hora de conectar. Excluir o proxy faz essas URLs pararem de funcionar; sessões já criadas com ele seguem até o fim. ## Escolher o navegador Cada sessão roda um **engine**: o navegador e a camada de automação que o controla. Sem `engine`, a sessão usa o engine padrão (`patchright`), como no **Comece em 2 minutos**. A lista de engines cresce com o tempo. Só iniciam sessões os engines que `GET /v1/engines` marca com `available: true`. Os marcados com `available: false` aparecem no catálogo, mas ainda não podem ser criados: o pedido volta `400` com o código `unavailable`. ### Descobrir engines ```bash curl https://platform.onveloz.com/api/browser/v1/engines \ -H "Authorization: Bearer bk_live_sua_chave" # → { "engines": [ { "id": "...", "label": "...", "available": true, ... } ] } ``` ```ts const engines = await ov.engines.list(); const prontos = engines.filter((engine) => engine.available).map((engine) => engine.id); ``` Cada engine traz: | Campo | Descrição | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | O valor de `engine` ao criar a sessão | | `label` | Nome de exibição | | `available` | `true` quando o engine já inicia sessões (sem opções) | | `experimental` | Engine em fase experimental | | `limitations` | O que o engine não faz que os outros fazem, em uma frase; `null` quando não há limite. Aparece também no dashboard, ao escolher o engine | | `protocol` | Como o cliente controla a sessão: `cdp` (Chrome DevTools Protocol, use `connectOverCDP`) ou `playwright` (protocolo do Playwright) | | `capabilities` | Um booleano por recurso que o engine aceita, como `headful`, `headless`, `locale`, `timezoneId`, `userAgent`, `flags`, `extensions`, `initScripts`, `geolocation` e `proxy` | | `headlessDefault` | O modo do navegador quando você omite `options.headless` | | `os` | Valores aceitos em `options.os` | | `proxySchemes` | Esquemas de proxy aceitos (`http`, `https`, `socks5`); vazio quando o engine não aceita proxy | | `browser` | Navegador padrão e versão (`version` pode ser `null`) | | `executables` | Builds que `options.executable` escolhe, o padrão primeiro; vazio quando o engine tem um só | | `license` | Licença do engine | ### Engines experimentais Os engines com `experimental: true` iniciam sessões, mas têm limites que os outros não têm. O campo `limitations` de cada um resume esses limites: - **`cloakbrowser`** é controlado por CDP (`connectOverCDP`) e não repassa ao cliente as mensagens do console da página, por decisão do fabricante do navegador. Por isso `page.setContent` não termina e os eventos `page.on('console')` e `page.on('pageerror')` não disparam. Navegar, ler e preencher elementos, executar scripts e capturar a tela funcionam. Os substitutos estão logo abaixo da lista. - **`camofox`** roda o Camoufox, um Firefox, pelo protocolo do Playwright (`protocol: "playwright"`). Conecte com `firefox.connect()` do Playwright 1.59.x. Com outra versão, a conexão é recusada na hora com uma mensagem que diz qual versão usar. A visualização ao vivo não está disponível para ele. - **`obscura`** só roda em headless e é controlado por CDP (`connectOverCDP`). Navegar (`page.goto`), executar scripts (`page.evaluate`) e capturar a tela (`Page.captureScreenshot`) funcionam. `page.setContent` e a visualização ao vivo não estão disponíveis. No `cloakbrowser`, troque `page.setContent` por `document.write` e leia o console por um script que roda antes da página: ```js // Registre antes de navegar: guarda o console de cada página em window.__logs await page.addInitScript(() => { window.__logs = []; for (const level of ["log", "error"]) { const original = console[level]; console[level] = (...args) => { window.__logs.push(`${level}: ${args.join(" ")}`); return original.apply(console, args); }; } }); await page.goto("https://example.com"); console.log(await page.evaluate(() => window.__logs)); // No lugar de page.setContent(html) const html = "

Olá

"; await page.evaluate((content) => { document.open(); document.write(content); document.close(); }, html); await page.waitForLoadState("load"); console.log(await page.locator("h1").textContent()); // Olá ``` ### Criar com engine e opções O exemplo usa o engine padrão com `locale` e `timezoneId`: ```bash curl -X POST https://platform.onveloz.com/api/browser/v1/sessions \ -H "Authorization: Bearer bk_live_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "engine": "patchright", "options": { "locale": "pt-BR", "timezoneId": "America/Sao_Paulo" }, "timeoutSec": 300 }' # → { "id": "...", "status": "PENDING", "connectUrl": null, "expiresAt": "..." } ``` ```ts const session = await ov.sessions.create({ engine: "patchright", options: { locale: "pt-BR", timezoneId: "America/Sao_Paulo" }, timeoutSec: 300, }); ``` Um `locale` ou `timezoneId` informado em `options` vale sobre o que o stealth derivaria de `proxyCountry`. Opções aceitas em `options`: | Opção | Tipo | Regras | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `headless` | boolean | Roda sem janela. Omitida, vale `headlessDefault`. O engine precisa aceitar o modo pedido | | `locale` | string | Locale BCP 47 da lista `locales` (ex: `"pt-BR"`), até 64 caracteres | | `timezoneId` | string | Fuso IANA da lista `timezones` (ex: `"America/Sao_Paulo"`), até 128 caracteres | | `userAgent` | string | User agent da sessão, até 1024 caracteres | | `os` | string | `"windows"`, `"macos"` ou `"linux"`, entre os que o engine lista em `os` | | `flags` | string[] | Flags extras do Chromium: até 32, com até 256 caracteres cada. Cada engine aceita só a sua lista | | `settings` | object | Configurações do engine por id (veja abaixo) | | `extensions` | object[] | Até 5, cada uma `{ "webStoreId": "..." }` (id de 32 letras da Chrome Web Store) ou `{ "url": "https://..." }` | | `initScripts` | string[] | Até 10 scripts não vazios, 256 KiB no total, que toda página roda antes do próprio código | | `executable` | string | Id de um build em `executables`. Só em engines com mais de um build | | `geolocation` | object | `{ "latitude": -23.55, "longitude": -46.63, "accuracy": 50 }`: latitude de -90 a 90, longitude de -180 a 180, `accuracy` em metros (opcional, maior que zero) | Cada opção depende de uma capacidade do engine (`capabilities`). Textos não aceitam caracteres de controle, e uma chave fora desta tabela volta `unknown_option`. Com `extensions` e sem `executable`, roda o primeiro build que carrega extensões. `locale`, `timezoneId` e `geolocation` valem no contexto padrão do navegador, o primeiro de `browser.contexts()` no Playwright ou `browser.defaultBrowserContext()` no Puppeteer. Um contexto que a sua automação cria depois pode não herdá-los: passe os mesmos valores ao criá-lo. Já os `initScripts` rodam em todos os contextos. Uma opção que o engine descreve ainda pode ser recusada com o código `unavailable` enquanto não estiver liberada para ele. O `issues` da resposta diz qual opção foi recusada (veja **Erros**). ### Configurações do engine (`settings`) Além das opções da tabela, cada engine publica as próprias configurações. Os ids seguem o formato `mecanismo:chave` (por exemplo, `context-option:viewport`) e mudam de um engine para outro. Consulte os de cada engine: ```bash curl https://platform.onveloz.com/api/browser/v1/engines/patchright/options \ -H "Authorization: Bearer bk_live_sua_chave" # → { "engine": { ... }, "settings": [ ... ], "lists": { "locales": [ ... ], "timezones": [ ... ], ... } } ``` ```ts const { settings, lists } = await ov.engines.options("patchright"); ``` Um id de engine que não existe responde `404` (no SDK, `BrowserAccessError` com `status: 404`). Cada item de `settings` traz: | Campo | Descrição | | ------------- | ---------------------------------------------------------------------------------------------------------- | | `id` | A chave em `options.settings` | | `label` | Nome de exibição | | `type` | `boolean`, `number`, `string`, `enum`, `string[]` ou `object` | | `category` | Grupo da configuração | | `choices` | Valores sugeridos (`value`, `label`, `recommended`). `value: null` significa deixar a configuração de fora | | `choicesFrom` | Lista em `lists` cujos valores a configuração também aceita, ou `null` | | `custom` | `true` quando a configuração aceita valores fora de `choices`, desde que do tipo certo | | `deprecated` | Configuração obsoleta | `lists` traz as listas de valores: `locales` e `timezones` (para as opções `locale` e `timezoneId`) e as listas citadas em `choicesFrom`. Para usar, passe o id e o valor em `options.settings`: ```json { "engine": "patchright", "options": { "settings": { "context-option:viewport": { "width": 1366, "height": 768 } } } } ``` Limites de `settings`: até 256 configurações e até 65.536 caracteres de JSON no total. O valor não pode ser `null`. Fora de `choices`, textos e `enum` têm de 1 a 2048 caracteres, listas até 128 itens e objetos até 16.384 caracteres de JSON. Algumas configurações são controladas pela Veloz e voltam `fixed` ou `controlled_switch`. A opção `geolocation` e uma configuração de geolocalização não podem ir juntas. ### Opções em conectar-para-acordar `ov.connect()` e `POST /v1/connect-token` aceitam `engine`, `options`, `region` e `timeoutSec`, como uma criação: ```ts const browser = await chromium.connectOverCDP( await ov.connect({ engine: "patchright", options: { locale: "pt-BR", timezoneId: "America/Sao_Paulo" }, }), ); ``` ```bash curl -X POST https://platform.onveloz.com/api/browser/v1/connect-token \ -H "Authorization: Bearer bk_live_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "engine": "patchright", "options": { "locale": "pt-BR" } }' # → { "connectUrl": "wss://.../v1/connect?token=..." } ``` - **A checagem acontece ao gerar a URL.** Engine ou opção recusada volta `400` antes de você conectar. - **A URL carrega as opções assinadas, mas não cifradas.** Quem tem a URL consegue lê-las e abrir uma sessão na sua organização. Trate a URL como segredo e não coloque segredos em `initScripts`. - **A URL tem no máximo 8 KiB.** Acima disso, a resposta é `400` com `option: "options"` e `code: "invalid"`. Reduza as opções (`initScripts` costuma ser o maior) ou crie a sessão antes de conectar. - **O proxy fica no servidor.** Um proxy próprio (`proxyServer` e credenciais) ou salvo (`proxyId`) é guardado ao gerar a URL, que só leva uma referência a ele. Envie um ou outro, não os dois. ### Repetir com segurança (`Idempotency-Key`) `POST /v1/sessions` aceita o cabeçalho `Idempotency-Key`. Com ele, repetir a mesma criação (por exemplo, depois de um timeout de rede) devolve a sessão que já existe em vez de abrir outra. ```bash curl -X POST https://platform.onveloz.com/api/browser/v1/sessions \ -H "Authorization: Bearer bk_live_sua_chave" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-123" \ -d '{ "timeoutSec": 300 }' ``` ```ts const session = await ov.sessions.create({ timeoutSec: 300 }, { idempotencyKey: "pedido-123" }); ``` - A chave tem de 1 a 255 caracteres ASCII visíveis (sem espaço). Outro valor volta `400` com `"error": "O cabeçalho Idempotency-Key deve ter de 1 a 255 caracteres ASCII visíveis."`. - A chave vale dentro da organização. Use uma chave nova para cada sessão nova. - **Mesma chave, mesmo pedido:** a resposta traz a sessão original (`id`, `status` atual e `connectUrl: null`). Busque o `connectUrl` com `GET /v1/sessions/:id`. A repetição não conta de novo no limite de sessões simultâneas. - **Mesma chave, pedido diferente:** `409` com `"error": "Esta chave de idempotência já foi usada com uma requisição diferente."`. No SDK, `BrowserError` com `code: "browser/idempotency-conflict"`. O `Idempotency-Key` vale só na criação de sessões, não em `POST /v1/connect-token`. ### Erros Engine ou opções recusadas respondem `400` com `error` (o texto completo) e `issues` (um item por problema): ```json { "error": "O valor da opção locale não está entre os permitidos. O valor da opção timezoneId não está entre os permitidos.", "issues": [ { "option": "locale", "code": "not_allowed", "message": "O valor da opção locale não está entre os permitidos." }, { "option": "timezoneId", "code": "not_allowed", "message": "O valor da opção timezoneId não está entre os permitidos." } ] } ``` `option` é o nome da opção (`locale`), o id da configuração (`context-option:viewport`), `engine`, `proxy` ou `options` (a URL de conexão inteira). Os códigos: | Código | Quando | | ------------------- | ------------------------------------------------------------------------------- | | `unknown_engine` | O `engine` não existe no catálogo | | `unknown_option` | Opção ou configuração que o engine não conhece | | `invalid` | Valor fora do formato ou dos limites | | `not_allowed` | Valor fora da lista permitida (por exemplo, `locale` fora de `locales`) | | `unsupported` | O engine não tem a capacidade (por exemplo, `headless: true` sem modo headless) | | `fixed` | Configuração controlada pela Veloz | | `controlled_switch` | Configuração que usa uma flag do Chromium controlada pela Veloz | | `unavailable` | Engine ou opção ainda não liberada para iniciar sessões | No SDK, esse `400` vira `BrowserOptionsError` (`code: "browser/invalid-options"`), com a mesma lista em `error.issues`. Um `400` sem `issues` vem de outro campo, como o proxy ou o `Idempotency-Key`, e vira `BrowserError`. ## Configuração da sessão Os campos abaixo valem em `ov.sessions.create()` e `ov.connect()`, e no corpo JSON de `POST /v1/sessions` e `POST /v1/connect-token`. O stealth é sempre garantido (não é um campo). | Campo | Tipo | Descrição | | --------------- | ------ | ----------------------------------------------------------------------------------- | | `engine` | string | Id do engine (veja `GET /v1/engines`). Omitido, usa o engine padrão | | `options` | object | Opções do navegador, checadas contra o engine (veja **Escolher o navegador**) | | `proxyServer` | string | Seu gateway de proxy (`scheme://host:porta`: http, https ou socks5) | | `proxyUsername` | string | Usuário do seu proxy (opcional; omita para proxy autorizado por IP) | | `proxyPassword` | string | Senha do seu proxy (opcional). Criptografada em repouso; nunca retornada | | `proxyCountry` | string | País de saída do seu proxy (ISO de 2 letras, ex: `"US"`), alinha o fingerprint | | `proxyId` | string | Id de um proxy salvo (veja **Proxies salvos**), no lugar dos outros campos de proxy | | `region` | string | Região de provisionamento (servidor escolhe o padrão) | | `timeoutSec` | number | TTL máximo da sessão em segundos (limitado ao teto do seu plano) | Um `region`, `timeoutSec` ou `proxyCountry` inválido é ignorado, e a sessão segue com o padrão. Já `engine` e `options` inválidos são recusados com `400` (veja **Erros**), assim como `proxyId` junto de qualquer outro campo de proxy, mesmo inválido. ## Visualização ao vivo No dashboard, abra uma sessão para ver o console **Sessão ao vivo**: a tela do navegador transmitida em tempo real enquanto a sessão roda, útil para acompanhar automações e depurar. A mesma transmissão é o screencast CDP padrão (`Page.startScreencast`), então você também pode consumi-la a partir do seu próprio cliente CDP. ### Visualização ao vivo pela API A `liveView` devolve a URL de uma página de live view hospedada pela Veloz: uma página HTML completa, com a marca Veloz, pronta para abrir numa aba (`window.open`) ou embutir num `