# railway.toml, campo a campo: no que cada ajuste se transforma ao passar para serviços separados

Um railway.toml ou railway.json declara o build e o deploy de um serviço. Veja no que cada campo se transforma.

Canonical URL: https://unbroker.cloud/pt/blog/railway-toml-to-services
Published: 2026-11-16
Reviewed: 2026-11-16
Author: Timoteo Borgobello

## A resposta curta

Um `railway.toml`, ou os mesmos ajustes num `railway.json`, declara o build e o deploy de um serviço do Railway. O que está no arquivo substitui o painel. Numa plataforma de serviços separados, o builder vira um Dockerfile ou uma receita de framework, `startCommand` sobe o contêiner, `preDeployCommand` vira o passo de migração, `healthcheckPath` vira o health check HTTP, `cronSchedule` vira um job agendado ou um worker, `numReplicas` dentro de uma região vira a quantidade de réplicas, e `environments.<name>` substitui o build e o deploy daquele ambiente.

A configuração do Railway como código foi descontinuada. Os `railway.toml` e `railway.json` que já existem continuam valendo, nos serviços que já os usam, até 2026-12-01. Um serviço novo não pode optar por esse sistema.

Este texto não copia preços do Railway. A diferença de medidor está em [cobrança por uso ou capacidade](https://unbroker.cloud/pt/blog/usage-vs-capacity-billing). As tarifas publicadas continuam em [preços do Railway](https://unbroker.cloud/pt/comparar/precos-railway). [Railway e Render](https://unbroker.cloud/compare/railway-vs-render) é o lado a lado com o Render. Se você já decidiu mover um serviço, comece em [levar um serviço do Railway para a Unbroker](https://unbroker.cloud/pt/migrar/railway) e no [guia de migração](https://docs.unbroker.cloud/guides/migrate-from-railway). A comparação está na [página do Railway](https://unbroker.cloud/pt/alternativas/railway).

## O que railway.toml e railway.json declaram

Por padrão o Railway procura `railway.toml` ou `railway.json`. Tudo o que está nas seções de build e de deploy dos ajustes do serviço pode ser declarado ali. O Railway junta os valores do arquivo com os do painel para o deployment. O painel não é atualizado. O que está definido em código sempre substitui os valores do painel. A fonte desta seção é a [referência de Config as Code](https://docs.railway.com/reference/config-as-code).

TOML e JSON são preferência. O comportamento é o mesmo. O schema JSON é [railway.schema.json](https://railway.com/railway.schema.json).

O caminho do arquivo pode ser trocado nos ajustes do serviço. É um caminho absoluto, por exemplo `/backend/railway.toml`. O arquivo de config não segue o Root Directory.

Estas chaves são formatos dessa referência, não um app de exemplo e não um arquivo completo:

```toml
[build]
builder = "RAILPACK"
buildCommand = "npm run build"
dockerfilePath = "Dockerfile.api"
watchPatterns = ["src/**"]

[deploy]
startCommand = "npm start"
preDeployCommand = ["npm run db:migrate"]
healthcheckPath = "/health"
healthcheckTimeout = 300
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10
cronSchedule = "*/15 * * * *"
```

`numReplicas` não é um campo de primeiro nível nessa referência. Ele aparece dentro de `deploy.multiRegionConfig`, por região, por exemplo `"us-west2": { "numReplicas": 2 }`. Também existem `build.railpackVersion`, `deploy.overlapSeconds` e `deploy.drainingSeconds`. Os dois últimos são o encerramento do deployment.

## O que mudou: de Config as Code para Infrastructure as Code

A [referência de Config as Code](https://docs.railway.com/reference/config-as-code) mostra este banner:

> Config as Code is deprecated. Prefer Infrastructure as Code. Existing files keep working for legacy services until 2026-12-01; migrate with the guide in Infrastructure as Code.

A [página de config as code](https://docs.railway.com/config-as-code) detalha o alcance dessa data. Os `railway.json` e `railway.toml` existentes continuam funcionando nos serviços que já os usam, até 2026-12-01. Essa data é um corte duro. Serviços novos não podem optar por Config as Code.

A substituição é [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code). O arquivo `.railway/railway.ts` está em disponibilidade geral. `.railway/railway.py` e `.railway/railway.go` estão em beta. Você gerencia com a CLI do Railway: `railway config init`, `railway config pull`, `railway config plan` e `railway config apply`.

`railway config migrate` é um preview. `railway config migrate --apply` grava o arquivo e limpa os ajustes de Railway Config File. `--delete-files` apaga, se você pedir, os arquivos antigos de config as code. Um serviço não pode ser gerenciado pelos dois sistemas ao mesmo tempo.

O alcance não é o mesmo. Config as code cobre o deployment de um serviço. Infrastructure as code cobre um projeto e um ambiente.

## Ajustes de build

`build.builder` vale `RAILPACK` ou `DOCKERFILE`. `RAILPACK` é o padrão. Esses valores vêm da [referência de Config as Code](https://docs.railway.com/reference/config-as-code), que diz: "Railway will always build with a Dockerfile if it finds one."

O caminho de Railpack para Dockerfile é `builder = "DOCKERFILE"`, ou um Dockerfile no repositório que o Railway encontra sozinho. `build.dockerfilePath` é o lugar de um Dockerfile que não está no caminho usual. `build.buildCommand` é o comando de build passado ao builder. `build.railpackVersion` existe. Este texto não lista os valores aceitos.

`build.watchPatterns` é uma lista de padrões que disparam o deploy só em alguns casos. Os padrões são no estilo gitignore. O Railpack e esses watch paths estão descritos em [build configuration](https://docs.railway.com/builds/build-configuration). O exemplo é `["src/**"]`.

O Railway injeta `PORT`. Builds com Dockerfile precisam declarar `ARG` para usar variáveis do Railway no build. Esse padrão de `ARG` não viaja igual. A seção da outra plataforma diz o que fazer com um token.

## Ajustes de deploy

`deploy.startCommand` é o comando que roda quando o contêiner sobe.

O healthcheck path do Railway é `deploy.healthcheckPath`, por exemplo `"/health"`. `deploy.healthcheckTimeout` é em segundos. O padrão é 300. O Railway consulta o endpoint até receber um 2xx, e só então ativa o deployment novo. Ele não continua olhando o endpoint depois que o deploy está no ar. A fonte é [Healthchecks](https://docs.railway.com/deployments/healthchecks).

`deploy.restartPolicyType` vale `ON_FAILURE`, `ALWAYS` ou `NEVER`. `deploy.restartPolicyMaxRetries` limita as tentativas. O padrão é On Failure com no máximo 10. A fonte é [Restart policy](https://docs.railway.com/deployments/restart-policy).

Nesta referência as réplicas são por região. `numReplicas` fica dentro de `deploy.multiRegionConfig` para uma região, como em `"us-west2": { "numReplicas": 2 }`. Não existe um `numReplicas` de primeiro nível para copiar.

`deploy.overlapSeconds` e `deploy.drainingSeconds` existem. Eles pertencem ao encerramento do deployment. Este texto não atribui a eles um controle no destino.

## preDeployCommand e as migrações

O comando do Railway antes do deploy é `deploy.preDeployCommand`. O exemplo da referência é `["npm run db:migrate"]`. Ele roda entre o build e o deploy, num contêiner separado. Esse contêiner pode ler as variáveis do app e usar a rede privada. Volumes não são montados. Mudanças de disco não são gravadas. Se o comando falha, o Railway não tenta de novo e o deployment não segue. Não há limite de tempo por padrão. Os ajustes podem incluir um Pre-deploy Timeout de 1 a 3600 segundos. A fonte é [Pre-deploy command](https://docs.railway.com/deployments/pre-deploy-command).

Em outra plataforma, deixe isso como um único comando de migração. Não coloque no build da imagem e não rode na subida de cada réplica. Como a migração precisa se comportar quando você volta o código está em [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy).

## cronSchedule e os workers

O cron do Railway é `deploy.cronSchedule`. É uma expressão crontab, por exemplo `"*/15 * * * *"`. Os horários estão em UTC. As execuções precisam ter pelo menos 5 minutos de intervalo. O serviço precisa sair quando o trabalho termina. Se a execução anterior ainda está ativa, a próxima é pulada. A fonte é [Cron jobs](https://docs.railway.com/cron-jobs).

Isso é um processo que começa e sai. Um processo que fica no ar esperando uma fila é um worker, não uma linha de cron. Depois da mudança são serviços diferentes. A divisão operacional está em [Workers e tarefas cron](https://unbroker.cloud/pt/blog/background-workers-cron-jobs).

## Overrides por ambiente e variáveis

`environments.<name>` substitui os ajustes de build e de deploy daquele ambiente. O nome especial é `pr`, para deployments de PR. A prioridade é fixa: config daquele ambiente em código, depois a config base em código, depois os ajustes do serviço.

As variáveis não fazem parte do arquivo. Liste-as à parte, em Variables do serviço. O Railway também injeta `PORT`. Um Dockerfile que precisa de uma variável do Railway no build tem que declarar `ARG`. Como o escopo funciona quando esses valores já são variáveis de ambiente comuns está em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets).

Um repositório que descreve vários processos num único arquivo Compose é outro inventário. Esse mapa está em [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production). Um blueprint do Render em render.yaml é outro inventário. O mapa de cada campo está em [render.yaml, campo a campo](https://unbroker.cloud/pt/blog/render-yaml-to-services).

## railway.toml, campo a campo

| Campo do railway.toml | No que se transforma |
| --- | --- |
| `build.builder = "RAILPACK"` | Um build de framework. Railpack é o padrão. |
| `build.builder = "DOCKERFILE"`, ou um Dockerfile que o Railway encontra | Um build com Dockerfile. O Railway sempre constrói com um Dockerfile se encontra um. |
| `build.buildCommand` | O comando de build da receita escolhida, ou o mesmo comando escrito no Dockerfile. |
| `build.dockerfilePath` | O caminho de um Dockerfile que não está no lugar padrão. |
| `build.watchPatterns` | Watch paths. Uma mudança só faz deploy se um padrão da lista casa. No Railway os padrões são no estilo gitignore. |
| `build.railpackVersion` | Um pin de versão do Railpack no Railway. Este texto não lista valores aceitos e não inventa um campo de destino. |
| `deploy.startCommand` | O comando que sobe o contêiner. |
| `deploy.preDeployCommand` | Um comando de migração entre o build e o deploy, no próprio contêiner, não na subida de cada réplica. |
| `deploy.healthcheckPath` | Um caminho HTTP que precisa devolver 2xx antes de o deployment novo ficar ativo. |
| `deploy.healthcheckTimeout` | Quanto esse check pode esperar, em segundos. O padrão do Railway é 300. O check para quando o deploy já está ativo. |
| `deploy.restartPolicyType` | `ON_FAILURE`, `ALWAYS` ou `NEVER`. O padrão é On Failure. |
| `deploy.restartPolicyMaxRetries` | O teto de tentativas. O padrão com On Failure é 10. |
| `deploy.multiRegionConfig.<region>.numReplicas` | A quantidade de réplicas daquela região, por exemplo `"us-west2": { "numReplicas": 2 }`. Não é um `numReplicas` de primeiro nível. |
| `deploy.cronSchedule` | Uma execução agendada em UTC. O processo sai. As execuções têm pelo menos 5 minutos de intervalo, e se uma ainda está ativa a próxima é pulada. |
| `deploy.overlapSeconds` e `deploy.drainingSeconds` | O encerramento do deployment. Copie só onde o destino documentar os mesmos controles. |
| `environments.<name>`, inclusive `pr` | Overrides de um ambiente. O código daquele ambiente ganha do arquivo base, e o arquivo base ganha do painel. |

## Como funciona na Unbroker

<aside class="plan-box">
<p><strong>Na Unbroker.</strong> railway.toml não é um formato de importação. Você traduz cada campo na mão, para os ajustes do serviço ou para <code>.unbroker/unbroker.ts</code>. O guia de migração exige uma organização Pro. Builds de Dockerfile, workers, comandos de migração, jobs agendados, comandos avulsos, health checks avançados, previews de PR, volumes persistentes e réplicas configuráveis exigem Pro.</p>
</aside>

[O guia de migração](https://docs.unbroker.cloud/guides/migrate-from-railway) diz: "Do not assume platform configuration files or service-reference expressions are portable to another provider." Faça o inventário da revisão de código, dos comandos de build e de subida, da região, das variáveis, do armazenamento, dos domínios e das dependências de cada serviço, inclusive workers e tarefas agendadas.

A tabela desse guia é curta. Comandos de build e de subida: revise a receita escolhida, ou escreva-os no Dockerfile. Variáveis secretas e de referência: recrie variáveis com escopo e as referências de conexão do destino. Arquivos persistentes: um volume de destino. Não copie hostnames internos do Railway. Não leve o padrão de `ARG` que carrega um token. A Unbroker expõe `NODE_AUTH_TOKEN` ou `GITHUB_TOKEN` como segredo do BuildKit.

[Tipos de serviço](https://docs.unbroker.cloud/apps/services) é onde o builder cai. Um serviço de repositório constrói projetos de servidor com Railpack, sozinho. Não precisa de `railpack.json`. Um Dockerfile do repositório dá controle explícito do build. Um serviço de imagem roda uma imagem que você já construiu. Um upload estático serve arquivos sem processo de servidor. Um worker não tem HTTP de entrada. Serve para filas, processamento agendado e trabalhos async. Builds de Dockerfile e workers exigem Pro.

Watch paths existem, e não são gitignore. [Deploy from Git](https://docs.unbroker.cloud/deployments/git) diz para definir Watch paths em Build & deploy ao criar um serviço de repositório, ou nos ajustes de Source do serviço. Um padrão por linha, relativo à raiz do repositório. Os padrões são `*`, `?` e `**`. Exclusões não são suportadas. O campo da API é `watchPaths`. Uma entrada de `watchPatterns` do Railway que começa com `!` não tem para onde ir. Liste os paths que você quer e deixe as negações de fora.

[Deployments](https://docs.unbroker.cloud/deployments/overview) leva uma revisão por Queued, Building, Deploying e Live. Um health check que falha impede tratar uma revisão doente como live. Health checks avançados exigem Pro. Este texto não documenta um equivalente de restart policy para `ON_FAILURE`, `ALWAYS` ou `NEVER`, nem equivalentes de `overlapSeconds` ou `drainingSeconds`.

Serviços de repositório e de upload podem rodar várias réplicas, como quantidade fixa ou como autoscale por CPU e memória. Serviços de imagem, workers e qualquer serviço com volume persistente rodam uma réplica. Na célula compartilhada um serviço pode rodar até 3 réplicas. Réplicas configuráveis exigem Pro. O Free roda uma réplica. Não há um bloco documentado de réplicas multi-região. O `numReplicas` de `multiRegionConfig` vira uma quantidade de réplicas daquele serviço, ou fica como um dado que você anota e não finge importar.

Existem comandos pre-deploy e post-deploy. Eles compartilham o isolamento de ambiente do serviço e alcançam os bancos privados dele. Comandos de migração exigem Pro. O passo de migração está em [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy).

O arquivo de infraestrutura como código da Unbroker é `.unbroker/unbroker.ts`, ou `.unbroker/unbroker.go`, ou `.unbroker/unbroker.py`. Os comandos são `ubctl config init`, e depois plan e apply. [Infrastructure as code](https://docs.unbroker.cloud/cli/infrastructure-as-code) diz que `@unbroker/iac` v0.2.0 mapeia `preDeploy`. Post-deploy ainda não está no schema. Os campos de serviço que essa página mostra incluem `source`, `start`, `replicas` e `env`. Mudar comandos, o health check ou as réplicas dispara um deploy no apply. É um arquivo diferente de `.railway/railway.ts`. Nada converte um no outro.

Um worker é o serviço sem HTTP de entrada. Jobs agendados exigem Pro. Este texto não descreve uma expressão cron nem uma tela de jobs da Unbroker. Use [Workers e tarefas cron](https://unbroker.cloud/pt/blog/background-workers-cron-jobs) para a diferença entre um processo que fica no ar e um comando que sai.

[Variáveis de ambiente](https://docs.unbroker.cloud/deployments/environment-variables) têm escopo Production, Preview ou All. Um valor de um ambiente substitui All. Uma variável do serviço substitui uma variável compartilhada do projeto com a mesma chave. Previews de PR exigem Pro. Eles copiam os valores All e Preview, e nunca copiam Production. Antes de adotar a infraestrutura como código da Unbroker, variáveis com escopo só de production ou de preview precisam passar para valores de todo o ambiente. Como esses escopos se comportam num preview está em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets).

O Free é $0. É um projeto, dois serviços no total e três pedidos de deploy por dia UTC. Cada serviço Free roda uma réplica, até 250m de CPU e 256 MiB, e dorme quando está ocioso. O Pro custa $25 por mês, com $25 de crédito de uso por ciclo de cobrança. O crédito não acumula. Esses termos estão em [preços](https://unbroker.cloud/pt/precos) e em [Plans](https://docs.unbroker.cloud/billing/plans).

## Lista antes de passar o serviço

1. Leia o banner. Config as code foi descontinuado. Os `railway.toml` e `railway.json` existentes continuam valendo, nos serviços que já os usam, até 2026-12-01. Serviços novos não podem optar.
2. Anote qual arquivo o Railway realmente lê, inclusive um caminho absoluto próprio. O arquivo não segue o Root Directory.
3. Anote `builder`, `buildCommand`, `dockerfilePath` e `watchPatterns`. Uma negação de gitignore não sobrevive como watch path da Unbroker.
4. Anote `startCommand`, `healthcheckPath`, `healthcheckTimeout` e a restart policy. A Unbroker não documenta equivalentes de `restartPolicyType`, `overlapSeconds` ou `drainingSeconds`.
5. Tire `preDeployCommand` do build da imagem e da subida de cada réplica. No Railway uma falha não é tentada de novo e o deployment não segue.
6. Trate `cronSchedule` como um job que sai, em UTC, com pelo menos 5 minutos de intervalo. Um processo que fica no ar é um worker.
7. Copie `numReplicas` de `deploy.multiRegionConfig`, por região. Não procure um `numReplicas` de primeiro nível.
8. Liste os overrides de ambiente, inclusive `pr`, e cada variável. Não copie hostnames internos do Railway. Não leve um token em `ARG`.
9. Traduza o arquivo na mão. Não é um formato de importação. Na Unbroker o destino são os ajustes do serviço ou `.unbroker/unbroker.ts`.
10. Confira o plano. Builds de Dockerfile, workers, comandos de migração, jobs agendados, comandos avulsos, health checks avançados, previews de PR, volumes e réplicas configuráveis exigem Pro. O guia de migração exige uma organização Pro.

## Perguntas frequentes

### Para que serve o railway.toml?

É a configuração do Railway como código de um serviço. Por padrão o Railway procura railway.toml ou railway.json. Dá para declarar ali tudo o que está nas seções de build e de deploy desse serviço. O Railway junta o arquivo com os ajustes do painel para o deployment. O painel não é atualizado, e o que está definido em código sempre substitui os valores do painel. A fonte é a [referência de Config as Code](https://docs.railway.com/reference/config-as-code).

### A configuração do Railway como código foi descontinuada, e até quando os arquivos railway.toml funcionam?

Sim. O banner da referência diz que Config as Code está deprecated e que o caminho é Infrastructure as Code. A [página de config as code](https://docs.railway.com/config-as-code) diz que os railway.json e railway.toml que já existem continuam valendo, nos serviços que já os usam, até 2026-12-01. Essa data é um corte duro. Serviços novos não podem optar por Config as Code. A substituição é [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code).

### Qual é a diferença entre railway.toml e railway.json?

Só o formato. A referência diz que TOML e JSON se comportam igual. O schema JSON está em [railway.schema.json](https://railway.com/railway.schema.json). Nos ajustes do serviço dá para fixar outro caminho, absoluto, por exemplo /backend/railway.toml. Esse arquivo não segue o Root Directory.

### O railway.toml substitui o que está no painel?

Sim. O Railway junta os valores do arquivo com os do painel para o deployment, e não grava esses valores de volta no painel. O que está em código sempre substitui o painel. Dentro do arquivo, o bloco de um ambiente ganha da config base em código, e a config base em código ganha dos ajustes do serviço. A fonte é a [referência de Config as Code](https://docs.railway.com/reference/config-as-code).

### Como rodar migrações antes do deploy fora do Railway (preDeployCommand)?

No Railway, o comando antes do deploy é deploy.preDeployCommand. O exemplo da documentação é `npm run db:migrate`. Ele roda entre o build e o deploy, num contêiner separado, com as variáveis do app e a rede privada. Volumes não são montados, mudanças de disco não são gravadas, uma falha não é tentada de novo e o deployment não segue. Não há limite de tempo por padrão. Nos ajustes dá para colocar um Pre-deploy Timeout de 1 a 3600 segundos. A fonte é [Pre-deploy command](https://docs.railway.com/deployments/pre-deploy-command). Fora do Railway, esse passo é um comando de migração: não entra no build da imagem e não entra na subida de cada réplica. Na Unbroker existem comandos pre-deploy. Eles compartilham o isolamento de ambiente do serviço e alcançam os bancos privados dele. Comandos de migração exigem Pro. Infraestrutura como código mapeia preDeploy. Como deixar a migração segura num rollback está em [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy).

### O que substitui o cronSchedule do Railway em outra plataforma?

deploy.cronSchedule é uma expressão crontab, por exemplo `*/15 * * * *`. Os horários estão em UTC, as execuções precisam ter pelo menos 5 minutos de intervalo, o serviço precisa sair ao terminar, e se a execução anterior ainda está ativa a próxima é pulada. A fonte é [Cron jobs](https://docs.railway.com/cron-jobs). Em outra plataforma isso vira um job agendado que começa, roda e sai, ou um worker que fica no ar e não recebe HTTP. Na Unbroker, jobs agendados e workers exigem Pro. Este texto não descreve a sintaxe de horário da Unbroker. A diferença entre um worker e um job está em [Workers e tarefas cron](https://unbroker.cloud/pt/blog/background-workers-cron-jobs).

## Related reading

- [Levar um serviço do Railway para a Unbroker](https://unbroker.cloud/pt/migrar/railway)
- [Alternativa ao Railway](https://unbroker.cloud/pt/alternativas/railway)
- [Preços do Railway, explicados](https://unbroker.cloud/pt/comparar/precos-railway)
- [Railway e Render](https://unbroker.cloud/compare/railway-vs-render)
- [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy)
- [Workers e tarefas cron](https://unbroker.cloud/pt/blog/background-workers-cron-jobs)
- [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets)
- [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production)
- [render.yaml, campo a campo](https://unbroker.cloud/pt/blog/render-yaml-to-services)
- [Cobrança por uso ou capacidade](https://unbroker.cloud/pt/blog/usage-vs-capacity-billing)
- [Preços](https://unbroker.cloud/pt/precos)
