The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Add Railway hosted deploy via Infrastructure as Code (#504)
Abhishek Choudharyf4fb4bda48ce
diff --git a/.changeset/railway-database-url.md b/.changeset/railway-database-url.mdnew file mode 100644index 000000000..0e875f4cd--- /dev/null+++ b/.changeset/railway-database-url.md@@ -0,0 +1,5 @@+---+"@truefoundry/trueforge": patch+---++Accept `DATABASE_URL` for hosted mode so managed Postgres (e.g. Railway) can be wired without discrete `POSTGRES_*` vars.diff --git a/.railway/README.md b/.railway/README.mdnew file mode 100644index 000000000..989ed3b89--- /dev/null+++ b/.railway/README.md@@ -0,0 +1,16 @@+# Railway configuration++TrueForge hosted topology (app + Postgres + Redis) lives in [`.railway/railway.ts`](./railway.ts).++```bash+pnpm install+railway login+railway init --name trueforge # or: railway link to an existing project+railway config plan+railway config apply+railway domain # public URL for the trueforge service+```++`RAILWAY_DOCKERFILE_PATH=Dockerfile.dev` selects the from-source image (`STANDALONE=false` and `HOST=0.0.0.0` are baked into that file). Auth is **off** by default — anyone who can reach the URL is admin. Before sharing a deployment, enable [OIDC login](https://trueforge.dev/authentication/overview) (optional shared-variable block is commented in `railway.ts`).++See [Railway Infrastructure as Code](https://docs.railway.com/infrastructure-as-code). Do not add a root `railway.toml` / `railway.json` — those conflict with this file.diff --git a/.railway/railway.ts b/.railway/railway.tsnew file mode 100644index 000000000..52b8bf937--- /dev/null+++ b/.railway/railway.ts@@ -0,0 +1,64 @@+/**+ * Railway Infrastructure as Code for TrueForge hosted mode.+ *+ * One project: app + Postgres + Redis. Plan/apply with:+ * pnpm install+ * railway login+ * railway init --name trueforge # or: railway link+ * railway config plan+ * railway config apply+ * railway domain # public URL for the trueforge service+ *+ * Docs: https://docs.railway.com/infrastructure-as-code+ *+ * Auth is off by default (anyone who can reach the URL is admin). Before+ * sharing a deployment, enable OIDC — see the commented block below and+ * https://trueforge.dev/authentication/overview+ */+import { defineRailway, github, group, postgres, project, redis, service } from 'railway/iac';++export default defineRailway(_ctx => {+ const db = postgres('Postgres');+ const cache = redis('Redis');++ const app = service('trueforge', {+ // Deploys from this repository's default branch. Forks: change owner/repo+ // (and optionally branch) to build your own copy.+ source: github('truefoundry/trueforge'),+ // IaC `build` is a build *command* string (not CaC's builder/dockerfilePath object).+ // Non-root Dockerfile is selected via RAILWAY_DOCKERFILE_PATH below — without it,+ // Railway picks the root Dockerfile (npm install of a published version) and fails+ // without APP_VERSION.+ healthcheck: '/healthz',+ healthcheckTimeout: 300,+ deploy: {+ restartPolicyType: 'ON_FAILURE',+ restartPolicyMaxRetries: 5,+ // Above GRACEFUL_TIMEOUT_SECONDS (30) so SIGKILL does not cut off turn drain.+ drainingSeconds: 35,+ },+ env: {+ // From-source image; root Dockerfile is the published npm recipe and needs APP_VERSION.+ RAILWAY_DOCKERFILE_PATH: 'Dockerfile.dev',+ DATABASE_URL: db.env.DATABASE_URL,+ REDIS_URL: cache.env.REDIS_URL,+ // Expanded by Railway at runtime once a public domain exists on this service.+ PUBLIC_BASE_URL: 'https://${{RAILWAY_PUBLIC_DOMAIN}}',++ // Optional OIDC (login off until these are set). Create matching *shared*+ // variables on the Railway environment, uncomment, then `railway config apply`.+ //+ // OIDC_ISSUER_URL: _ctx.shared.OIDC_ISSUER_URL,+ // OIDC_CLIENT_ID: _ctx.shared.OIDC_CLIENT_ID,+ // OIDC_CLIENT_SECRET: _ctx.shared.OIDC_CLIENT_SECRET,+ // OIDC_USER_REFERENCE_CLAIM: 'email',+ // OIDC_SCOPES: 'openid,profile,email',+ // OIDC_USER_ROLE_CLAIM: 'email',+ // OIDC_ADMIN_ROLE_VALUE: '[email protected]',+ },+ });++ return project('trueforge', {+ resources: [group('TrueForge', [db, cache, app])],+ });+});diff --git a/Dockerfile.dev b/Dockerfile.devindex 6529a27b3..e3c66dd35 100644--- a/Dockerfile.dev+++ b/Dockerfile.dev@@ -8,7 +8,8 @@## Dependency install uses pnpm fetch (lockfile-only) then install --offline so# the download layer stays cached when only package.json / scripts change.-# See https://pnpm.io/cli/fetch+# See https://pnpm.io/cli/fetch. BuildKit cache mounts are avoided so the same+# file builds on Railway Metal (which requires a hardcoded service id in mount ids).FROM node:24-slim AS baseENV PNPM_HOME=/pnpm@@ -18,10 +19,14 @@ WORKDIR /app# ---------------------------------------------------------------------------# store: the pnpm store, from the lockfile only (stable when manifests churn).+# BuildKit cache mounts are omitted: Railway's Metal builder requires+# `id=s/<service-id>-…` (hardcoded per deploy), which cannot live in a shared+# OSS Dockerfile. Layer cache on this stage still hits when the lockfile is+# unchanged.# ---------------------------------------------------------------------------FROM base AS storeCOPY pnpm-lock.yaml pnpm-workspace.yaml ./-RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm fetch+RUN pnpm fetch# ---------------------------------------------------------------------------# workspace: install inputs shared by every stage below — the manifests plus the@@ -41,8 +46,7 @@ COPY packages/trueforge-core/src/core/sandbox/scripts packages/trueforge-core/sr# builder: install all deps (incl. dev) and build trueforge-core + server.# ---------------------------------------------------------------------------FROM workspace AS builder-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \- pnpm install --frozen-lockfile --offline --filter @truefoundry/trueforge...+RUN pnpm install --frozen-lockfile --offline --filter @truefoundry/trueforge...COPY packages/trueforge-core packages/trueforge-coreCOPY packages/trueforge packages/trueforgeRUN pnpm --filter @truefoundry/trueforge-core build && pnpm --filter @truefoundry/trueforge build@@ -51,8 +55,7 @@ RUN pnpm --filter @truefoundry/trueforge-core build && pnpm --filter @truefoundr# frontend-builder: build the UI the server serves (parallel to builder above).# ---------------------------------------------------------------------------FROM workspace AS frontend-builder-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \- pnpm install --frozen-lockfile --offline --filter frontend...+RUN pnpm install --frozen-lockfile --offline --filter frontend...COPY packages/trueforge-sdk packages/trueforge-sdkRUN pnpm --filter @truefoundry/trueforge-sdk buildCOPY packages/trueforge-ui packages/trueforge-ui@@ -64,14 +67,17 @@ RUN pnpm --filter frontend build# prod-deps: production dependency tree (no dev tooling), resolved offline.# ---------------------------------------------------------------------------FROM workspace AS prod-deps-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \- pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/trueforge...+RUN pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/trueforge...# ---------------------------------------------------------------------------# runner: minimal image with prod node_modules + built artifacts.# ---------------------------------------------------------------------------FROM base AS runner-ENV NODE_ENV=production+# HOST=0.0.0.0 so Railway / Compose published ports and probes reach the process.+# STANDALONE=false ⇒ Postgres + Redis (hosted topology this image is built for).+ENV NODE_ENV=production \+ STANDALONE=false \+ HOST=0.0.0.0# Production dependency tree (pnpm workspace symlinks preserved).COPY --from=prod-deps /app/node_modules ./node_modulesdiff --git a/README.md b/README.mdindex 1a4d1815d..efa79f7ab 100644--- a/README.md+++ b/README.md@@ -48,7 +48,7 @@ Building an agent is easy. Running one well is not - you need streaming, session- **Context engineering** - subagents, deferred tool loading, Code Mode, large-result offloading, and compaction.- **Chat UI + SDK** - use the bundled UI, automate with `@truefoundry/trueforge-sdk`, or embed `@truefoundry/trueforge-ui`.-It scales down and up: **local mode** (one process, SQLite) or **hosted mode** (Postgres + Redis, Docker Compose or Helm).+It scales down and up: **local mode** (one process, SQLite) or **hosted mode** (Postgres + Redis, Docker Compose, Helm, or Railway).## Getting started@@ -58,7 +58,7 @@ It scales down and up: **local mode** (one process, SQLite) or **hosted mode** (npx @truefoundry/trueforge@latest```-Use the [Quickstart](https://trueforge.dev/quickstart) guide to run TrueForge using various methods (Local, Docker Compose, or Kubernetes). Connect models, tools, skills and build your first reusable agent.+Use the [Quickstart](https://trueforge.dev/quickstart) guide to run TrueForge using various methods (Local, Docker Compose, Kubernetes, or Railway). Connect models, tools, skills and build your first reusable agent.To work on TrueForge from this repository, see [CONTRIBUTING.md](CONTRIBUTING.md).@@ -72,10 +72,10 @@ To work on TrueForge from this repository, see [CONTRIBUTING.md](CONTRIBUTING.md</picture></p>-| Mode | Best for | Storage | Extra infra | How to run |-| ------ | --------------------------- | -------- | ---------------- | ---------------------------- |-| Local | Personal use, trying it out | SQLite | None | `npx @truefoundry/trueforge` |-| Hosted | Teams, multi-replica | Postgres | Postgres + Redis | Docker Compose or Helm |+| Mode | Best for | Storage | Extra infra | How to run |+| ------ | --------------------------- | -------- | ---------------- | -------------------------------- |+| Local | Personal use, trying it out | SQLite | None | `npx @truefoundry/trueforge` |+| Hosted | Teams, multi-replica | Postgres | Postgres + Redis | Docker Compose, Helm, or Railway |> **Local mode is for your machine only.** It is a convenient way to try TrueForge — not a production or internet-facing setup. There is no login by default, and data lives in a local SQLite file. Please keep it on localhost. We cannot take responsibility for data loss or unauthorized access if local mode is used beyond that. For a shared or production deployment, use hosted mode.diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdxindex 294e6d18d..a74792ce2 100644--- a/docs/authentication/overview.mdx+++ b/docs/authentication/overview.mdx@@ -14,7 +14,10 @@ Login in TrueForge is **optional**. Run it without auth for personal, local use,| **OIDC login** | Hosted or shared team deployments | Sign-in with your IdP; each person is an `admin` or a `user` |<Note>- Standalone / local mode ignores OIDC even if the variables are set. OIDC login applies to hosted deployments (Docker Compose or Helm). Local mode is intended for personal use on your own machine — it is not a production or internet-facing setup. Please keep it on localhost; we cannot take responsibility for data loss or unauthorized access if it is used beyond that.+ Standalone / local mode ignores OIDC even if the variables are set. OIDC login applies to hosted deployments+ (Docker Compose, Helm, or Railway). Local mode is intended for personal use on your own machine — it is not a+ production or internet-facing setup. Please keep it on localhost; we cannot take responsibility for data loss or+ unauthorized access if it is used beyond that.</Note>## Option A — leave login offdiff --git a/docs/introduction.mdx b/docs/introduction.mdxindex 6c8a06cd0..2aa7a863a 100644--- a/docs/introduction.mdx+++ b/docs/introduction.mdx@@ -81,7 +81,7 @@ The agent features are identical in both modes — only the backend around the s| | Local | Hosted || --- | --- | --- || **Best for** | Personal use — one process on your machine, like Claude Desktop | A shared deployment for your team, like Claude's managed agents |-| **How to run** | `npx @truefoundry/trueforge` | Docker Compose or Helm |+| **How to run** | `npx @truefoundry/trueforge` | Docker Compose, Helm, or Railway || **Storage** | SQLite | Postgres, shared by all replicas || **Extra infra** | None | Postgres + Redis || **Replicas** | Single process | Multiple replicas behind a load balancer. Redis peers them so streams and cancellations follow the client across replicas. |diff --git a/docs/quickstart.mdx b/docs/quickstart.mdxindex bc92c48b8..49c6967a7 100644--- a/docs/quickstart.mdx+++ b/docs/quickstart.mdx@@ -9,7 +9,7 @@ description: 'Run TrueForge, connect a model and tools, and build your first reuTrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode** — a single process on your machine, like a personal productivity tool — and **hosted mode** — a shared deployment for your team, with Postgres for storage and Redis for cross-replica peering. The agent features are identical in both.<Tabs>- <Tab title="Local mode (npx)">+ <Tab title="npx (Local)">Requires [Node.js](https://nodejs.org) 22.14 or newer. One command, no other infrastructure — the UI and backend run locally, and data is stored in a local SQLite file:```bash@@ -26,7 +26,7 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**</Warning></Tab>- <Tab title="Hosted mode (Docker Compose)">+ <Tab title="Docker Compose (Hosted)">Runs the full hosted topology on your machine: the server (UI + API), Postgres, and Redis.```bash@@ -44,7 +44,7 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**| Host ports | `8791`, `5433`, `6380` | App, Postgres, and Redis. |</Tab>- <Tab title="Hosted mode (Kubernetes)">+ <Tab title="Kubernetes (Hosted)">The Helm chart deploys the server in hosted mode with bundled Postgres and Redis (or point it at your own):```bash@@ -94,11 +94,35 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**| `configs.oidc.enabled` | `false` | Enable IdP login via `configs.oidc.*`. Default off = shared local admin — see [chart README](https://github.com/truefoundry/trueforge/blob/main/charts/trueforge/README.md#dev-defaults-read-before-exposing). |</Tab>+ <Tab title="Railway (Hosted)">+ Hosted topology on [Railway](https://railway.com) is defined with [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code) in [`.railway/railway.ts`](https://github.com/truefoundry/trueforge/blob/main/.railway/railway.ts): one project with the server (UI + API), Postgres, and Redis. The app sets `RAILWAY_DOCKERFILE_PATH=Dockerfile.dev` so Railway builds the from-source image ([`Dockerfile.dev`](https://github.com/truefoundry/trueforge/blob/main/Dockerfile.dev)), and wires `DATABASE_URL`, `REDIS_URL`, and `PUBLIC_BASE_URL` in that file.++ From a clone of this repo:++ ```bash+ pnpm install+ railway login+ railway init --name trueforge+ railway config plan+ railway config apply+ railway domain+ ```++ `railway config apply` creates the three services and connects them. Generate a public domain on the `trueforge` service (CLI above or Settings → Networking), then open that URL.++ <Warning>+ Without [OIDC login](/authentication/overview), anyone who can reach the URL is admin. Enable login before sharing+ a Railway deployment beyond personal use.+ </Warning>++ `STANDALONE=false` and `HOST=0.0.0.0` are baked into `Dockerfile.dev`. Railway injects `PORT` automatically.++ </Tab></Tabs><Note>- Local mode (`npx`) uses SQLite and needs no other services. Docker Compose and Kubernetes run hosted mode: Postgres- replaces SQLite as durable storage, and Redis peers the replicas so streams and cancellations follow the client+ Local mode (`npx`) uses SQLite and needs no other services. Docker Compose, Kubernetes, and Railway run hosted mode:+ Postgres replaces SQLite as durable storage, and Redis peers the replicas so streams and cancellations follow the clientacross them.</Note>@@ -252,7 +276,8 @@ With TrueForge open in your browser, this walkthrough takes you from an empty woPUBLIC_BASE_URL=https://trueforge.myorg.com npx @truefoundry/trueforge```- In hosted mode, set it in `packages/trueforge/.env` (Docker Compose) or via `server.publicBaseUrl` (Helm).+ In hosted mode, set it in `packages/trueforge/.env` (Docker Compose), via `server.publicBaseUrl` (Helm), or as+ `PUBLIC_BASE_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}` on Railway.</Accordion></AccordionGroup>diff --git a/eslint.config.mjs b/eslint.config.mjsindex e9e5c9495..cfa2be8fe 100644--- a/eslint.config.mjs+++ b/eslint.config.mjs@@ -54,6 +54,8 @@ export default defineConfig('packages/trueforge-sdk/**',// Build-generated sources (catalogs, sandbox scripts); not in package tsconfigs.'**/*.gen.ts',+ // Railway IaC config: consumed by the railway CLI, not part of a package tsconfig.+ '.railway/**',],},{diff --git a/package.json b/package.jsonindex 3be2de1e0..0ed7b0aa1 100644--- a/package.json+++ b/package.json@@ -61,6 +61,7 @@"lint-staged": "^16.4.0","prettier": "^3.9.6","prettier-plugin-organize-imports": "^4.3.0",+ "railway": "^3.11.0","typescript": "~5.9.3","typescript-eslint": "^8.68.0"},diff --git a/packages/trueforge/.env.example b/packages/trueforge/.env.exampleindex da8f1c21c..a0375be89 100644--- a/packages/trueforge/.env.example+++ b/packages/trueforge/.env.example@@ -120,7 +120,12 @@ REDIS_URL=redis://localhost:6379## Local-dev credentials only (trueforge/trueforge) — change them for any shared## or networked host. Keep localhost here for host `pnpm dev`;## `docker-compose.yml` overrides POSTGRES_HOST/PORT for the server container.+##+## Managed Postgres (Railway, etc.): set DATABASE_URL instead of the discrete+## POSTGRES_* vars below. When DATABASE_URL is set, POSTGRES_* are ignored for+## the app connection (Compose postgres still needs POSTGRES_* for its own env).## ---------------------------------------------------------------------------+# DATABASE_URL=postgres://trueforge:trueforge@localhost:5432/trueforgePOSTGRES_USER=trueforgePOSTGRES_PASSWORD=trueforgePOSTGRES_DB=trueforgediff --git a/packages/trueforge/src/config.ts b/packages/trueforge/src/config.tsindex b809ca0e8..68727bd4d 100644--- a/packages/trueforge/src/config.ts+++ b/packages/trueforge/src/config.ts@@ -186,8 +186,15 @@ function resolveRedisUrl(): string {return raw;}-/** Postgres connection string derived from `POSTGRES_*` for distributed mode. */+/**+ * Postgres connection string for distributed mode.+ * Prefers `DATABASE_URL` when set (Railway / managed Postgres); otherwise builds from `POSTGRES_*`.+ */function resolvePostgresDatabaseUrl(): string {+ const databaseUrl = getEnv('DATABASE_URL');+ if (databaseUrl !== undefined && databaseUrl.trim() !== '') {+ return databaseUrl.trim();+ }const postgresUser = getEnv('POSTGRES_USER', { defaultValue: DEFAULT_POSTGRES_USER }) ?? DEFAULT_POSTGRES_USER;const postgresPassword =getEnv('POSTGRES_PASSWORD', { defaultValue: DEFAULT_POSTGRES_PASSWORD }) ?? DEFAULT_POSTGRES_PASSWORD;@@ -205,7 +212,7 @@ function resolvePostgresDatabaseUrl(): string {postgresHost.trim() === '') {throw new Error(- 'POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and POSTGRES_HOST must be non-empty when STANDALONE=false.',+ 'Set DATABASE_URL, or set non-empty POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and POSTGRES_HOST when STANDALONE=false.',);}return buildPostgresConnectionString({@@ -434,8 +441,8 @@ export type DistributedServerConfiguration = SharedServerConfiguration & {*/STANDALONE: false;/**- * Postgres connection string derived from `POSTGRES_*` (not read from env directly).- * Form: `postgres://USER:PASSWORD@HOST:PORT/DB` with user/password URL-encoded.+ * Postgres connection string. Env: `DATABASE_URL` when set; otherwise built from `POSTGRES_*`.+ * Form: `postgres://USER:PASSWORD@HOST:PORT/DB` (or `postgresql://…`) with user/password URL-encoded.*/DATABASE_URL: string;/** Max connections in the `pg` Pool. Env: `DATABASE_POOL_MAX`. Default 10. */diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex f007777d0..00ad637fe 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -44,6 +44,9 @@ importers:prettier-plugin-organize-imports:specifier: ^4.3.0version: 4.3.0([email protected])([email protected])+ railway:+ specifier: ^3.11.0+ version: 3.11.0typescript:specifier: ~5.9.3version: 5.9.3@@ -1628,6 +1631,11 @@ packages:'@floating-ui/[email protected]':resolution: {integrity: sha512-HpCo8tmWzLVad5s2d19EhAz5zqrrQ6s69qd6moPMQvkOuSwDT1YgRfWSVuc4ennqrgv3OHppiOGMQ7oC13yIww==}+ '@graphql-typed-document-node/[email protected]':+ resolution: {integrity: sha512-mB9oAsNCm9aM3/SOv4YtBMqZbYj10R7dkq8byBqxGY/ncFwhf2oQzMV+LCRlWoDSEBJ3COiR1yeDvMtsoOsuFQ==}+ peerDependencies:+ graphql: ^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0+'@grpc/[email protected]':resolution: {integrity: sha512-k9Dj3DV/itK9D06Y8f190Qgop7/Ui+D0njFV3LHMPwPT75DpXLQohE9Wmz0QElrJnzsjB7KPWiKJbOl7IPDArQ==}engines: {node: '>=12.10.0'}@@ -6372,6 +6380,11 @@ packages:'@types/react-dom':optional: true+ resolution: {integrity: sha512-ehLFHCxV+gITWeBlIVaXulXaVRg4LCxqm0bq64iXSwYL1DESd0pUeLYMP/BMBhnZWeFFBYyJCREaq+Nka7Wgmw==}+ engines: {node: '>=22'}+ hasBin: true+resolution: {integrity: sha512-hek2mFQpPuI4E1BBKrSto+BU3e3x4xuarsbiwr3+lf7p44juvFMV0XFWQAP3xUyqXA4RrXLIoaSUGbSt056ZMw==}engines: {node: '>= 0.6'}@@ -8668,6 +8681,10 @@ snapshots:'@floating-ui/[email protected]': {}+ '@graphql-typed-document-node/[email protected]([email protected])':+ dependencies:+ graphql: 16.14.2+'@grpc/[email protected]':dependencies:'@grpc/proto-loader': 0.8.1@@ -14154,6 +14171,12 @@ snapshots:'@types/react': 19.2.18'@types/react-dom': 19.2.5(@types/[email protected])+ dependencies:+ '@graphql-typed-document-node/core': 3.2.0([email protected])+ graphql: 16.14.2+ tsx: 4.23.12+