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. Las tarifas publicadas siguen en precios de Railway. Railway y Render es el lado a lado con Render. Si ya decidiste mover un servicio, empieza por llevar un servicio de Railway a Unbroker y por la guía de migración. La comparación está en la página de 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.
TOML y JSON son una preferencia. El comportamiento es el mismo. El schema JSON es 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:
[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 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 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. 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, 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. 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.
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.
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.
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.
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.
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.
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.
Un repo que describe varios procesos en un solo archivo Compose es otro inventario. Ese mapa está en Docker Compose en producción. Un blueprint de Render en render.yaml es otro inventario. El mapa de cada campo está en render.yaml, campo por campo.
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
La guía de migración 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 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 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 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.
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 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 para la diferencia entre un proceso que se queda vivo y un comando que sale.
Variables de entorno 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.
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 y en Plans.
Lista antes de pasar el servicio
- Lee el banner. Config as code está deprecado. Los
railway.tomlyrailway.jsonexistentes siguen valiendo, en los servicios que ya los usan, hasta el 2026-12-01. Los servicios nuevos no pueden optar. - Anota qué archivo lee Railway de verdad, incluida una ruta absoluta propia. El archivo no sigue el Root Directory.
- Anota
builder,buildCommand,dockerfilePathywatchPatterns. Una negación de gitignore no sobrevive como watch path de Unbroker. - Anota
startCommand,healthcheckPath,healthcheckTimeouty la restart policy. Unbroker no documenta equivalentes derestartPolicyType,overlapSecondsodrainingSeconds. - Saca
preDeployCommanddel build de la imagen y del arranque de cada réplica. En Railway un fallo no se reintenta y el deployment no sigue. - Trata
cronSchedulecomo un job que sale, en UTC, con al menos 5 minutos de separación. Un proceso que se queda vivo es un worker. - Copia
numReplicasdesdedeploy.multiRegionConfig, por región. No busques unnumReplicasde primer nivel. - Lista los overrides de entorno, incluido
pr, y cada variable. No copies hostnames internos de Railway. No lleves un token enARG. - 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. - 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.
¿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 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.
¿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. 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.
¿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. 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.
¿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. 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.