# railway.toml, campo por campo: en qué se convierte cada ajuste al pasar a servicios separados

Un railway.toml o railway.json declara el build y el deploy de un servicio. Mira en qué se convierte cada campo.

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

## La respuesta corta

Un `railway.toml`, o los mismos ajustes en `railway.json`, declara el build y el deploy de un servicio de Railway. Lo que está en el archivo pisa al panel. En una plataforma de servicios separados, el builder pasa a ser un Dockerfile o una receta de framework, `startCommand` arranca el contenedor, `preDeployCommand` queda como el paso de migración, `healthcheckPath` queda como el chequeo HTTP, `cronSchedule` queda como un job programado o un worker, `numReplicas` dentro de una región queda como la cantidad de réplicas, y `environments.<name>` pisa el build y el deploy de ese entorno.

La configuración de Railway como código está deprecada. Los `railway.toml` y `railway.json` que ya existen siguen valiendo, en los servicios que ya los usan, hasta el 2026-12-01. Un servicio nuevo no puede optar por ese sistema.

Esta nota no copia precios de Railway. La diferencia de medidor está en [precio por uso o por capacidad](https://unbroker.cloud/es/blog/usage-vs-capacity-billing). Las tarifas publicadas siguen en [precios de Railway](https://unbroker.cloud/es/comparar/precios-railway). [Railway y Render](https://unbroker.cloud/compare/railway-vs-render) es el lado a lado con Render. Si ya decidiste mover un servicio, empieza por [llevar un servicio de Railway a Unbroker](https://unbroker.cloud/es/migrar/railway) y por la [guía de migración](https://docs.unbroker.cloud/guides/migrate-from-railway). La comparación está en la [página de Railway](https://unbroker.cloud/es/alternativas/railway).

## Qué declaran railway.toml y railway.json

Por defecto Railway busca `railway.toml` o `railway.json`. Todo lo que está en las secciones de build y de deploy de los ajustes del servicio se puede declarar ahí. Railway combina los valores del archivo con los del panel para el deployment. El panel no se actualiza. Lo definido en código siempre pisa los valores del panel. La fuente de esta sección es la [referencia de Config as Code](https://docs.railway.com/reference/config-as-code).

TOML y JSON son una preferencia. El comportamiento es el mismo. El schema JSON es [railway.schema.json](https://railway.com/railway.schema.json).

La ruta del archivo se puede cambiar en los ajustes del servicio. Es una ruta absoluta, por ejemplo `/backend/railway.toml`. El archivo de config no sigue el Root Directory.

Estas claves son formas de esa referencia, no una app de ejemplo y no un archivo 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` no es un campo de primer nivel en esa referencia. Aparece dentro de `deploy.multiRegionConfig`, por región, por ejemplo `"us-west2": { "numReplicas": 2 }`. También existen `build.railpackVersion`, `deploy.overlapSeconds` y `deploy.drainingSeconds`. Los dos últimos son el cierre del deployment.

## Qué cambió: de Config as Code a Infrastructure as Code

La [referencia de Config as Code](https://docs.railway.com/reference/config-as-code) muestra 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.

La [página de config as code](https://docs.railway.com/config-as-code) precisa el alcance de esa fecha. Los `railway.json` y `railway.toml` existentes siguen funcionando en los servicios que ya los usan, hasta el 2026-12-01. Esa fecha es un corte duro. Los servicios nuevos no pueden optar por Config as Code.

El reemplazo es [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code). El archivo `.railway/railway.ts` está en disponibilidad general. `.railway/railway.py` y `.railway/railway.go` están en beta. Se maneja con la CLI de Railway: `railway config init`, `railway config pull`, `railway config plan` y `railway config apply`.

`railway config migrate` es un preview. `railway config migrate --apply` escribe el archivo y limpia los ajustes de Railway Config File. `--delete-files` borra, si lo pides, los archivos viejos de config as code. Un servicio no puede estar gestionado por los dos sistemas a la vez.

El alcance no es el mismo. Config as code cubre el deployment de un servicio. Infrastructure as code cubre un proyecto y un entorno.

## Ajustes de build

`build.builder` vale `RAILPACK` o `DOCKERFILE`. `RAILPACK` es el default. Esos valores salen de la [referencia de Config as Code](https://docs.railway.com/reference/config-as-code), que dice: "Railway will always build with a Dockerfile if it finds one."

El paso de Railpack a Dockerfile es `builder = "DOCKERFILE"`, o un Dockerfile en el repo que Railway encuentra solo. `build.dockerfilePath` es la ubicación de un Dockerfile que no está en el lugar habitual. `build.buildCommand` es el comando de build que se le pasa al builder. `build.railpackVersion` existe. Esta nota no lista los valores que acepta.

`build.watchPatterns` es una lista de patrones que disparan el deploy solo a veces. Los patrones son estilo gitignore. Railpack y esos watch paths están descritos en [build configuration](https://docs.railway.com/builds/build-configuration). El ejemplo es `["src/**"]`.

Railway inyecta `PORT`. Los builds con Dockerfile tienen que declarar `ARG` para usar variables de Railway en el build. Ese patrón de `ARG` no viaja tal cual. La sección de la otra plataforma dice qué hacer con un token.

## Ajustes de deploy

`deploy.startCommand` es el comando que corre cuando arranca el contenedor.

La ruta de healthcheck de Railway es `deploy.healthcheckPath`, por ejemplo `"/health"`. `deploy.healthcheckTimeout` está en segundos. El default es 300. Railway consulta el endpoint hasta recibir un 2xx, y solo entonces activa el deployment nuevo. No sigue mirando el endpoint después de que el deploy está vivo. La fuente es [Healthchecks](https://docs.railway.com/deployments/healthchecks).

`deploy.restartPolicyType` vale `ON_FAILURE`, `ALWAYS` o `NEVER`. `deploy.restartPolicyMaxRetries` pone el tope de reintentos. El default es On Failure con un máximo de 10. La fuente es [Restart policy](https://docs.railway.com/deployments/restart-policy).

En esta referencia las réplicas son por región. `numReplicas` vive dentro de `deploy.multiRegionConfig` para una región, como en `"us-west2": { "numReplicas": 2 }`. No hay un `numReplicas` de primer nivel para copiar.

`deploy.overlapSeconds` y `deploy.drainingSeconds` existen. Pertenecen al cierre del deployment. Esta nota no les asigna un control en el destino.

## preDeployCommand y las migraciones

El comando de Railway previo al deploy es `deploy.preDeployCommand`. El ejemplo de la referencia es `["npm run db:migrate"]`. Corre entre el build y el deploy, en un contenedor aparte. Ese contenedor puede leer las variables de la app y usar la red privada. Los volúmenes no se montan. Los cambios de disco no se guardan. Si el comando falla, Railway no lo reintenta y el deployment no sigue. No hay límite de tiempo por defecto. En los ajustes se puede agregar un Pre-deploy Timeout de 1 a 3600 segundos. La fuente es [Pre-deploy command](https://docs.railway.com/deployments/pre-deploy-command).

En otra plataforma, deja eso como un solo comando de migración. No lo metas en el build de la imagen y no lo corras en cada réplica al arrancar. Cómo tiene que portarse la migración cuando vuelves el código atrás está en [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy).

## cronSchedule y los workers

El cron de Railway es `deploy.cronSchedule`. Es una expresión crontab, por ejemplo `"*/15 * * * *"`. Los horarios están en UTC. Las corridas tienen que separarse al menos 5 minutos. El servicio tiene que salir cuando el trabajo termina. Si la corrida anterior sigue activa, la siguiente se salta. La fuente es [Cron jobs](https://docs.railway.com/cron-jobs).

Eso es un proceso que arranca y sale. Un proceso que se queda vivo esperando una cola es un worker, no una línea de cron. Después del cambio son servicios distintos. La división operativa está en [Workers y tareas cron](https://unbroker.cloud/es/blog/background-workers-cron-jobs).

## Overrides por entorno y variables

`environments.<name>` pisa los ajustes de build y de deploy de ese entorno. El nombre especial es `pr`, para los deployments de PR. La prioridad es fija: config de ese entorno en código, después la config base en código, después los ajustes del servicio.

Las variables no forman parte del archivo. Anótalas aparte, en Variables del servicio. Railway también inyecta `PORT`. Un Dockerfile que necesita una variable de Railway en el build tiene que declarar `ARG`. Cómo funciona el alcance cuando esos valores ya son variables de entorno comunes está en [Variables de entorno y secretos](https://unbroker.cloud/es/blog/environment-variables-and-secrets).

Un repo que describe varios procesos en un solo archivo Compose es otro inventario. Ese mapa está en [Docker Compose en producción](https://unbroker.cloud/es/blog/docker-compose-to-production). Un blueprint de Render en render.yaml es otro inventario. El mapa de cada campo está en [render.yaml, campo por campo](https://unbroker.cloud/es/blog/render-yaml-to-services).

## railway.toml, campo por campo

| Campo de railway.toml | En qué se convierte |
| --- | --- |
| `build.builder = "RAILPACK"` | Un build de framework. Railpack es el default. |
| `build.builder = "DOCKERFILE"`, o un Dockerfile que Railway encuentra | Un build con Dockerfile. Railway siempre construye con un Dockerfile si encuentra uno. |
| `build.buildCommand` | El comando de build de la receta elegida, o el mismo comando escrito en el Dockerfile. |
| `build.dockerfilePath` | La ruta de un Dockerfile que no está en el lugar default. |
| `build.watchPatterns` | Watch paths. Un cambio despliega solo si un patrón de la lista coincide. En Railway los patrones son estilo gitignore. |
| `build.railpackVersion` | Un pin de versión de Railpack en Railway. Esta nota no lista valores aceptados y no inventa un campo de destino. |
| `deploy.startCommand` | El comando que arranca el contenedor. |
| `deploy.preDeployCommand` | Un comando de migración entre el build y el deploy, en su propio contenedor, no en el arranque de cada réplica. |
| `deploy.healthcheckPath` | Una ruta HTTP que tiene que devolver 2xx antes de que el deployment nuevo quede activo. |
| `deploy.healthcheckTimeout` | Cuánto puede esperar ese chequeo, en segundos. El default de Railway es 300. El chequeo se detiene cuando el deploy ya está activo. |
| `deploy.restartPolicyType` | `ON_FAILURE`, `ALWAYS` o `NEVER`. El default es On Failure. |
| `deploy.restartPolicyMaxRetries` | El tope de reintentos. El default con On Failure es 10. |
| `deploy.multiRegionConfig.<region>.numReplicas` | La cantidad de réplicas de esa región, por ejemplo `"us-west2": { "numReplicas": 2 }`. No es un `numReplicas` de primer nivel. |
| `deploy.cronSchedule` | Una corrida programada en UTC. El proceso sale. Las corridas se separan al menos 5 minutos, y si una sigue activa la siguiente se salta. |
| `deploy.overlapSeconds` y `deploy.drainingSeconds` | El cierre del deployment. Cópialos solo donde el destino documente los mismos controles. |
| `environments.<name>`, incluido `pr` | Overrides de un entorno. El código de ese entorno gana sobre el archivo base, y el archivo base gana sobre el panel. |

## Cómo funciona en Unbroker

<aside class="plan-box">
<p><strong>En Unbroker.</strong> railway.toml no es un formato de importación. Traduces cada campo a mano, a los ajustes del servicio o a <code>.unbroker/unbroker.ts</code>. La guía de migración pide una organización Pro. Los builds de Dockerfile, los workers, los comandos de migración, los jobs programados, los comandos de una vez, los health checks avanzados, los previews de PR, los volúmenes persistentes y las réplicas configurables piden Pro.</p>
</aside>

[La guía de migración](https://docs.unbroker.cloud/guides/migrate-from-railway) dice: "Do not assume platform configuration files or service-reference expressions are portable to another provider." Haz el inventario de la revisión de código, los comandos de build y de arranque, la región, las variables, el almacenamiento, los dominios y las dependencias de cada servicio, incluidos workers y tareas programadas.

La tabla de esa guía es corta. Comandos de build y de arranque: revisa la receta elegida, o escríbelos en el Dockerfile. Variables secretas y de referencia: vuelve a crear variables con alcance y las referencias de conexión del destino. Archivos persistentes: un volumen de destino. No copies hostnames internos de Railway. No lleves el patrón de `ARG` que carga un token. Unbroker expone `NODE_AUTH_TOKEN` o `GITHUB_TOKEN` como secreto de BuildKit.

[Tipos de servicio](https://docs.unbroker.cloud/apps/services) es donde cae el builder. Un servicio de repositorio construye los proyectos de servidor con Railpack, solo. No hace falta un `railpack.json`. Un Dockerfile del repositorio da control explícito del build. Un servicio de imagen corre una imagen que ya construiste. Una subida estática sirve archivos sin proceso de servidor. Un worker no tiene HTTP de entrada. Sirve para colas, procesamiento programado y trabajos async. Los builds de Dockerfile y los workers piden Pro.

Los watch paths existen, y no son gitignore. [Deploy from Git](https://docs.unbroker.cloud/deployments/git) dice que configures Watch paths en Build & deploy al crear un servicio de repositorio, o en los ajustes de Source del servicio. Un patrón por línea, relativo a la raíz del repo. Los patrones son `*`, `?` y `**`. Las exclusiones no están soportadas. El campo de la API es `watchPaths`. Una entrada de `watchPatterns` de Railway que empieza con `!` no tiene adónde ir. Lista los paths que quieres y deja afuera las negaciones.

[Deployments](https://docs.unbroker.cloud/deployments/overview) lleva una revisión por Queued, Building, Deploying y Live. Un health check fallido impide tratar una revisión enferma como live. Los health checks avanzados piden Pro. Esta nota no documenta un equivalente de restart policy para `ON_FAILURE`, `ALWAYS` o `NEVER`, ni equivalentes de `overlapSeconds` o `drainingSeconds`.

Los servicios de repositorio y de subida pueden correr varias réplicas, como cantidad fija o como autoscale por CPU y memoria. Los servicios de imagen, los workers y cualquier servicio con volumen persistente corren una réplica. En la celda compartida un servicio puede correr hasta 3 réplicas. Las réplicas configurables piden Pro. Free corre una réplica. No hay un bloque documentado de réplicas multi-región. El `numReplicas` de `multiRegionConfig` pasa a ser una cantidad de réplicas de ese servicio, o queda como un dato que anotas y no pretendes importar.

Existen comandos pre-deploy y post-deploy. Comparten el aislamiento de entorno del servicio y pueden llegar a sus bases privadas. Los comandos de migración piden Pro. El paso de migración está en [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy).

El archivo de infraestructura como código de Unbroker es `.unbroker/unbroker.ts`, o `.unbroker/unbroker.go`, o `.unbroker/unbroker.py`. Los comandos son `ubctl config init`, y después plan y apply. [Infrastructure as code](https://docs.unbroker.cloud/cli/infrastructure-as-code) dice que `@unbroker/iac` v0.2.0 mapea `preDeploy`. Post-deploy todavía no está en el schema. Los campos de servicio que muestra esa página incluyen `source`, `start`, `replicas` y `env`. Cambiar comandos, el health check o las réplicas dispara un deploy al hacer apply. Es un archivo distinto de `.railway/railway.ts`. Nada convierte uno en el otro.

Un worker es el servicio sin HTTP de entrada. Los jobs programados piden Pro. Esta nota no describe una expresión cron ni una pantalla de jobs de Unbroker. Usa [Workers y tareas cron](https://unbroker.cloud/es/blog/background-workers-cron-jobs) para la diferencia entre un proceso que se queda vivo y un comando que sale.

[Variables de entorno](https://docs.unbroker.cloud/deployments/environment-variables) tienen alcance Production, Preview o All. Un valor de un entorno pisa All. Una variable del servicio pisa una variable compartida del proyecto con la misma clave. Los previews de PR piden Pro. Copian los valores All y Preview, y nunca copian Production. Antes de adoptar la infraestructura como código de Unbroker, las variables con alcance solo de production o de preview tienen que pasar a valores de todo el entorno. Cómo se portan esos alcances en un preview está en [Variables de entorno y secretos](https://unbroker.cloud/es/blog/environment-variables-and-secrets).

Free es $0. Es un proyecto, dos servicios en total y tres pedidos de deploy por día UTC. Cada servicio Free corre una réplica, hasta 250m de CPU y 256 MiB, y se duerme cuando está idle. Pro sale $25 al mes, con $25 de crédito de uso por ciclo de facturación. El crédito no se acumula. Esos términos están en [precios](https://unbroker.cloud/es/precios) y en [Plans](https://docs.unbroker.cloud/billing/plans).

## Lista antes de pasar el servicio

1. Lee el banner. Config as code está deprecado. Los `railway.toml` y `railway.json` existentes siguen valiendo, en los servicios que ya los usan, hasta el 2026-12-01. Los servicios nuevos no pueden optar.
2. Anota qué archivo lee Railway de verdad, incluida una ruta absoluta propia. El archivo no sigue el Root Directory.
3. Anota `builder`, `buildCommand`, `dockerfilePath` y `watchPatterns`. Una negación de gitignore no sobrevive como watch path de Unbroker.
4. Anota `startCommand`, `healthcheckPath`, `healthcheckTimeout` y la restart policy. Unbroker no documenta equivalentes de `restartPolicyType`, `overlapSeconds` o `drainingSeconds`.
5. Saca `preDeployCommand` del build de la imagen y del arranque de cada réplica. En Railway un fallo no se reintenta y el deployment no sigue.
6. Trata `cronSchedule` como un job que sale, en UTC, con al menos 5 minutos de separación. Un proceso que se queda vivo es un worker.
7. Copia `numReplicas` desde `deploy.multiRegionConfig`, por región. No busques un `numReplicas` de primer nivel.
8. Lista los overrides de entorno, incluido `pr`, y cada variable. No copies hostnames internos de Railway. No lleves un token en `ARG`.
9. Traduce el archivo a mano. No es un formato de importación. En Unbroker el destino son los ajustes del servicio o `.unbroker/unbroker.ts`.
10. Revisa el plan. Los builds de Dockerfile, los workers, los comandos de migración, los jobs programados, los comandos de una vez, los health checks avanzados, los previews de PR, los volúmenes y las réplicas configurables piden Pro. La guía de migración pide una organización Pro.

## Preguntas frecuentes

### ¿Para qué sirve railway.toml?

Es la configuración de Railway como código de un servicio. Por defecto Railway busca railway.toml o railway.json. Ahí se puede declarar todo lo que está en las secciones de build y de deploy de ese servicio. Railway combina el archivo con los ajustes del panel para el deployment. El panel no se actualiza, y lo que está definido en código siempre pisa los valores del panel. La fuente es la [referencia de Config as Code](https://docs.railway.com/reference/config-as-code).

### ¿La configuración de Railway como código está deprecada, y hasta cuándo sirven los archivos railway.toml?

Sí. El banner de la referencia dice que Config as Code está deprecado y que conviene usar Infrastructure as Code. La [página de config as code](https://docs.railway.com/config-as-code) dice que los railway.json y railway.toml que ya existen siguen funcionando, en los servicios que ya los usan, hasta el 2026-12-01. Esa fecha es un corte duro. Los servicios nuevos no pueden optar por Config as Code. El reemplazo es [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code).

### ¿En qué se diferencian railway.toml y railway.json?

En el formato, nada más. La referencia dice que TOML y JSON se comportan igual. El schema JSON está en [railway.schema.json](https://railway.com/railway.schema.json). En los ajustes del servicio puedes fijar otra ruta, absoluta, por ejemplo /backend/railway.toml. Ese archivo no sigue el Root Directory.

### ¿railway.toml pisa lo que está en el panel?

Sí. Railway combina los valores del archivo con los del panel para el deployment, y no escribe esos valores de vuelta en el panel. Lo definido en código siempre pisa al panel. Dentro del archivo, el bloque de un entorno gana sobre la config base en código, y la config base en código gana sobre los ajustes del servicio. La fuente es la [referencia de Config as Code](https://docs.railway.com/reference/config-as-code).

### ¿Cómo se corren las migraciones antes del deploy fuera de Railway (preDeployCommand)?

En Railway, el comando previo al deploy es deploy.preDeployCommand. El ejemplo de la documentación es `npm run db:migrate`. Corre entre el build y el deploy, en un contenedor aparte, con las variables de la app y la red privada. Los volúmenes no se montan, los cambios de disco no se guardan, un fallo no se reintenta y el deployment no sigue. No hay límite de tiempo por defecto. En los ajustes se puede poner un Pre-deploy Timeout de 1 a 3600 segundos. La fuente es [Pre-deploy command](https://docs.railway.com/deployments/pre-deploy-command). Fuera de Railway, ese paso es un comando de migración: no va en el build de la imagen y no va en el arranque de cada réplica. En Unbroker existen comandos pre-deploy. Comparten el aislamiento de entorno del servicio y pueden llegar a sus bases privadas. Los comandos de migración piden Pro. La infraestructura como código mapea preDeploy. Cómo dejar la migración a salvo de un rollback está en [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy).

### ¿Qué reemplaza el cronSchedule de Railway en otra plataforma?

deploy.cronSchedule es una expresión crontab, por ejemplo `*/15 * * * *`. Los horarios están en UTC, las corridas tienen que separarse al menos 5 minutos, el servicio tiene que salir al terminar, y si la corrida anterior sigue activa la siguiente se salta. La fuente es [Cron jobs](https://docs.railway.com/cron-jobs). En otra plataforma eso es un job programado que arranca, corre y sale, o un worker que se queda vivo y no recibe HTTP. En Unbroker, los jobs programados y los workers piden Pro. Esta nota no describe la sintaxis de horarios de Unbroker. La diferencia entre un worker y un job está en [Workers y tareas cron](https://unbroker.cloud/es/blog/background-workers-cron-jobs).

## Related reading

- [Llevar un servicio de Railway a Unbroker](https://unbroker.cloud/es/migrar/railway)
- [Alternativa a Railway](https://unbroker.cloud/es/alternativas/railway)
- [Precios de Railway, explicados](https://unbroker.cloud/es/comparar/precios-railway)
- [Railway y Render](https://unbroker.cloud/compare/railway-vs-render)
- [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy)
- [Workers y tareas cron](https://unbroker.cloud/es/blog/background-workers-cron-jobs)
- [Variables de entorno y secretos](https://unbroker.cloud/es/blog/environment-variables-and-secrets)
- [Docker Compose en producción](https://unbroker.cloud/es/blog/docker-compose-to-production)
- [render.yaml, campo por campo](https://unbroker.cloud/es/blog/render-yaml-to-services)
- [Precio por uso o por capacidad](https://unbroker.cloud/es/blog/usage-vs-capacity-billing)
- [Precios](https://unbroker.cloud/es/precios)
