Documentação

Do nada
a uma aplicação no ar.

Este guia percorre o caminho inteiro com comandos reais. Cada bloco é copiável e funciona na ordem em que aparece.

1. Instalar a CLI

Baixe o binário do seu sistema em /downloads, confira o checksum e coloque no PATH:

# macOS (Apple Silicon) — os demais sistemas estão em /downloads
curl -fsSLO https://zero.nnumbers.com.br/downloads/zero-darwin-arm64.tar.gz
curl -fsSLO https://zero.nnumbers.com.br/downloads/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing
tar -xzf zero-darwin-arm64.tar.gz
sudo mv zero /usr/local/bin/
zero version

2. Autenticar

zero auth login

O login abre a autenticação da plataforma e guarda a credencial localmente. zero auth status mostra quem você é; zero auth logout descarta a credencial. Se sua conta participa de mais de uma organização:

zero orgs list
zero orgs use <organização>

3. Criar um projeto

zero projects create loja

O comando imprime só o identificador do projeto — de propósito, para encadear em scripts. O ambiente inicial nasce junto com o projeto.

4. Criar o serviço

Antes, diga de onde o projeto publica. A origem é atributo do projeto, e não do serviço: todos os serviços de um projeto publicam do mesmo repositório, e é isso que deixa a pergunta “de onde este projeto publica?” ter uma resposta só.

zero source set loja \
  --repo https://github.com/voce/loja.git

Depois, crie o serviço dentro de um ambiente. O ambiente é a fronteira de isolamento, e o projeto já nasceu com um:

zero environments list loja
zero services create web --env env_...

Criar não publica — e a CLI diz isso. Num monorepo, --subdir diz qual pasta este serviço constrói.

5. Publicar

zero deploy web

O build acontece na plataforma, a partir do commit — você acompanha cada etapa ao vivo: build, verificação do artefato, endereço, TLS, instâncias no ar. Ao final, a URL da aplicação. --detach devolve o controle imediatamente; zero logs <deployment> --build mostra a saída do build.

6. Operar

zero status loja        # o retrato: ambientes, serviços, o que está no ar
zero logs --follow      # a saída da aplicação, ao vivo
zero releases web       # o histórico imutável de ativações

7. Domínio próprio

Cadastre o domínio no console, em Domínios, e aponte um CNAME do seu DNS para o endereço indicado. O certificado é emitido e renovado automaticamente — um registro DNS, nenhum formulário de certificado.

8. Variáveis e secrets

No console, em Variáveis e Secrets, por organização, projeto ou ambiente — o escopo mais específico vence. Secrets nunca são exibidos depois de escritos: o valor é aplicado à aplicação, não devolvido à tela.

9. Escalar

Em Escala e disponibilidade, no console: o número de instâncias, ou o autoscaling com mínimo, máximo e alvo de uso de CPU. As instâncias se distribuem entre máquinas diferentes automaticamente — isso não é uma opção a ligar, é o comportamento de toda aplicação publicada — e manutenções drenam uma instância por vez, nunca todas juntas.

O alcance exato da proteção, para quem desenha arquitetura: a distribuição protege contra a falha de uma máquina. Ela não protege contra a perda da zona — as máquinas da instalação atual vivem numa única zona de disponibilidade. O mesmo aviso está na tela de escala do console.

10. Promover entre ambientes

zero promote web-prod --from web-preview

A promoção leva o artefato exato que estava ativo na origem — nada é reconstruído no caminho. zero artifacts web-preview lista as versões já construídas, com o digest de cada uma; --release e --artifact promovem uma versão específica.

SDKs

Os dois SDKs são gerados do mesmo contrato da API e distribuídos em /downloads. Os exemplos abaixo foram executados de verdade contra os pacotes publicados.

TypeScript

npm install ./zero-sdk-typescript.tgz

import { ZeroClient } from '@nnumbers/zero';

const zero = new ZeroClient({
  baseUrl: 'https://api.zero.nnumbers.com.br',
  token: process.env.ZERO_TOKEN,
});

// publicar, com chave de idempotência — repetir nunca duplica
const publicacao = await zero.createDeployment(servico, {},
  { idempotencyKey: crypto.randomUUID() });

Go

O namespace da plataforma não resolve por go get — por decisão de arquitetura, o SDK é vendorizado por cópia, exatamente como a CLI e o próprio MCP o consomem:

tar -xzf zero-sdk-go.tar.gz -C internal/

import "suaempresa.com/app/internal/zero"

cliente, err := zero.New(zero.Config{
    BaseURL: "https://api.zero.nnumbers.com.br",
    Token:   zero.StaticToken(os.Getenv("ZERO_TOKEN")),
})

Agentes de IA (MCP)

O zero-mcp — em /downloads — expõe as operações da API como ferramentas para qualquer agente que fale MCP. Ele nasce do contrato: não existe ferramenta que não seja uma operação da API pública.

A credencial é a mesma da CLI — o token que você usou no zero auth login — e vai por variável de ambiente, nunca por argumento:

{
  "mcpServers": {
    "zero": {
      "command": "/usr/local/bin/zero-mcp",
      "args": ["--org", "org_01…"],
      "env": {
        "ZERO_API_BASE_URL": "https://api.zero.nnumbers.com.br",
        "ZERO_TOKEN": "…"
      }
    }
  }
}

Os três modos de permissão são a parte que importa: um servidor MCP roda ao lado de um agente com a credencial de alguém, e o modo seguro é o que não muda nada.

Modo	Ferramentas	O que libera
(nenhuma flag)	67	só leitura. O padrão.
`--permitir-mutacao`	112	criar, alterar, publicar, escalar
`--permitir-mutacao --permitir-destrutiva`	119	apagar, cancelar, reverter

A API

Tudo acima existe como operação na API pública — contrato completo em /openapi.yaml, com 127 operações ativas. Mutações aceitam chave de idempotência e devolvem operações acompanháveis, inclusive por SSE. Os SDKs de TypeScript e Go e o servidor MCP para agentes derivam do mesmo contrato.

Quando algo dá errado

Sintoma	O que olhar
O build falhou	`zero logs <deployment> --build` — a saída completa do build, incluindo a linha que falhou.
Publicou mas não responde	`zero status <projeto>` — o estado por serviço diz se as instâncias subiram e, quando não, por quê.
A escala não acontece	A tela de escala do console explica: alvo sem medida de uso, limite do intervalo alcançado, ou instância sem capacidade.
Preciso voltar uma versão	Restaurar, no console, ou promover a release anterior — a versão antiga continua inteira; nada é reconstruído.
Outra coisa	suporte@nnumbers.com.br — o suporte é de quem constrói a plataforma.

Do nadaa uma aplicação no ar.