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. Published rates stay on Railway pricing. 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 and the migration tutorial. The comparison is the Railway page.
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.
TOML and JSON are a preference. The behavior is the same. The JSON schema is 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:
[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 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 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. 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, 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 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.
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.
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.
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.
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.
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.
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.
A repo that describes several processes in one Compose file is a different inventory. That map is Docker Compose in production. A Render Blueprint in render.yaml is a different inventory. The field map is render.yaml, field by field.
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
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 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 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 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.
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 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 for the difference between a process that stays up and a command that exits.
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.
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 and in Plans.
Checklist before you move
- Read the banner. Config as code is deprecated. Existing
railway.tomlandrailway.jsonfiles keep working for services that already use them until 2026-12-01. New services cannot opt in. - Note which file Railway actually reads, including a custom absolute path. The file does not follow the Root Directory.
- Write down
builder,buildCommand,dockerfilePath, andwatchPatterns. A gitignore negation does not survive as an Unbroker watch path. - Write down
startCommand,healthcheckPath,healthcheckTimeout, and the restart policy. Unbroker does not document equivalents forrestartPolicyType,overlapSeconds, ordrainingSeconds. - Move
preDeployCommandout of the image build and out of every replica’s startup. On Railway a failure is not retried and the deployment does not proceed. - Treat
cronScheduleas a job that exits, in UTC, at least 5 minutes apart. A process that stays up is a worker. - Copy
numReplicasfromdeploy.multiRegionConfig, per region. Do not look for a top-levelnumReplicas. - List environment overrides, including
pr, and every variable. Do not copy internal Railway hostnames. Do not carry a token inARG. - Translate the file by hand. It is not an import format. On Unbroker the destination is service settings or
.unbroker/unbroker.ts. - 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.
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 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.
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. 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.
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. 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.
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. 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.