Infrastructure as Code (IaC)

Railway Infrastructure as Code lets you define the services and resources in a Railway project with a TypeScript file:

Use Railway IaC when you want one editable file for project-level configuration: services, databases, volumes, buckets, custom domains, environment variables, replicas, and canvas groups.

TypeScript only (for now). Railway IaC is authored in TypeScript via the railway SDK and a .railway/railway.ts file. TypeScript is currently the only supported language; other languages may follow.

IaC vs Config as Code

Railway has two code-based configuration systems:

Config as Code is read from your service repository during deploy. It overrides dashboard values for that service.

Infrastructure as Code is evaluated by the Railway CLI. The CLI compares .railway/railway.ts with the selected Railway environment, shows the changes it would make, and applies those changes only after confirmation.

A service cannot be managed by both systems at the same time. If a service is already managed by railway.json or railway.toml, railway config plan stops and tells you which service must be migrated before .railway/railway.ts can manage it.

Install or upgrade the CLI

Infrastructure as Code is managed through the Railway CLI. See Installing the CLI for installation instructions.

Then authenticate and connect the current directory to the Railway project and environment you want to manage:

If the current directory is not linked, railway config plan, railway config apply, and railway config pull prompt you to choose the Railway project and environment to use.

Commands

Initialize a new configuration

Run:

Railway creates:

The CLI can scan the current directory and generate a starting service from your package manager, package.json scripts, and GitHub remote.

Example generated file:

Import an existing project

Run:

This writes the linked Railway project's current configuration to .railway/railway.ts.

The importer generates code intended to be edited by humans. It keeps user-facing names, omits platform defaults, leaves out generated Railway domains, avoids internal IDs, and omits encrypted secrets unless it must include preserve() to avoid overwriting an existing value.

After importing, run a plan to check whether the generated file would change anything in Railway:

A clean import should show no changes:

Preview changes

Run:

Example output when the file creates one service:

plan is safe. It only reads Railway state and prints the changes that would be applied.

Variable values are redacted in plan output by default (shown as «hidden»), so secrets defined in .railway/railway.ts don't end up in your terminal or CI logs. The variable and whether it's changing are still shown. To print the actual values — useful when reviewing non-secret config — pass --show-values:

For machine-readable output:

To gate CI on drift, use --detailed-exit-code. The plan then exits 0 when nothing would change and 2 when changes are pending (errors stay non-zero):

--detailed-exit-code is opt-in, so the default exit behavior is unchanged.

Apply changes

Run:

Railway always runs a plan before applying. In an interactive terminal, you will be asked to confirm the exact changes shown in the plan.

To apply non-interactively:

Destructive changes, such as deleting a service or variable, are marked before confirmation. Review those lines carefully before continuing. Non-interactively (with --yes, --json, or in an agent session), destructive changes additionally require --confirm-destructive, so a stray --yes cannot remove resources on its own:

Apply is also protected against acting on a stale plan. Railway runs a fresh plan immediately before applying and commits against the exact environment state it just read. If the environment changed in between — for example a concurrent apply or a dashboard edit — the apply is rejected and you are asked to run railway config plan again. This prevents an apply from silently overwriting changes it never saw.

Authoring

A Railway configuration file exports defineRailway and returns a project.

For the full TypeScript DSL, including services, sources, replicas, variables, databases, volumes, buckets, domains, groups, and environment context, see the Infrastructure as Code reference.

Migrating from Config as Code

If you currently use railway.json or railway.toml, migrate one service at a time. Do not leave the same service managed by both files.

1. Import your current Railway project:

2. Open the service's railway.json or railway.toml file and translate the settings you want Railway IaC to own into the .railway/railway.ts DSL.

   For example, this railway.json:

   becomes:

3. Remove the old railway.json or railway.toml file from the service's source repository.

   If the service uses a custom config file path in Railway, open the service's Settings, find the config file path field, and clear it. After this step, future deployments for that service should not read railway.json or railway.toml.

4. Preview the migration:

5. Review the plan. It is safe to apply when the listed changes are only the settings you intentionally moved into .railway/railway.ts.

   For example, a good migration plan might show updates to build, start, or healthcheck for the service you migrated. It should not show unexpected service deletes, variable deletes, bucket deletes, or changes to unrelated services.

6. Apply the migration:

Railway blocks plans for services still managed by railway.json or railway.toml to prevent two sources of truth. If you see that error, remove the repo config file for that service and run railway config plan again.

Generated support files

railway config init and railway config pull also create project-local support files:

These files help teammates and agents understand how to edit the Railway configuration safely.

Limitations

Infrastructure as Code is experimental. Current limitations include:

• Services managed by railway.json or railway.toml must be migrated before IaC can manage them.
• Volume lifecycle is intentionally conservative to avoid accidental unmounts.
• Bucket regions are immutable after creation.
• Persisted ChangeSet history and apply-later workflows are not part of v0.
• Generated .railway/railway.ts formatting may change while the DSL is experimental.

Related pages

• Infrastructure as Code reference
• Config as Code
• Config as Code reference
• CLI
• Environments
• Variables