railform

Railform is a TypeScript config layer for Railway. It previews, stages, and applies Railway projects, services, databases, variables, domains, and deploy settings from railform.config.ts.

Install

npm install -g railform
railway login

Quickstart

Create a project and install the config helpers:

mkdir my-app
cd my-app
npm init -y
npm install -D @railform/core

Create a config:

railform init

If your Railway account has multiple workspaces, init asks which one to use and saves it in .railform/state.json.

Preview changes:

railform plan

Apply changes:

railform apply

Minimal Config

import { Postgres, Project, Redis, Service, randomSecret } from "@railform/core";

export default new Project({
	name: "my-app",
	environment: "production",
	databases: [new Postgres({ name: "postgres" }), new Redis({ name: "redis" })],
	services: [
		new Service({
			name: "api",
			databases: ["postgres", "redis"],
			variables: {
				NODE_ENV: "production",
				SESSION_SECRET: randomSecret(48),
			},
			deploy: {
				startCommand: "bun run start",
				healthcheckPath: "/health",
			},
		}),
	],
});

Agent Approval Flow

Request human review and exit:

railform apply --request-approval --format json

Human review:

railform review <approval-id>
railform approve <approval-id>

Continue after approval:

railform apply --approval <approval-id> --wait --format json

Skip approval only when the user explicitly asked for it:

RAILFORM_DANGEROUSLY_SKIP_PERMISSIONS=1 railform apply --request-approval --wait --format json

Helpers

• randomSecret(48) creates ${{secret(48)}}.
• promptVariable("API token") asks at apply time or via --var.
• railwayRef("api", "RAILWAY_PRIVATE_DOMAIN") creates Railway references.
• railwayPublicUrl("web") and railwayPrivateUrl("api") create service URLs.

Agent instructions ship at:

node_modules/@railform/core/agent-skills/railway-stack/SKILL.md