# railway.toml, field by field: what each setting becomes when you move to separate services

A railway.toml or railway.json declares one service's build and deploy. See what each field becomes on separate services.

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

## The short answer

A `railway.toml`, or the same settings in `railway.json`, declares the build and deploy for one Railway service. Values in the file override the dashboard. On a platform of separate services, the builder becomes a Dockerfile or a framework recipe, `startCommand` starts the container, `preDeployCommand` becomes the migration step, `healthcheckPath` becomes the HTTP check, `cronSchedule` becomes a scheduled job or a worker, `numReplicas` inside a region becomes the replica count, and `environments.<name>` overrides build and deploy for that environment.

Railway config as code is deprecated. Existing `railway.toml` and `railway.json` files keep working for services that already use them until 2026-12-01. A new service cannot opt in.

This page does not quote Railway prices. The meter difference is [usage vs capacity billing](https://unbroker.cloud/blog/usage-vs-capacity-billing). Published rates stay on [Railway pricing](https://unbroker.cloud/compare/railway-pricing). [Railway vs Render](https://unbroker.cloud/compare/railway-vs-render) is the side by side with Render. If you have already decided to move a service, start at [Move a Railway service to Unbroker](https://unbroker.cloud/migrate/railway) and the [migration tutorial](https://docs.unbroker.cloud/guides/migrate-from-railway). The comparison is the [Railway page](https://unbroker.cloud/alternatives/railway).

## What railway.toml and railway.json declare

By default Railway looks for `railway.toml` or `railway.json`. Everything in the build and deploy sections of the service settings can be specified there. Railway combines file values with dashboard settings for the deployment. The dashboard is not updated. Configuration defined in code always overrides dashboard values. The source for this section is the [Config as Code reference](https://docs.railway.com/reference/config-as-code).

TOML and JSON are a preference. The behavior is the same. The JSON schema is [railway.schema.json](https://railway.com/railway.schema.json).

A custom config file path can be set in service settings. It is an absolute path, for example `/backend/railway.toml`. The config file does not follow the Root Directory.

These keys are shapes from that reference, not one sample app, and not a complete file:

```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` is not a top-level field in that reference. It appears inside `deploy.multiRegionConfig`, per region, for example `"us-west2": { "numReplicas": 2 }`. `build.railpackVersion`, `deploy.overlapSeconds`, and `deploy.drainingSeconds` also exist. The last two are deployment teardown.

## What changed: Config as Code to Infrastructure as Code

The [Config as Code reference](https://docs.railway.com/reference/config-as-code) shows this 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.

The [config as code page](https://docs.railway.com/config-as-code) adds the scope of that date. Existing `railway.json` and `railway.toml` files continue to work for services that already use them until 2026-12-01. That date is a hard cutoff. New services cannot opt into Config as Code.

The replacement is [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code). The authoring file `.railway/railway.ts` is generally available. `.railway/railway.py` and `.railway/railway.go` are beta. You manage it with the Railway CLI: `railway config init`, `railway config pull`, `railway config plan`, and `railway config apply`.

`railway config migrate` is a preview. `railway config migrate --apply` writes the file and clears the Railway Config File settings. `--delete-files` optionally deletes the old config-as-code files. A service cannot be managed by both systems at the same time.

The scopes differ. Config as code covers one service deployment. Infrastructure as code covers a project and an environment.

## Build settings

`build.builder` is `RAILPACK` or `DOCKERFILE`. `RAILPACK` is the default. Those values come from the [Config as Code reference](https://docs.railway.com/reference/config-as-code), which states: "Railway will always build with a Dockerfile if it finds one."

The railpack to dockerfile path is `builder = "DOCKERFILE"`, or a Dockerfile in the repo that Railway finds on its own. `build.dockerfilePath` is the location of a Dockerfile that is not in the standard place. `build.buildCommand` is the build command passed to the builder. `build.railpackVersion` exists. This page does not list the values it accepts.

`build.watchPatterns` is an array of patterns that conditionally trigger deploys. The patterns are gitignore-style. Railpack and these watch paths are described on the [build configuration](https://docs.railway.com/builds/build-configuration) page. The example is `["src/**"]`.

Railway injects `PORT`. Dockerfile builds must declare `ARG` to use Railway variables at build time. Do not treat that `ARG` pattern as portable. The next platform section says what to do with a token.

## Deploy settings

`deploy.startCommand` is the command that runs when the container starts.

The Railway healthcheck path is `deploy.healthcheckPath`, for example `"/health"`. `deploy.healthcheckTimeout` is in seconds. The default is 300. Railway queries the endpoint until it returns a 2xx, and only then makes the new deployment active. It does not monitor the endpoint after the deploy is live. The source is [Healthchecks](https://docs.railway.com/deployments/healthchecks).

`deploy.restartPolicyType` is `ON_FAILURE`, `ALWAYS`, or `NEVER`. `deploy.restartPolicyMaxRetries` caps the retries. The default is On Failure with a max of 10. The source is [Restart policy](https://docs.railway.com/deployments/restart-policy).

Replicas are regional in this reference. `numReplicas` sits inside `deploy.multiRegionConfig` for a region, as in `"us-west2": { "numReplicas": 2 }`. There is no top-level `numReplicas` field to copy.

`deploy.overlapSeconds` and `deploy.drainingSeconds` exist. They belong to deployment teardown. This page does not assign them a destination control.

## The Railway pre deploy command and migrations

The Railway pre deploy command is `deploy.preDeployCommand`. The reference example is `["npm run db:migrate"]`. It runs between the build and the deploy, in a separate container. That container can read the app's environment variables and can use the private network. Volumes are not mounted. Filesystem changes are not persisted. If the command fails, Railway does not retry it, and the deployment does not proceed. There is no time limit by default. Settings can add a Pre-deploy Timeout from 1 to 3600 seconds. The source is [Pre-deploy command](https://docs.railway.com/deployments/pre-deploy-command).

On another platform, keep that as one migration command. Do not fold it into the image build, and do not run it from every replica at startup. How the migration has to behave when you roll the code back is [Database migrations on deploy](https://unbroker.cloud/blog/database-migrations-on-deploy).

## cronSchedule and workers

The Railway cron schedule is `deploy.cronSchedule`. It is a crontab expression, for example `"*/15 * * * *"`. Schedules are UTC. Runs must be at least 5 minutes apart. The service must exit when the work is done. If the previous run is still active, the next run is skipped. The source is [Cron jobs](https://docs.railway.com/cron-jobs).

That is a process that starts and exits. A process that stays up and waits on a queue is a worker, not a cron line. Those are different services after the move. The operational split is [Background workers and cron jobs](https://unbroker.cloud/blog/background-workers-cron-jobs).

## Environment overrides and variables

`environments.<name>` overrides the base build and deploy settings for that environment. The special name is `pr`, for PR deployments. Priority is fixed: environment-specific config in code, then base config in code, then service settings.

Variables are not part of the file. List them from the service's Variables separately. Railway also injects `PORT`. A Dockerfile that needs a Railway variable at build time has to declare `ARG`. How scope works once the values are ordinary environment variables is [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets).

A repo that describes several processes in one Compose file is a different inventory. That map is [Docker Compose in production](https://unbroker.cloud/blog/docker-compose-to-production). A Render Blueprint in render.yaml is a different inventory. The field map is [render.yaml, field by field](https://unbroker.cloud/blog/render-yaml-to-services).

## railway.toml field by field

| railway.toml field | What it becomes |
| --- | --- |
| `build.builder = "RAILPACK"` | A framework build. Railpack is the default. |
| `build.builder = "DOCKERFILE"`, or a Dockerfile Railway finds | A Dockerfile build. Railway always builds with a Dockerfile if it finds one. |
| `build.buildCommand` | The build command on the selected recipe, or the same command encoded in the Dockerfile. |
| `build.dockerfilePath` | The path of a Dockerfile that is not in the default location. |
| `build.watchPatterns` | Watch paths. A change deploys only when a listed pattern matches. The Railway patterns are gitignore-style. |
| `build.railpackVersion` | A Railpack version pin on Railway. This page does not list accepted values, and it does not invent a destination field for it. |
| `deploy.startCommand` | The command that starts the container. |
| `deploy.preDeployCommand` | One migration command between build and deploy, in its own container, not on every replica boot. |
| `deploy.healthcheckPath` | An HTTP path that must return 2xx before the new deployment is active. |
| `deploy.healthcheckTimeout` | How long that check may wait, in seconds. The Railway default is 300. The check stops once the deploy is active. |
| `deploy.restartPolicyType` | `ON_FAILURE`, `ALWAYS`, or `NEVER`. The default is On Failure. |
| `deploy.restartPolicyMaxRetries` | The retry cap. The default with On Failure is 10. |
| `deploy.multiRegionConfig.<region>.numReplicas` | The replica count for that region, for example `"us-west2": { "numReplicas": 2 }`. Not a top-level `numReplicas`. |
| `deploy.cronSchedule` | A scheduled run in UTC. The process exits. Runs are at least 5 minutes apart, and a still-active run causes the next one to be skipped. |
| `deploy.overlapSeconds` and `deploy.drainingSeconds` | Deployment teardown. Copy them only where the destination documents the same controls. |
| `environments.<name>`, including `pr` | Overrides for one environment. Code for that environment wins over the base file, which wins over the dashboard. |

## How this works on Unbroker

<aside class="plan-box">
<p><strong>On Unbroker.</strong> railway.toml is not an import format. You translate each field by hand into service settings, or into <code>.unbroker/unbroker.ts</code>. The migration guide requires a Pro organization. Dockerfile builds, worker services, migration commands, scheduled jobs, one-off commands, advanced health checks, PR previews, persistent volumes, and configurable replicas require Pro.</p>
</aside>

[Migrate from Railway](https://docs.unbroker.cloud/guides/migrate-from-railway) says: "Do not assume platform configuration files or service-reference expressions are portable to another provider." Inventory each service's source revision, build and start commands, region, variables, storage, domains, and dependencies, including workers and scheduled tasks.

The same guide's translation is short. Build and start commands: review the selected recipe, or encode them in the Dockerfile. Secret and reference variables: recreate scoped variables and destination connection references. Persistent files: a destination volume. Do not copy internal Railway hostnames. Do not carry the token-bearing `ARG` pattern. Unbroker exposes `NODE_AUTH_TOKEN` or `GITHUB_TOKEN` as a BuildKit secret instead.

[Service types](https://docs.unbroker.cloud/apps/services) is where the builder lands. A repository service builds server projects with Railpack automatically. No `railpack.json` is required. A repository Dockerfile gives explicit build control. An image service runs an image you already built. A static upload serves files with no server process. A worker has no inbound HTTP. It is for queues, scheduled processing, and async jobs. Dockerfile builds and worker services require Pro.

Watch paths are supported, and they are not gitignore. [Deploy from Git](https://docs.unbroker.cloud/deployments/git) says to set Watch paths under Build & deploy when you create a repository service, or in the service's Source settings. One pattern per line, relative to the repo root. The patterns are `*`, `?`, and `**`. Exclusions are not supported. The API field is `watchPaths`. A Railway `watchPatterns` entry that starts with `!` has nowhere to go. List the paths you want, and leave the negations out.

[Deployments](https://docs.unbroker.cloud/deployments/overview) moves a revision through Queued, Building, Deploying, and Live. A failed health check prevents an unhealthy revision from being treated as live. Advanced health checks require Pro. This page does not document a restart-policy equivalent for `ON_FAILURE`, `ALWAYS`, or `NEVER`, and it does not document equivalents for `overlapSeconds` or `drainingSeconds`.

Repository and upload services can run several replicas, as a fixed count or as autoscale on CPU and memory. Image services, workers, and any service with a persistent volume run one replica. On the shared cell a service can run up to 3 replicas. Configurable replicas require Pro. Free runs one replica. There is no documented multi-region replica block. `numReplicas` inside `multiRegionConfig` becomes a replica count on that one service, or it stays a fact you write down and do not pretend to import.

Pre-deploy and post-deploy commands exist. They share the service's environment isolation and can reach its private databases. Migration commands require Pro. The migration step itself is [Database migrations on deploy](https://unbroker.cloud/blog/database-migrations-on-deploy).

Unbroker's own infrastructure-as-code file is `.unbroker/unbroker.ts`, or `.unbroker/unbroker.go`, or `.unbroker/unbroker.py`. The commands are `ubctl config init`, then plan and apply. [Infrastructure as code](https://docs.unbroker.cloud/cli/infrastructure-as-code) says `@unbroker/iac` v0.2.0 maps `preDeploy`. Post-deploy is not in the schema yet. The service fields that page shows include `source`, `start`, `replicas`, and `env`. Changing commands, the health check, or replicas triggers a deploy on apply. This is a different file from `.railway/railway.ts`. Nothing converts one into the other.

A worker is the service with no inbound HTTP. Scheduled jobs require Pro. This page does not describe a cron expression or a jobs screen for Unbroker. Use [Background workers and cron jobs](https://unbroker.cloud/blog/background-workers-cron-jobs) for the difference between a process that stays up and a command that exits.

[Environment variables](https://docs.unbroker.cloud/deployments/environment-variables) are scoped Production, Preview, or All. An environment-specific value overrides All. A service variable overrides a shared project variable with the same key. PR previews require Pro. They copy All and Preview values, and they never copy Production. Before you adopt Unbroker infrastructure as code, variables scoped specifically to production or preview must be migrated to environment-wide values. How those scopes behave in a preview is [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets).

Free is $0. It is one project, two services in total, and three deploy requests per UTC day. Each Free service runs one replica, up to 250m CPU and 256 MiB, and sleeps when idle. Pro is $25 a month, including $25 of usage credit per billing cycle. The credit does not roll over. Those terms are on [pricing](https://unbroker.cloud/pricing) and in [Plans](https://docs.unbroker.cloud/billing/plans).

## Checklist before you move

1. Read the banner. Config as code is deprecated. Existing `railway.toml` and `railway.json` files keep working for services that already use them until 2026-12-01. New services cannot opt in.
2. Note which file Railway actually reads, including a custom absolute path. The file does not follow the Root Directory.
3. Write down `builder`, `buildCommand`, `dockerfilePath`, and `watchPatterns`. A gitignore negation does not survive as an Unbroker watch path.
4. Write down `startCommand`, `healthcheckPath`, `healthcheckTimeout`, and the restart policy. Unbroker does not document equivalents for `restartPolicyType`, `overlapSeconds`, or `drainingSeconds`.
5. Move `preDeployCommand` out of the image build and out of every replica's startup. On Railway a failure is not retried and the deployment does not proceed.
6. Treat `cronSchedule` as a job that exits, in UTC, at least 5 minutes apart. A process that stays up is a worker.
7. Copy `numReplicas` from `deploy.multiRegionConfig`, per region. Do not look for a top-level `numReplicas`.
8. List environment overrides, including `pr`, and every variable. Do not copy internal Railway hostnames. Do not carry a token in `ARG`.
9. Translate the file by hand. It is not an import format. On Unbroker the destination is service settings or `.unbroker/unbroker.ts`.
10. Check the plan. Dockerfile builds, workers, migration commands, scheduled jobs, one-off commands, advanced health checks, PR previews, volumes, and configurable replicas require Pro. The migration guide requires a Pro organization.

## FAQ

### What is railway.toml used for?

It is Railway config as code for one service. By default Railway looks for railway.toml or railway.json. Everything in the build and deploy sections of that service's settings can be specified there. Railway combines the file with dashboard settings for the deployment. The dashboard is not updated, and configuration defined in code always overrides dashboard values. The source is [Config as Code reference](https://docs.railway.com/reference/config-as-code).

### Is Railway config as code deprecated, and until when do railway.toml files work?

Yes. The reference banner says Config as Code is deprecated and to prefer Infrastructure as Code. The [config as code page](https://docs.railway.com/config-as-code) says existing railway.json and railway.toml files continue to work for services that already use them until 2026-12-01, which is a hard cutoff, and that new services cannot opt into Config as Code. The replacement is [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code).

### What is the difference between railway.toml and railway.json?

Preference. The reference says TOML and JSON have the same behavior. The JSON schema is at [railway.schema.json](https://railway.com/railway.schema.json). A custom config file path can be set in service settings as an absolute path, for example /backend/railway.toml, and that file does not follow the Root Directory.

### Does railway.toml override dashboard settings?

Yes. Railway combines file values with dashboard settings for the deployment, and it does not write those file values back to the dashboard. Configuration defined in code always overrides dashboard values. Inside the file, an environment-specific block wins over the base config in code, and the base config in code wins over service settings. The source is the [Config as Code reference](https://docs.railway.com/reference/config-as-code).

### How do I run migrations before deploy outside Railway (preDeployCommand)?

On Railway, the Railway pre deploy command is deploy.preDeployCommand. The documented example is `npm run db:migrate`. It runs between build and deploy, in a separate container, with the app's environment variables and private network. Volumes are not mounted, filesystem changes are not persisted, a failure is not retried, and the deployment does not proceed. There is no time limit by default. An optional Pre-deploy Timeout of 1 to 3600 seconds can be set in settings. The source is [Pre-deploy command](https://docs.railway.com/deployments/pre-deploy-command). Outside Railway, that step is one migration command, not a step in the image build and not a command on every replica's startup. On Unbroker, pre-deploy commands exist, share the service's environment isolation, and can reach its private databases. Migration commands require Pro. Infrastructure as code maps preDeploy. How to keep the migration safe for a rollback is [Database migrations on deploy](https://unbroker.cloud/blog/database-migrations-on-deploy).

### What replaces Railway's cronSchedule on another platform?

deploy.cronSchedule is a crontab expression, for example `*/15 * * * *`. Schedules are UTC, runs must be at least 5 minutes apart, the service must exit when it is done, and a run is skipped if the previous one is still active. The source is [Cron jobs](https://docs.railway.com/cron-jobs). On another platform that becomes a scheduled job that starts, runs, and exits, or a worker that stays up and has no inbound HTTP. On Unbroker, scheduled jobs and worker services require Pro. This page does not describe Unbroker's schedule syntax. The split between a worker and a job is [Background workers and cron jobs](https://unbroker.cloud/blog/background-workers-cron-jobs).

## Related reading

- [Move a Railway service to Unbroker](https://unbroker.cloud/migrate/railway)
- [Railway alternative](https://unbroker.cloud/alternatives/railway)
- [Railway pricing explained](https://unbroker.cloud/compare/railway-pricing)
- [Railway vs Render](https://unbroker.cloud/compare/railway-vs-render)
- [Database migrations on deploy](https://unbroker.cloud/blog/database-migrations-on-deploy)
- [Background workers and cron jobs](https://unbroker.cloud/blog/background-workers-cron-jobs)
- [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets)
- [Docker Compose in production](https://unbroker.cloud/blog/docker-compose-to-production)
- [render.yaml, field by field](https://unbroker.cloud/blog/render-yaml-to-services)
- [Usage vs capacity billing](https://unbroker.cloud/blog/usage-vs-capacity-billing)
- [Pricing](https://unbroker.cloud/pricing)
