Gerencie variáveis de ambiente dos seus serviços via CLI.

Listar variáveis

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:

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:

veloz env import .env

Ou sem argumento para colar interativamente:

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):

veloz env import .env --replace

Exportar variáveis

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

veloz env delete API_KEY

Interpolação de valores (`${VAR}`)

Valores de variáveis podem referenciar outras variáveis do mesmo serviço usando ${NOME_DA_VAR} — a Veloz resolve a referência no deploy, antes do container subir.

Exemplos rápidos

Alias entre naming da Veloz e do seu app:

# Seu app lê POSTGRES_URL; a Veloz injeta DATABASE_URL.
veloz env set POSTGRES_URL='${DATABASE_URL}'

Compor URL com parâmetros:

veloz env set DATABASE_URL='${POSTGRES_POOLER_URL}?sslmode=require&pgbouncer=true'

Separar uma connection string em partes:

veloz env set DB_HOST='${POSTGRES_HOST}' DB_PORT='${POSTGRES_PORT}' \
              DB_USER='${POSTGRES_USERNAME}' DB_PASS='${POSTGRES_PASSWORD}' \
              DB_NAME='${POSTGRES_DATABASE}'

Reusar um valor base:

veloz env set APP_HOST='myapp.runveloz.com'
veloz env set API_BASE='https://${APP_HOST}'
veloz env set NEXT_PUBLIC_API='${API_BASE}/v1'

O que a interpolação resolve

Dentro do mesmo serviço, ${VAR} resolve contra:

Qualquer variável que você definiu via veloz env set / veloz env import / dashboard.
Variáveis de sistema: PORT (porta do serviço, não injetada em workers) e NODE_ENV=production.
Variáveis de plataforma VELOZ_* (ver seção abaixo) — metadados sobre o deploy, Git, domínios.
Variáveis de banco gerenciado (prefixo = nome do serviço de banco em maiúsculas, - → _; banco main-db vira MAIN_DB_*):
- <PREFIXO>_DATABASE_URL, <PREFIXO>_HOST, <PREFIXO>_PORT, <PREFIXO>_USERNAME, <PREFIXO>_PASSWORD, <PREFIXO>_DATABASE
- <PREFIXO>_POOLER_URL, <PREFIXO>_POOLER_PORT — só quando o PgBouncer está ativo (Postgres apenas)
- Apelidos canônicos, injetados só quando o projeto tem exatamente um banco daquele tipo:
  - Postgres/MySQL → DATABASE_URL (pooler se ativo, senão URL direta)
  - Redis → REDIS_URL

Para referenciar outro serviço do projeto (ex: banco gerenciado), use duplo-brace:

veloz env set DATABASE_URL='${{postgres.url}}'

Propriedades disponíveis em ${{servico.propriedade}}: host, port, username, password, database, url.

Variáveis de plataforma (`VELOZ_*`)

Todo deploy recebe um conjunto de variáveis VELOZ_* com metadados sobre o serviço, projeto, deploy, Git e domínios registrados. Elas são auto-injetadas no runtime (sua var manual sempre vence — é só referenciar via ${VELOZ_*} no valor de outra var para compor).

Sempre presentes:

Variável	O que contém
`VELOZ_SERVICE_ID`	ID interno do serviço (ex: `svc_abc123`)
`VELOZ_SERVICE_NAME`	Nome do serviço (chave no `veloz.json`)
`VELOZ_SERVICE_TYPE`	`WEB`, `WORKER`, `STATIC` ou `DATABASE`
`VELOZ_PROJECT_ID`	ID do projeto
`VELOZ_PROJECT_NAME`	Nome do projeto
`VELOZ_DEPLOYMENT_ID`	ID do deploy atual
`VELOZ_DEPLOYED_AT`	Timestamp ISO do início do deploy

Presentes quando o build gerou imagem:

Variável	O que contém
`VELOZ_IMAGE_TAG`	Tag da imagem OCI gerada (útil para debugar rollback)

Presentes quando o deploy veio do Git:

Variável	O que contém
`VELOZ_GIT_COMMIT_SHA`	SHA completo do commit
`VELOZ_GIT_COMMIT_SHORT`	SHA curto (7 chars) — ideal para badges de versão
`VELOZ_GIT_COMMIT_MESSAGE`	Primeira linha da mensagem do commit
`VELOZ_GIT_BRANCH`	Nome da branch

Presentes quando o serviço tem pelo menos um domínio:

