Pular para o conteúdo

O aiuby.toml por dentro, campo a campo

Equipe AIUBYRevisado em 16 nov 2026

aiuby.toml + CLI aiuby + revisões

Toda aplicação do AIUBY Compute nasce de um arquivo: o aiuby.toml. Ele diz qual imagem roda, em que porta, com que hardware e com quantas réplicas. Este texto percorre cada campo, com a regra que o contrato aplica, e separa três coisas que costumam se confundir: o que a CLI valida no seu computador, o que só a API decide e o que o arquivo descreve mas a plataforma ainda não executa.

#Um arquivo de exemplo

Este é o arquivo do template fastapi-http, como a CLI copia com aiuby init:

aiuby.toml
name = "Minha API"
slug = "minha-api"

[config]
runtime = "container"
image = "REGISTRO/minha-api:1"
port = 8080

[config.hardware]
provider = "any"
cpu = 1
memoryMb = 512

[config.scaling]
minReplicas = 0
maxReplicas = 2

Guarde o maxReplicas = 2: ele volta no fim do texto.

#Nome e identificador

  • name é o nome exibido, com até 120 caracteres.
  • slug é o identificador único no workspace, e é o que os comandos usam. De 3 a 40 caracteres: minúsculas, dígitos e hífen, começando por letra.

Os dois ficam fora de [config] de propósito. A configuração é versionada; o nome e o identificador são da aplicação, não de uma revisão.

#O que roda: imagem, porta, args e env

CampoRegra
runtimecontainer ou python. Só container é executado hoje
imageReferência da imagem, com registro e versão, sem espaços. Obrigatória com runtime container
portPorta em que a aplicação escuta, de 1 a 65535. Padrão: 8080
argsArgumentos do processo da imagem. Até 30. Vazio: vale o que a imagem define
envVariáveis de ambiente. Até 50, com nome em maiúsculas, dígitos e sublinhado

args substitui o comando padrão da imagem (o CMD). É o que permite usar uma imagem de terceiros sem reconstruir: o template vllm-openai usa a imagem oficial do vLLM e escolhe o modelo assim.

aiuby.toml
[config]
runtime = "container"
image = "docker.io/vllm/vllm-openai:latest"
args = ["--model", "microsoft/Phi-3-mini-4k-instruct", "--host", "0.0.0.0", "--port", "8080", "--max-model-len", "4096"]
port = 8080

[config.env]
HF_HOME = "/tmp/hf"

Em env, alguns nomes são reservados pela plataforma e recusados, como PORT: a porta se define em port.

Atenção

Não ponha segredo em env. As variáveis ficam na configuração, gravadas em cada revisão e visíveis a quem vê a aplicação. Servem para ajuste (um caminho, um nível de log), não para senha, chave ou token. Para isso use os Segredos, na tela da aplicação: ficam cifrados e chegam à aplicação como variável de ambiente.

#Hardware e escala

O hardware é pedido por réplica, em [config.hardware]:

  • provider: any, gcp ou aws. Com any, que é o padrão, o planejador escolhe entre os provedores habilitados.
  • cpu: número de vCPUs, de 0,25 a 96.
  • memoryMb: memória em MB, inteiro, a partir de 256.
  • gpu: uma tabela própria, com o código da placa e a quantidade. Sem ela, a aplicação é só CPU.
aiuby.toml
[config.hardware]
provider = "gcp"
cpu = 4
memoryMb = 16384

[config.hardware.gpu]
sku = "gcp-cloudrun-l4"
count = 1

Com GPU, cpu e memoryMb deixam de ser escolha: cada placa só sobe com a máquina exata dela (a NVIDIA L4, com 4 vCPU e 16 GB).

Em [config.scaling], minReplicas igual a 0 permite escalar a zero, e maxReplicas vale no mínimo 1. O mínimo não pode passar do máximo.

#O que é validado e por quem

aiuby config validate lê o arquivo e aplica o mesmo contrato da API, sem usar a rede. Ele pega erro de sintaxe, campo fora da faixa, identificador malformado e campo desconhecido. Campo desconhecido é recusado, não ignorado: um memoryMB digitado errado não passa em silêncio. Arquivo inválido sai com o código 5.

terminal
aiuby config validate
aiuby config validate outro.toml

A validação local é conveniência. Quem decide é a API, e há perguntas que só ela responde:

  • O identificador já existe no workspace?
  • O workspace ainda tem vaga? São até 50 aplicações, com até 200 revisões cada.
  • A chave tem os escopos para cadastrar?
  • A configuração é implantável para a sua organização, hoje? Isso é o plano, que você lê com aiuby deploy --dry-run.

Arquivo válido, portanto, não é promessa de implantação. É só um arquivo bem formado.

#Revisões imutáveis

aiuby apps create cadastra a aplicação com a revisão r1. Dali em diante, cada mudança gravada com aiuby apps update vira uma revisão nova. As anteriores não mudam.

  • A aplicação é encontrada pelo slug do arquivo. Trocar o slug não renomeia: aponta para outra aplicação.
  • Sem mudança na configuração, nenhuma revisão é criada.
  • apps update não altera o nome. Se o name do arquivo difere do cadastrado, a CLI avisa e segue.
  • Gravar uma revisão não implanta. Implantar pega a revisão atual, e reimplantar troca a revisão no mesmo endereço.

#O que o arquivo aceita e a plataforma ainda não executa

O contrato é mais largo do que o runtime, de propósito: o arquivo descreve a intenção, e o plano diz o que dá para fazer com ela. A configuração fora do limite é cadastrada, o plano mostra o bloqueio e a implantação é recusada.

Limite

O maxReplicas = 2 do exemplo é um desses casos. O arquivo é válido e a aplicação é cadastrada, mas a prévia do runtime aceita uma réplica: para implantar lá, troque por 1. A implantação paga em CPU aceita até 3.
  • runtime = "python": build a partir do código é planejado. Hoje o plano bloqueia e pede uma imagem de contêiner.
  • provider = "aws": o valor é aceito, mas a implantação hoje acontece no Google Cloud.
  • CPU e memória grandes: o contrato vai até 96 vCPUs, mas a prévia aceita até 1 vCPU e 1 GB, e a implantação paga em CPU exige que a configuração case com um dos tamanhos de Cobrança.
  • GPU: o contrato aceita até 8 placas por réplica. A plataforma executa uma, na máquina exata dela, na implantação paga, cobrada por minuto, ou na prévia.
  • Mais de três réplicas, volumes e domínios próprios ainda não existem.

A tabela resumida dos campos está na referência do aiuby.toml, e os limites da prévia em Compute, na documentação.