vixpi.json

Descreva runtime, comandos, porta, workers e cron no próprio repositório.

Arquivo opcional na raiz do repositório (ou da subpasta configurada no serviço). Quando existe, ele tem prioridade sobre qualquer outro método de build (vixpi.json → Dockerfile → compose → Railpack → Nixpacks → templates).

O agente valida o arquivo antes de qualquer build. Se estiver inválido, o deploy falha na fase "Detecção do método de build" com o código VIXPI_JSON_INVALID, listando cada campo e o motivo. A versão que está no ar não é tocada.

Campos

Campo	Tipo	Obrigatório	Descrição
`runtime`	`php`, `node`, `bun`, `python`, `static` ou `custom`	sim	Runtime do app. `custom` exige um `Dockerfile` no repositório.
`version`	texto	não	Versão do runtime (ex.: `"22"`, `"8.4"`). Padrão: a do componente app do serviço.
`install`	texto (até 500)	não	Comando de instalação de dependências (ex.: `npm ci`).
`build`	texto (até 500)	não	Comando de build (ex.: `npm run build`).
`start`	texto (até 500)	não	Comando de start; vira o `CMD` do container. Aspas simples e duplas são respeitadas; não há expansão de shell.
`port`	inteiro de 1 a 65535	não	Porta em que o app escuta. O agente injeta `PORT` com o mesmo valor.
`healthcheck`	texto começando com `/`	não	Caminho verificado antes de trocar a versão (padrão `/`). Qualquer resposta com status abaixo de 500 conta como saudável.
`public`	texto sem `..`	não	Pasta pública (runtimes `static` e `php`).
`persistent`	lista de pastas	não	Subpastas (ex.: `["storage"]`) preservadas entre deploys no modo de arquivos montados.
`workers`	lista	não	Processos em segundo plano.
`cron`	lista	não	Tarefas agendadas.

`workers[]`

Campo	Regra
`name`	obrigatório, `^[a-z0-9-]+$`
`command`	obrigatório
`instances`	opcional, inteiro de 1 a 10

`cron[]`

Campo	Regra
`name`	obrigatório
`schedule`	obrigatório, 5 campos separados por espaço (`min hora dia mês dia-da-semana`)
`command`	obrigatório

Hoje workers e cron do arquivo são validados, mas os componentes correspondentes ainda precisam ser criados na aba Banco de dados (veja Banco de dados e Redis).

Exemplos

Node com build:

{
  "runtime": "node",
  "version": "22",
  "install": "npm ci",
  "build": "npm run build",
  "start": "node dist/server.js",
  "port": 3000,
  "healthcheck": "/saude"
}

PHP/Laravel com worker de fila e cron:

{
  "runtime": "php",
  "version": "8.4",
  "install": "composer install --no-dev --optimize-autoloader",
  "workers": [{ "name": "fila", "command": "php artisan queue:work --tries=3" }],
  "cron": [{ "name": "agenda", "schedule": "* * * * *", "command": "php artisan schedule:run" }]
}

Site estático:

{ "runtime": "static", "public": "dist" }

Mensagens de erro

Cada erro aponta o campo e o motivo, por exemplo:

runtime é obrigatório
port deve ser um inteiro entre 1 e 65535
healthcheck deve começar com /
workers[0].name deve corresponder a /^[a-z0-9-]+$/
cron[1].schedule deve ter 5 campos separados por espaço

Corrija o arquivo, faça o commit e publique de novo. Veja o fluxo completo em Git e GitHub Actions.