Variável	O que contém
`VELOZ_PRIMARY_DOMAIN`	Domínio principal (custom se houver, senão `*.runveloz.com`)
`VELOZ_PUBLIC_URL`	`https://<VELOZ_PRIMARY_DOMAIN>` — URL pública canônica
`VELOZ_DOMAINS`	Todos os domínios do serviço, separados por vírgula

Usos típicos:

# Badge de versão no endpoint de status
veloz env set APP_VERSION='${VELOZ_GIT_COMMIT_SHORT}'
 
# Release tagging no Sentry
veloz env set SENTRY_RELEASE='${VELOZ_PROJECT_NAME}@${VELOZ_GIT_COMMIT_SHORT}'
 
# URL canônica para OpenGraph / sitemap
veloz env set NEXT_PUBLIC_SITE_URL='${VELOZ_PUBLIC_URL}'
 
# Allowlist de CORS baseada nos domínios registrados
veloz env set ALLOWED_ORIGINS='${VELOZ_DOMAINS}'

Variáveis cujo dado de origem não existe (ex: VELOZ_GIT_BRANCH num deploy que não veio do Git) não são emitidas — assim ${VELOZ_GIT_BRANCH} passa como literal e aparece como aviso no log, em vez de resolver para string vazia.

Gerar secrets e números aleatórios em templates (`${{secret()}}`, `${{randomInt()}}`)

Em templates (apps instalados via veloz template deploy ou o catálogo de templates), valores de env vars podem conter duas expressões geradoras, resolvidas uma única vez na instalação:

# String aleatória de 32 caracteres, alfabeto base62 (a-z A-Z 0-9)
${{secret(32)}}

# String hexadecimal de 16 caracteres
${{secret(16, "0123456789abcdef")}}

# Número inteiro aleatório entre 8000 e 9000 (inclusivo)
${{randomInt(8000, 9000)}}

Regras:

secret(N) — N entre 1 e 256.
secret(N, "alfabeto") — o alfabeto não pode ser vazio; os caracteres são escolhidos uniformemente via crypto.randomBytes.
randomInt(min, max) — min precisa ser menor que max; o resultado está no intervalo fechado.
Resolvidas na hora da instalação do template — o valor gerado é persistido como env var normal. Deploys seguintes reutilizam o mesmo valor.
Hoje disponível só para templates. Em projetos comuns (via veloz env set) essas funções NÃO são executadas — o valor literal ${{secret(32)}} ficaria no env var. Para secrets em projetos comuns, gere fora (ex: openssl rand -hex 32) e salve com veloz env set.

Regras de interpolação

Referência não encontrada → passa como literal. Se ${VAR} aponta para uma variável que não existe, o valor literal ${VAR} fica no container e um aviso aparece no log do deploy. O deploy não falha.
Encadeamento funciona. A=${B}, B=${C}, C=x resolve A=x. Profundidade máxima de 10.
Ciclos são interrompidos. A=${A} ou ciclos mútuos param no loop e viram aviso.
Use $${LITERAL} para escapar. Um valor que precisa conter ${...} literal (sem interpolar) usa dois cifrões: veloz env set MSG='Preço em $${USD}' resulta em Preço em ${USD}.
Case-sensitive. ${database_url} e ${DATABASE_URL} são chaves diferentes.

Onde isto ajuda mais

Eliminar duplicação de secrets quando o naming do seu app não bate com o naming da Veloz.
Adicionar query params a uma URL de banco gerenciada sem copiar a string.
Quebrar uma URL em partes quando a biblioteca que você usa não aceita uma connection string única.

Evite interpolação para valores 100% estáticos (API keys de terceiros, flags) — passe o valor direto.

Variáveis no build (Dockerfile injection)

A Veloz injeta automaticamente todas as variáveis de ambiente no Dockerfile durante o build. Isso significa que frameworks como Next.js que precisam de variáveis em build-time (ex: NEXT_PUBLIC_API_URL) funcionam sem configuração extra.

As variáveis são injetadas como ARG no Dockerfile gerado pelo Nixpacks, disponíveis em todas as fases do build.

Segurança: variáveis sensíveis ficam apenas na camada de build e não são incluídas na imagem final. Em runtime, são injetadas via Kubernetes Secrets.

Próximos passos

Logs — Acompanhe seu app em tempo real
Configurações — Ajuste build, porta, recursos

Variáveis de Ambiente