Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Standalone mode for `npx @truefoundry/utils` (#47)

Chirag Jain2946f690bd58
diff --git a/.github/workflows/generate-sdk.yaml b/.github/workflows/generate-sdk.yaml
index 3b6719869..f3b1eef79 100644
--- a/.github/workflows/generate-sdk.yaml
+++ b/.github/workflows/generate-sdk.yaml
@@ -62,7 +62,7 @@ jobs:
run: pnpm --filter @truefoundry/utils-core build
- name: Write OpenAPI document
- run: pnpm --filter @truefoundry/server openapi:write
+ run: pnpm --filter @truefoundry/utils openapi:write
# Generation and its Docker pull are the slow part, so skip everything below
# when neither the document nor the generator config moved.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a37a53019..da8598f72 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -21,15 +21,17 @@ jobs:
registry-url: https://registry.npmjs.org
# OIDC trusted publishing requires npm >= 11.5.1; node 22 bundles npm 10.x.
+ # npm 11 also refuses prerelease publishes without an explicit --tag.
- run: npm install -g npm@latest
- run: pnpm install --frozen-lockfile
- run: pnpm build
- run: pnpm test
- # Guard: tag must match package.json version.
- # npm publishes what's in package.json, not the tag name.
- - name: Verify tag matches package version
+ # Guard: git tag must match @truefoundry/utils-core (library is the version authority).
+ # npm publishes what's in package.json, not the tag name. @truefoundry/utils may
+ # use an independent version; bump it in the same release PR when the app changes.
+ - name: Verify tag matches utils-core version
working-directory: packages/harness
run: |
PKG_VERSION="v$(node -p "require('./package.json').version")"
@@ -38,9 +40,8 @@ jobs:
exit 1
fi
- # Publish from the staged dist/: dist/package.json is
- # generated by the build with dist-relative paths, so the tarball root is
- # the compiled file tree and deep imports have no dist/ segment.
+ # Library first: utils pins workspace:* → this concrete version on publish.
+ # Prereleases (e.g. 0.1.9-rc.1) must pass --tag (npm 11); first preid → dist-tag (rc).
- name: Publish @truefoundry/utils-core
working-directory: packages/harness/dist
run: |
@@ -56,3 +57,14 @@ jobs:
fi
# TODO(oss): add --provenance once the repo is public. Do NOT add it now:
# provenance publicly attests the source repo and commit.
+
+ # TODO: Publish @truefoundry/utils
+
+ # # Root build copies FE into packages/server/dist/_frontend; refuse an API-only tarball.
+ # - name: Verify packaged UI is present
+ # run: |
+ # test -f packages/server/dist/cli.js
+ # test -f packages/server/dist/_frontend/index.html
+
+ # App + CLI from package root (dist/ includes dist/_frontend/).
+ # pnpm publish rewrites workspace:* deps to the utils-core version just published.
diff --git a/.gitignore b/.gitignore
index e3127999c..feb8fbc1d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,7 +4,6 @@ dist/
.DS_Store
*.log
.env
-packages/server/registry/
coverage/
.turbo/
*.tsbuildinfo
diff --git a/Dockerfile b/Dockerfile
index 2117e6353..d6c6047ed 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,6 +1,6 @@
# syntax=docker/dockerfile:1
#
-# Multi-stage build for @truefoundry/server, which also serves the UI: the only image the stack needs.
+# Multi-stage build for @truefoundry/utils, which also serves the UI: the only image the stack needs.
#
# Lives at the repository root because the build needs the whole pnpm workspace
# as its context: the server depends on the workspace package @truefoundry/utils-core.
@@ -45,10 +45,10 @@ COPY packages/harness/src/core/sandbox/scripts packages/harness/src/core/sandbox
# ---------------------------------------------------------------------------
FROM workspace AS builder
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
- pnpm install --frozen-lockfile --offline --filter @truefoundry/server...
+ pnpm install --frozen-lockfile --offline --filter @truefoundry/utils...
COPY packages/harness packages/harness
COPY packages/server packages/server
-RUN pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/server build
+RUN pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/utils build
# ---------------------------------------------------------------------------
# frontend-builder: build the UI the server serves (parallel to builder above).
@@ -71,7 +71,7 @@ RUN pnpm --filter frontend build
# ---------------------------------------------------------------------------
FROM workspace AS prod-deps
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
- pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/server...
+ pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/utils...
# ---------------------------------------------------------------------------
# runner: minimal image with prod node_modules + built artifacts.
@@ -88,16 +88,16 @@ COPY --from=prod-deps /app/packages/server/node_modules ./packages/server/node_m
COPY --from=builder /app/packages/harness/package.json ./packages/harness/package.json
COPY --from=builder /app/packages/harness/dist ./packages/harness/dist
-# Built server.
+# Built server (JS). UI is copied below from the parallel frontend stage into
+# dist/_frontend — same path as the npm tarball / `pnpm build` copy step.
COPY --from=builder /app/packages/server/package.json ./packages/server/package.json
COPY --from=builder /app/packages/server/dist ./packages/server/dist
-
-# The UI, at an absolute path so it resolves from any working directory.
-COPY --from=frontend-builder /app/packages/frontend/dist ./packages/frontend/dist
-ENV FRONTEND_DIR=/app/packages/frontend/dist
+# Frontend builds in a parallel stage; place it at the same path as the npm tarball.
+COPY --from=frontend-builder /app/packages/frontend/dist ./packages/server/dist/_frontend
WORKDIR /app/packages/server
EXPOSE 8790
+# Launch-only (matches root `pnpm start` / `standalone:start`). Image already contains dist.
CMD ["node", "dist/main.js"]
diff --git a/README.md b/README.md
index 09ff28ccc..f3de21993 100644
--- a/README.md
+++ b/README.md
@@ -1,103 +1,121 @@
-# TrueFoundry harness workspace
+# TrueForge
-pnpm workspace with:
+TrueForge is an open-source agent harness: the runtime layer that turns an LLM into a working agent. It runs the execution loop — model calls, tool use, context, and session state — and exposes the result as a chat UI, an HTTP API, and a TypeScript library.
-| Package | Path | Role |
-| ------------------------- | ---------------------------------------- | ------------------------------------------------------ |
-| `@truefoundry/utils-core` | [`packages/harness`](packages/harness) | Published library (`core` + `agent-session`) |
-| `@truefoundry/server` | [`packages/server`](packages/server) | HTTP server + UI host (private; depends on utils-core) |
-| `frontend` | [`packages/frontend`](packages/frontend) | Private draft-only agent chat UI (not published) |
+Out of the box you get multi-turn sessions with streaming, MCP tool servers (including OAuth), skills, sandboxed code execution, human-in-the-loop approvals, and subagents. Configure providers in the UI or via the settings APIs; run as a single process on SQLite, or scale out with Postgres and Redis.
-## Development
+> Note: Package and folder names will be renamed soon to match the release names below. They have been intentionally named "utils" to not leak before announcement.
+
+| Package | Release Name | Path | What it is |
+| ------------------------- | ----------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
+| `@truefoundry/utils` | `@truefoundry/trueforge` | `[packages/server](packages/server)` | Agent server + bundled UI |
+| `@truefoundry/utils-core` | `@truefoundry/trueforge-core` | `[packages/harness](packages/harness)` | Library: agent core, sessions, and streaming |
+| `trueharness` | `@truefoundry/trueforge-sdk` | `[packages/sdk](packages/sdk)` | Generated TypeScript SDK |
+| `frontend` | — | `[packages/frontend](packages/frontend)` | Chat UI (bundled into the server; not published on its own) |
-The API and frontend run on the host with hot reload. Postgres and Redis run in Docker.
+Requires **Node.js 22.13+** and **pnpm**.
-### One-time setup
+## Run from source
```bash
pnpm install
cp packages/server/.env.example packages/server/.env
```
-Fill in any required secrets in `packages/server/.env`. The copied defaults already connect the host server to the Compose services.
-
-### Day-to-day
+### Standalone (local, zero infra)
-Terminal 1:
+SQLite only — good for trying the product or single-process use.
```bash
-pnpm dev:infra # Postgres + Redis (data in ./data/dev/postgres); Ctrl+C stops them
+pnpm standalone:dev
```
-Terminal 2:
-
-```bash
-pnpm dev # API on :8790 and Vite on :3000
-```
+- UI (Vite): [http://localhost:3000](http://localhost:3000) — proxies `/api/*` to the API
+- API: [http://localhost:8790](http://localhost:8790)
-Open `http://localhost:3000`. Frontend changes update through Vite HMR; server changes automatically restart the API on `:8790`. Vite proxies `/api/*` to the API. Local server scripts resolve `@truefoundry/utils-core` from source (`exports.development`), so a utils-core `dist/` build is not required for `pnpm dev`. For drain testing without server hot reload, use `pnpm dev:no-watch` instead of `pnpm dev`.
+### Multi-replica (Postgres + Redis)
-The workspace utils-core package is ESM so the host server and source schemas share one ESM dependency graph. `NODE_OPTIONS=--conditions=development` selects `src/` at runtime, and TypeScript uses the same condition for source-based static analysis. Development, lint, typecheck, tests, OpenAPI generation, and migrations do not read or recreate `packages/harness/dist`; release builds, package checks, and Docker smoke tests create it intentionally.
+Use this when you need more than one server process (cancels and turn streams peer over Redis).
-Server dev scripts regenerate the embedded sandbox Python helpers before startup. Root `pnpm dev` also watches those Python files, regenerates the TypeScript source module after edits, and lets the server watcher restart normally. Neither path builds `dist`.
+Terminal 1 — start Postgres (`:5432`) and Redis (`:6379`):
-| Script | Runs |
-| ------------------- | ---------------------------------------------------------------------------------- |
-| `pnpm dev:infra` | Postgres + Redis in the foreground |
-| `pnpm dev` | Sandbox helper generator + server (`tsx watch`) + Vite |
-| `pnpm dev:no-watch` | Same, but API without hot reload (`NODE_ENV=production`) so Ctrl+C exercises drain |
-| `pnpm clean` | Workspace build outputs and the ESLint cache |
-| `pnpm clean:all` | The same outputs plus all workspace `node_modules` directories |
+```bash
+pnpm dev:infra
+```
-Migrations run automatically on server startup. To migrate without starting HTTP:
+Terminal 2:
```bash
-pnpm --filter @truefoundry/server migrate
+pnpm dev
```
-Workspace checks:
+- UI (Vite): [http://localhost:3000](http://localhost:3000) — proxies `/api/*` to the API
+- API: [http://localhost:8790](http://localhost:8790)
+
+| | Standalone | Multi-replica |
+| --------- | -------------------------------------- | ----------------------------------------------- |
+| Process | One server | One or more replicas with Redis peering |
+| Database | SQLite | Postgres |
+| Infra | None | Postgres + Redis (`pnpm dev:infra` or your own) |
+| Dev | `pnpm standalone:dev` | `pnpm dev` (after infra) |
+| Prod-like | `pnpm build` → `pnpm standalone:start` | `pnpm build` → `pnpm start` |
+
+Migrations run on server startup. To run Postgres migrations without starting HTTP:
```bash
-pnpm build
-pnpm test
-pnpm typecheck
+pnpm --filter @truefoundry/utils migrate
```
-Root `build` / `typecheck` (and CI) include utils-core, server, and frontend. `FRONTEND_PORT` moves Vite off `:3000`, `VITE_SERVER_URL` points it at another API. See [`packages/frontend/README.md`](packages/frontend/README.md).
+That script sets `STANDALONE=false` and uses `POSTGRES_*` from `packages/server/.env`. It will not run in standalone mode (SQLite migrations happen on boot instead).
-## Serving the UI from the server
+### Serving the UI from the server
-Deployments are one process on one origin: `/api/*` (including `/api/v1/docs` and `/api/v1/openapi.json`) and
-`/healthz` are the API, everything else resolves to the UI. `FRONTEND_DIR` points at the build (default
-`../frontend/dist`; the image sets an absolute path). It is not required: with no build there the server
-logs a warning and serves the API only, which is what running the server behind Vite needs.
+Dev and production-like runs use different process topologies. Standalone vs multi-replica only changes storage/peering (`STANDALONE`); it does not change how the UI is served.
-## Docker Compose smoke test
+**Development** — `pnpm standalone:dev` / `pnpm dev` run two processes in parallel: Vite (UI, with live reload) and the Hono API. The browser talks to Vite; Vite proxies `/api/`* to Hono.
-Full stack in containers — built server image serves API + UI (no Vite HMR):
+```
+ browser Vite (:3000) Hono (:8790)
+ │ │ │
+ │ GET / (UI) │ │
+ │────────────────────────────>│ │
+ │ │ │
+ │ /api/* │ proxy │
+ │────────────────────────────>│─────────────────────────────>│
+```
-```bash
-pnpm smoke # build, wait for healthy services, then check /healthz and the UI app shell
-pnpm smoke:down # stop the stack
+**Production-like** — after `pnpm build`, `pnpm standalone:start` / `pnpm start` run a single Hono process. It serves the built frontend bundle for non-API routes and handles `/api/`* itself. The Docker container works the same way: one process, one origin.
+
+```
+ browser Hono (:8790)
+ │ │
+ │ GET / (static UI from dist/_frontend) │
+ │───────────────────────────────────────────>│
+ │ │
+ │ /api/* │
+ │───────────────────────────────────────────>│
```
-Open `http://localhost:8791`. Secrets and Postgres credentials come from `packages/server/.env`. Host ports and in-network DB/Redis targets are fixed in Compose so they do not collide with development: Postgres `:5433`, Redis `:6380`, app `:8791` (vs `pnpm dev:infra` on `:5432`/`:6379` and `pnpm dev` on `:8790`/`:3000`).
+Open the UI on `:3000` in dev, or on the API port (`:8790`) when the server is serving the bundle.
-Requires `packages/server/.env`. `.env` and `data/` are gitignored. Development infra stores Postgres under `./data/dev/postgres`.
+## Configuration
-## SDK generation
+Model providers, MCP servers, skills, and sandboxes are configured in the UI under **Settings**, or via the settings APIs. Discovery presets come from the `*/catalog` endpoints. Interactive API docs are at `/api/v1/docs`.
-`packages/sdk` and `fern/openapi/openapi.json` are both generated by
-[Fern](https://buildwithfern.com) and committed — edit `packages/server/src/routes/`, never the
-output. [`generate-sdk.yaml`](.github/workflows/generate-sdk.yaml) regenerates them on every change;
-see its comments for the flags if you need to run it by hand (Docker required):
+See `[packages/server/.env.example](packages/server/.env.example)` for every env var.
-```bash
-pnpm openapi:write
-fern check && fern generate --group ts-sdk --version 0.0.0 --local --generate-tests
-```
+Useful overrides:
-## Library imports
+- `PORT` — API port (default `8790`)
+- `FRONTEND_PORT` — Vite UI port in dev (default `3000`); see `[packages/frontend/README.md](packages/frontend/README.md)`
+- `VITE_SERVER_URL` — point the Vite proxy at a different API
+- `FRONTEND_DIR` — directory of a built UI for the server to serve
+- `SQLITE_PATH` — SQLite file location in standalone mode
+- `REDIS_URL` / `POSTGRES_*` — used when `STANDALONE=false`
+
+On one origin (start / Docker): `/api/*` (including OpenAPI) and `/healthz` are the API; everything else is the UI. The server prefers a packaged `dist/_frontend`, then `packages/frontend/dist`. With no UI build present it serves the API only (normal for Vite-backed `pnpm dev`). See [Serving the UI from the server](#serving-the-ui-from-the-server).
+
+## Use as a library
```ts
import { AgentThread } from '@truefoundry/utils-core/core';
@@ -110,6 +128,44 @@ Or namespaced:
import { core, agentSession } from '@truefoundry/utils-core';
```
-Workspace-only `development` exports are removed from the published package. Its staged `dist/package.json` remains CommonJS so `require()` uses `.js`, while ESM consumers use `.mjs`. After switching from `@truefoundry/utils` to `@truefoundry/utils-core`, consumers such as `tfy-llm-gateway` keep the same deep-import and CJS/ESM layout. Consumer compatibility is checked against a packed artifact, including root, barrel, deep skill imports, and both CJS and ESM loading.
+The published package supports both CommonJS and ESM. Server-only dependencies (Hono, SQLite, Postgres, Redis, etc.) stay in `@truefoundry/utils` and are not pulled in by library consumers.
+
+## Development
+
+| Script | Purpose |
+| ---------------------------------------------------- | ----------------------------------------------------- |
+| `pnpm standalone:dev` / `pnpm dev` | Local UI + API (see modes above) |
+| `pnpm standalone:dev:no-watch` / `pnpm dev:no-watch` | Same, but the server does not restart on file changes |
+| `pnpm dev:server:ui` | Packed UI + watched API (no Vite) |
+| `pnpm build` | Build all packages |
+| `pnpm test` / `pnpm typecheck` | Workspace checks |
+| `pnpm smoke` / `pnpm smoke:down` | Full Docker Compose stack |
+| `pnpm clean` / `pnpm clean:all` | Remove build outputs (+ `node_modules` for `:all`) |
+
+Local server scripts resolve `@truefoundry/utils-core` from source, so you do not need a utils-core `dist/` build for `pnpm dev` / `standalone:dev`.
+
+### Smoke test (Docker)
+
+Full stack in containers — built server image serves API + UI. Forces multi-replica mode (`STANDALONE=false`):
+
+```bash
+pnpm smoke # build, wait for healthy services, check /healthz and UI
+pnpm smoke:down
+```
+
+Open [http://localhost:8791](http://localhost:8791). Credentials come from `packages/server/.env`. Host ports differ from local dev so they do not collide: Postgres `:5433`, Redis `:6380`, app `:8791`.
+
+### Entry points
+
+| File | Used by | Role |
+| -------------- | --------------------------------------------- | ------------------------------------------- |
+| `dist/main.js` | Docker, `pnpm start`, `pnpm standalone:start` | Env-only server boot |
+| `dist/cli.js` | `npx @truefoundry/trueforge` | CLI (`--help`, `--port`), then loads `main` |
-Server-only deps (`hono`, `@hono/node-server`, `@hono/swagger-ui`, `yaml`) live in `packages/server` and never reach library consumers.
+### Generated SDK and OpenAPI
+
+`packages/sdk` and `fern/openapi/openapi.json` are generated by [Fern](https://buildwithfern.com) and committed. Edit route handlers under `packages/server/src/routes/`, not the generated output. CI regenerates them; to run locally (Docker required):
+
+```bash
+pnpm sdk:generate
+```
diff --git a/RELEASING.md b/RELEASING.md
index 2c1ae84f2..4fac312d1 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -1,3 +1,22 @@
+# Releasing
+
+Two public packages ship from this repo:
+
+| Package | Source | How it publishes |
+| ------------------------- | ------------------ | --------------------------------------------------------------- |
+| `@truefoundry/utils-core` | `packages/harness` | From staged `packages/harness/dist` (library) |
+| `@truefoundry/utils` | `packages/server` | From package root (`dist/`, including `dist/_frontend/` for UI) |
+
+The git tag `v*` must match **`packages/harness` (`@truefoundry/utils-core`) version**.
+`@truefoundry/utils` may use an independent version — bump it in the same release PR
+whenever the app/CLI changes. CI publishes **core first**, then utils (so
+`workspace:*` rewrites to the core version that just landed on npm).
+
+> **Currently only `@truefoundry/utils-core` publishes.** The `@truefoundry/utils`
+> publish step in `release.yml` is deferred (`TODO`); CI still builds and tests it.
+
+---
+
# Releasing `@truefoundry/utils-core`
Interim setup for the fast development phase: the library in
@@ -32,14 +51,18 @@ root is the compiled file tree. Consequences:
## Per-release flow
-1. **Bump the version via PR** (direct pushes to `main` are blocked by org
+1. **Bump versions via PR** (direct pushes to `main` are blocked by org
ruleset):
```bash
git checkout -b release/v0.x.y
cd packages/harness
- npm version 0.x.y --no-git-tag-version # edits packages/harness/package.json only
- git commit -am "chore: release v0.x.y"
+ npm version 0.x.y --no-git-tag-version # or 0.x.y-rc.N for a prerelease
+ cd ../server
+ npm version 0.x.y --no-git-tag-version # bump when the app/CLI changes; may differ from core
+ cd ../..
+ git add packages/harness/package.json packages/server/package.json
+ git commit -m "chore: release v0.x.y"
git push -u origin release/v0.x.y
```
@@ -49,15 +72,21 @@ root is the compiled file tree. Consequences:
```bash
git checkout main && git pull
- git tag v0.x.y
+ git tag v0.x.y # must equal packages/harness version (e.g. v0.1.9-rc.1)
git push origin v0.x.y
```
3. **CI publishes automatically.** `.github/workflows/release.yml` installs,
- builds (which stages `dist/` with its own package.json and smoke-tests
- it), tests, verifies the tag matches `packages/harness/package.json`, and
- runs `npm publish` **from `packages/harness/dist`** via trusted publishing
- (OIDC — no NPM_TOKEN anywhere). Watch it under the repo's Actions tab.
+ builds, tests, verifies the tag matches `packages/harness/package.json`, then
+ runs `npm publish` **from `packages/harness/dist`**. (The `@truefoundry/utils`
+ publish is deferred — see the note above.)
+
+ Auth is trusted publishing (OIDC — no `NPM_TOKEN`). Watch the repo Actions tab.
+
+ **Dist-tags:** npm 11 requires an explicit `--tag` for prereleases. CI derives
+ it from the semver prerelease id (`0.2.0-rc.1` → `--tag rc`). Stable releases
+ publish to `latest`. Install with `npx @truefoundry/utils@rc` or
+ `@0.2.0-rc.1`; bare `npx @truefoundry/utils` stays on `latest`.
4. **Bump the pinned version in the gateway.** Pin exact versions (no `^`)
during the fast 0.x churn:
@@ -66,25 +95,41 @@ root is the compiled file tree. Consequences:
"@truefoundry/utils-core": "0.x.y"
```
+## Why core must publish before utils
+
+`@truefoundry/utils` depends on `@truefoundry/utils-core: workspace:*`. On
+publish, pnpm rewrites that to the **version in `packages/harness/package.json`**.
+If that core version is missing from npm (or is an older build without exports
+the server imports), `npx @truefoundry/utils` fails at runtime. Always ship
+matching core+utils together when the app uses new core APIs.
+
## Local iteration without publishing
For tight loops, skip the publish round-trip:
```bash
+pnpm clean && pnpm build && pnpm standalone:start
+# or pack only:
cd packages/harness && pnpm build && cd dist && pnpm pack
+cd packages/server && pnpm pack
```
-Point the gateway at the tarball via a `file:` dependency (or use `yalc`).
+Point consumers at a tarball via a `file:` dependency (or use `yalc`).
Publish a real version when CI or teammates need it.
## Troubleshooting
+- **Publish fails requiring a tag**: prerelease versions need `--tag` (npm 11).
+ CI handles this; for local publishes use e.g. `pnpm publish --tag rc`.
- **Publish fails with 403/E403**: version already published (npm versions
are immutable — bump and re-tag), or the trusted publisher config doesn't
match the workflow filename/repo exactly.
- **Tag/version mismatch failure**: the guard step caught a tag that doesn't
match `packages/harness/package.json`. Delete the tag
(`git push origin :refs/tags/vX.Y.Z`), fix the version via PR, re-tag.
+- **Missing `dist/_frontend/index.html`**: root `pnpm build` must build
+ `frontend` before `@truefoundry/utils`; the release job fails closed if the
+ copy is absent.
- **OIDC/auth error in the publish step**: trusted publishing requires
npm >= 11.5.1; the workflow upgrades npm globally before publishing —
check that step ran.
diff --git a/docker-compose.yml b/docker-compose.yml
index e10d42eeb..404617139 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,7 +1,7 @@
# Full-stack smoke test. Reads packages/server/.env for secrets and
# credentials; host ports and in-network DB/Redis targets are opinionated here
# so they do not collide with or inherit host-dev values.
-name: harness
+name: trueforge
services:
postgres:
@@ -54,9 +54,9 @@ services:
POSTGRES_HOST: postgres
POSTGRES_PORT: 5432
# Compose runs one replica but keeps peering on so the peered cancel path
- # stays exercised in development. A single-process deployment can set this
- # to true and drop the redis service entirely.
- SINGLE_BINARY: 'false'
+ # stays exercised. STANDALONE=false ⇒ Postgres + Redis.
+ # A single-process deployment can set STANDALONE=true and drop redis.
+ STANDALONE: 'false'
REDIS_URL: redis://redis:6379
# Secrets and Postgres credentials (POSTGRES_USER, …).
# `environment` above overrides any colliding keys from this file.
diff --git a/package.json b/package.json
index e708c3acc..df5683153 100644
--- a/package.json
+++ b/package.json
@@ -6,32 +6,34 @@
"node": ">=22.13.0"
},
"scripts": {
- "build": "pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/server build && pnpm --filter frontend build",
- "clean": "node scripts/clean.mjs",
+ "build": "pnpm --filter @truefoundry/utils-core build && pnpm --filter frontend build && pnpm --filter @truefoundry/utils build",
"clean:all": "node scripts/clean.mjs --dependencies",
- "typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/server typecheck && pnpm --filter frontend typecheck",
- "lint": "eslint . --fix --cache --cache-location .eslintcache",
- "lint:ci": "eslint . --cache --cache-location .eslintcache",
- "format": "prettier --write . --cache --config .prettierrc",
+ "clean": "node scripts/clean.mjs",
+ "dev": "STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/utils --filter frontend dev",
+ "dev:no-watch": "STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/utils --filter frontend dev:no-watch",
+ "dev:infra": "docker compose -f docker-compose.dev.yml up",
+ "dev:server:ui": "pnpm --filter frontend build && pnpm --filter @truefoundry/utils build:frontend-assets && STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/utils dev",
+ "standalone:dev": "STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/utils --filter frontend dev",
+ "standalone:dev:no-watch": "STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/utils --filter frontend dev:no-watch",
+ "start": "STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/utils start",
+ "standalone:start": "STANDALONE=true NODE_ENV=production pnpm --filter @truefoundry/utils start",
"format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,md}\" --cache --error-on-unmatched-pattern --config .prettierrc",
"format:fix": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\" --cache --config .prettierrc",
- "test": "pnpm --filter @truefoundry/utils-core test && pnpm --filter @truefoundry/server test && pnpm --filter frontend test",
- "test:store:local": "bash scripts/test-store-local.sh",
- "dev": "pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/server --filter frontend dev",
- "dev:no-watch": "pnpm --parallel --filter @truefoundry/server --filter frontend dev:no-watch",
- "dev:infra": "docker compose -f docker-compose.dev.yml up",
- "dev:server": "pnpm --filter @truefoundry/server dev",
- "dev:frontend": "pnpm --filter frontend dev",
- "dev:server:ui": "pnpm --filter frontend build && pnpm dev:server",
- "smoke": "docker compose up --build --wait && node -e \"Promise.all([fetch('http://127.0.0.1:8791/healthz'), fetch('http://127.0.0.1:8791/')]).then(async ([health, ui]) => { if (!health.ok) throw new Error('healthz returned ' + health.status); const html = await ui.text(); if (!ui.ok || !html.includes('id=\\\"root\\\"')) throw new Error('UI did not return its app shell'); console.log('healthz and UI OK'); })\"",
- "smoke:down": "docker compose down",
- "openapi:write": "pnpm --filter @truefoundry/server openapi:write",
+ "format": "prettier --write . --cache --config .prettierrc",
+ "lint:ci": "eslint . --cache --cache-location .eslintcache",
+ "lint": "eslint . --fix --cache --cache-location .eslintcache",
+ "openapi:write": "pnpm --filter @truefoundry/utils openapi:write",
+ "pack:dry": "pnpm --filter @truefoundry/utils-core pack:dry && pnpm --filter @truefoundry/utils pack:dry",
+ "postinstall": "pnpm --filter @truefoundry/utils-core build:gen",
+ "prepare": "husky || true",
"sdk:generate": "bash scripts/generate-sdk.sh",
- "ui:shot": "node ui-shots/shot.mjs",
+ "smoke:down": "docker compose down",
+ "smoke": "docker compose up --build --wait && node -e \"Promise.all([fetch('http://127.0.0.1:8791/healthz'), fetch('http://127.0.0.1:8791/')]).then(async ([health, ui]) => { if (!health.ok) throw new Error('healthz returned ' + health.status); const html = await ui.text(); if (!ui.ok || !html.includes('id=\\\"root\\\"')) throw new Error('UI did not return its app shell'); console.log('healthz and UI OK'); })\"",
+ "test:store:local": "bash scripts/test-store-local.sh",
+ "test": "pnpm --filter @truefoundry/utils-core test && pnpm --filter @truefoundry/utils test && pnpm --filter frontend test",
+ "typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/utils typecheck && pnpm --filter frontend typecheck",
"ui:clean": "node ui-shots/clean.mjs",
- "pack:dry": "pnpm --filter @truefoundry/utils-core pack:dry",
- "postinstall": "pnpm --filter @truefoundry/utils-core build:gen",
- "prepare": "husky || true"
+ "ui:shot": "node ui-shots/shot.mjs"
},
"devDependencies": {
"@eslint-react/eslint-plugin": "^5.18.0",
diff --git a/packages/frontend/README.md b/packages/frontend/README.md
index 1df57b937..58cd102a9 100644
--- a/packages/frontend/README.md
+++ b/packages/frontend/README.md
@@ -19,12 +19,14 @@ No login is required.
## Local development
-For the full host workflow (Compose Postgres/Redis, then API + Vite), see the root
-[`README.md`](../../README.md#development).
+For the full host workflow (standalone or non-standalone), see the root
+[`README.md`](../../README.md).
```bash
-pnpm dev # API on :8790 and Vite on :3000 together (after `pnpm dev:infra`)
-pnpm dev:frontend # or Vite alone, against an API that is already up
+pnpm standalone:dev # zero-env: SQLite, Vite :3000 + API :8790
+# or:
+pnpm dev:infra # then in another terminal:
+pnpm dev # Postgres + Redis, Vite :3000 + API :8790
```
Open `http://localhost:3000`: Vite serves the UI from source (edits hot-reload, no rebuild or server
diff --git a/packages/harness/package.json b/packages/harness/package.json
index c3623fe70..440f2f118 100644
--- a/packages/harness/package.json
+++ b/packages/harness/package.json
@@ -69,9 +69,9 @@
"dist"
],
"scripts": {
- "build": "pnpm run build:gen && tsc --noEmit && pnpm run build:js && pnpm run build:dts && pnpm run build:pkg && pnpm run build:check",
"build:gen": "node scripts/generate-sandbox-scripts.mjs",
"build:gen:watch": "node --watch-path=src/core/sandbox/scripts scripts/generate-sandbox-scripts.mjs",
+ "build": "pnpm run build:gen && tsc --noEmit && pnpm run build:js && pnpm run build:dts && pnpm run build:pkg && pnpm run build:check",
"dev": "pnpm run build:gen:watch",
"build:js": "tsup",
"build:dts": "tsc -p tsconfig.build.json --emitDeclarationOnly",
diff --git a/packages/server/.env.example b/packages/server/.env.example
index 0741ec09f..e362b144b 100644
--- a/packages/server/.env.example
+++ b/packages/server/.env.example
@@ -3,6 +3,11 @@
#
# Copy to .env and fill in the values. The server validates all of these at
# startup and refuses to boot on any invalid value (bad JSON, bad URL, etc.).
+#
+# Topology (STANDALONE) and NODE_ENV are set by root pnpm scripts
+# (`pnpm dev`, `pnpm standalone:dev`, `pnpm start`, …). Those process env
+# values win over this file. Uncomment STANDALONE below only when running the
+# server package directly (e.g. `node dist/main.js` or `tsx src/main.ts`).
# ---------------------------------------------------------------------------
# HTTP port the server listens on. Optional, defaults to 8790.
@@ -24,22 +29,27 @@ PORT=8790
# When unset, the catalog inlined at build time (src/catalog/sandbox-catalog.yaml) is used.
# SANDBOX_CATALOG_PATH=/path/to/sandbox-catalog.yaml
-# Frontend build the server serves alongside the API. Optional, defaults to
-# ../frontend/dist relative to the working directory. With no build there the
-# server logs a warning and serves the API only.
-# FRONTEND_DIR=../frontend/dist
+# Frontend build the server serves alongside the API. Optional; defaults to
+# packages/server/dist/_frontend (after build) or monorepo packages/frontend/dist.
+# With no build there the server logs a warning and serves the API only.
+# FRONTEND_DIR=/absolute/path/to/frontend/dist
+
+# Deployment topology: single process (true, default) uses SQLite and
+# disables Redis/executor peering; false uses Postgres + Redis so cancels
+# that land on the wrong replica still work. Prefer root scripts
+# (`pnpm standalone:*` vs `pnpm dev` / `pnpm start`) over setting this here.
+# STANDALONE=false
-# Declares the deployment topology. true (the default) asserts exactly one
-# server process: Redis is never contacted and REDIS_URL is ignored even if set.
-# Set it to false before running more than one replica, otherwise a cancel that
-# lands on the wrong replica silently stops nothing.
-SINGLE_BINARY=true
+# Absolute path to the SQLite database file. Used when STANDALONE=true;
+# defaults to the OS data dir from env-paths (app name "truefoundry-utils"):
+# macOS: ~/Library/Application Support/truefoundry-utils/db.sqlite
+# Linux: ~/.local/share/truefoundry-utils/db.sqlite
+# Windows: %LOCALAPPDATA%\truefoundry-utils\Data\db.sqlite
+# SQLITE_PATH=
-# Required when SINGLE_BINARY=false, ignored otherwise. Redis connection URL
-# shared by all server replicas; carries executor peering so a cancel that lands
-# on one replica reaches the replica running the turn. Use localhost for host
-# `pnpm dev`; `docker-compose.yml` overrides this to redis://redis:6379 for the
-# server container.
+# Used when STANDALONE=false (ignored in standalone). Redis connection URL for
+# executor peering. Defaults to redis://localhost:6379 if unset.
+# `docker-compose.yml` overrides this to redis://redis:6379 for the server container.
REDIS_URL=redis://localhost:6379
# Resumable turn stream settings. All are optional.
@@ -51,11 +61,12 @@ REDIS_URL=redis://localhost:6379
# TURN_SUBSCRIBE_TIMEOUT_MS=600000
# ---------------------------------------------------------------------------
-# MCP OAuth (DCR). PUBLIC_BASE_URL is required — origin of the fixed callback route
-# {PUBLIC_BASE_URL}/api/v1/mcp-servers/oauth/callback (not trimmed). OAUTH_CLIENT_NAME is
-# the RFC 7591 client_name on the consent screen (default: truefoundry-harness).
+# MCP OAuth (DCR). PUBLIC_BASE_URL is the origin of the fixed callback route
+# {PUBLIC_BASE_URL}/api/v1/mcp-servers/oauth/callback (not trimmed). Optional;
+# defaults to http://localhost:${PORT}. OAUTH_CLIENT_NAME is the RFC 7591
+# client_name on the consent screen (default: truefoundry-harness).
# ---------------------------------------------------------------------------
-PUBLIC_BASE_URL=http://localhost:8790
+# PUBLIC_BASE_URL=http://localhost:8790
# OAUTH_CLIENT_NAME=truefoundry-harness
# ---------------------------------------------------------------------------
@@ -69,8 +80,9 @@ PUBLIC_BASE_URL=http://localhost:8790
# SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD=20971520
# ---------------------------------------------------------------------------
-# Postgres (required). Used by the server pool and by Compose postgres
-# services (via env_file). Keep localhost here for host `pnpm dev`;
+# Postgres (used when STANDALONE=false; also read by Compose postgres
+# services via env_file). Config defaults match these values if unset.
+# Keep localhost here for host `pnpm dev`;
# `docker-compose.yml` overrides POSTGRES_HOST/PORT for the server container.
# ---------------------------------------------------------------------------
POSTGRES_USER=harness
diff --git a/packages/server/.env.test b/packages/server/.env.test
index 442731292..b7d1080f3 100644
--- a/packages/server/.env.test
+++ b/packages/server/.env.test
@@ -1,4 +1,5 @@
# Dummy values so config.ts loads in unit tests; no service is contacted.
+# STANDALONE defaults to true → SQLite (Postgres env below is unused).
POSTGRES_USER=test
POSTGRES_PASSWORD=test
POSTGRES_DB=test
diff --git a/packages/server/package.json b/packages/server/package.json
index 8ca71ea23..d72857162 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,28 +1,35 @@
{
- "name": "@truefoundry/server",
- "version": "0.1.0",
- "description": "TrueFoundry agent server (CLI/HTTP). Not published yet.",
+ "name": "@truefoundry/utils",
+ "version": "0.2.0-rc.2",
+ "description": "TrueFoundry agent server + UI (npx @truefoundry/utils)",
"author": "Truefoundry",
"license": "UNLICENSED",
- "private": true,
+ "private": false,
"type": "module",
+ "bin": "./dist/cli.js",
+ "files": [
+ "dist"
+ ],
"scripts": {
- "build:gen": "node scripts/generate-catalog.mjs",
+ "build:frontend-assets": "node scripts/copy-frontend.mjs",
"build:gen:watch": "node --watch-path=src/catalog/model-catalog.yaml --watch-path=src/catalog/mcp-catalog.yaml --watch-path=src/catalog/skill-catalog.yaml --watch-path=src/catalog/sandbox-catalog.yaml scripts/generate-catalog.mjs",
- "build": "pnpm run build:gen && tsc --noEmit && tsup",
- "predev": "pnpm --filter @truefoundry/utils-core build:gen && pnpm run build:gen",
- "dev": "pnpm run \"/^(catalog-watch|dev:serve)$/\"",
- "catalog-watch": "pnpm run build:gen:watch",
+ "build:gen": "node scripts/generate-catalog.mjs",
+ "build:clean": "rm -rf dist",
+ "build": "pnpm run build:gen && tsc --noEmit && pnpm run build:clean && tsup && chmod +x dist/cli.js && pnpm run build:frontend-assets",
"dev:serve": "NODE_OPTIONS='--conditions=development' NODE_ENV=development tsx watch --env-file=.env src/main.ts",
- "predev:no-watch": "pnpm --filter @truefoundry/utils-core build:gen && pnpm run build:gen",
- "dev:no-watch": "NODE_OPTIONS='--conditions=development' NODE_ENV=production tsx --env-file=.env src/main.ts",
- "migrate": "NODE_OPTIONS='--conditions=development' tsx --env-file=.env src/db/postgres/migrate-cli.ts",
- "typecheck": "pnpm run build:gen && tsc --noEmit && tsc --noEmit -p tests/db/tsconfig.json && tsc --noEmit -p tests/unit/tsconfig.json",
+ "dev": "pnpm run \"/^(build:gen:watch|dev:serve)$/\"",
+ "dev:no-watch": "NODE_OPTIONS='--conditions=development' NODE_ENV=development tsx --env-file=.env src/main.ts",
+ "start": "NODE_ENV=production node --env-file=.env dist/main.js",
+ "migrate": "NODE_OPTIONS='--conditions=development' STANDALONE=false tsx --env-file=.env src/db/postgres/migrate-cli.ts",
"openapi:write": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' tsx --env-file=.env.test scripts/write-openapi.ts",
- "test": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.unit.config.cjs",
+ "pack:dry": "pnpm pack --dry-run",
+ "predev:no-watch": "pnpm --filter @truefoundry/utils-core build:gen && pnpm run build:gen",
+ "predev": "pnpm --filter @truefoundry/utils-core build:gen && pnpm run build:gen",
+ "test:eventsub": "jest --config jest.eventsub.config.cjs",
"test:store:postgres": "jest --config jest.store.postgres.config.cjs",
"test:store:sqlite": "jest --config jest.store.sqlite.config.cjs",
- "test:eventsub": "jest --config jest.eventsub.config.cjs"
+ "test": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.unit.config.cjs",
+ "typecheck": "pnpm run build:gen && tsc --noEmit && tsc --noEmit -p tests/db/tsconfig.json && tsc --noEmit -p tests/unit/tsconfig.json"
},
"dependencies": {
"@daytona/sdk": "^0.190.0",
@@ -32,6 +39,7 @@
"@modelcontextprotocol/sdk": "^1.29.0",
"@truefoundry/utils-core": "workspace:*",
"better-sqlite3": "^13.0.2",
+ "env-paths": "^4.0.0",
"hono": "^4.12.34",
"kysely": "^0.29.4",
"pg": "^8.22.0",
diff --git a/packages/server/scripts/copy-frontend.mjs b/packages/server/scripts/copy-frontend.mjs
new file mode 100644
index 000000000..4453dad1c
--- /dev/null
+++ b/packages/server/scripts/copy-frontend.mjs
@@ -0,0 +1,26 @@
+/**
+ * Copies the monorepo frontend build into `dist/_frontend` so the published
+ * `@truefoundry/utils` tarball (and local `node dist/main.js` / `pnpm start`) can serve the UI
+ * from next to the server bundle. Cleared by `pnpm clean` with the rest of dist/.
+ *
+ * Root `pnpm build` builds frontend before this package; a missing source only
+ * skips (Docker builder builds frontend in a parallel stage).
+ */
+import { cpSync, existsSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const source = path.resolve(packageRoot, '../frontend/dist');
+const destination = path.join(packageRoot, 'dist', '_frontend');
+
+if (!existsSync(path.join(source, 'index.html'))) {
+ console.warn(
+ `Skipping frontend copy: no build at ${source}. Run \`pnpm --filter frontend build\` first for a UI-capable package.`,
+ );
+ process.exit(0);
+}
+
+rmSync(destination, { recursive: true, force: true });
+cpSync(source, destination, { recursive: true });
+console.log(`Copied frontend build to ${destination}`);
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 3e1d83f50..b3268309b 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -47,18 +47,18 @@ function routeNotFound(c: Context) {
export interface ServerDeps {
modelCatalog: ModelCatalog;
- modelProviderStore: IModelProviderStore;
mcpCatalog: McpCatalog;
+ skillCatalog: SkillCatalog;
+ sandboxCatalog: SandboxCatalog;
+ modelProviderStore: IModelProviderStore;
mcpServerStore: IMcpServerStore;
tokenStore: IOAuthTokenStore;
- skillCatalog: SkillCatalog;
skillStore: ISkillStore;
- sandboxCatalog: SandboxCatalog;
sandboxProviderStore: ISandboxProviderStore;
sessionStore: ISessionStore;
sessions: Sessions;
activeTurns: ActiveTurnRegistry;
- /** Primary Redis client (server-owned); undefined in single-binary mode. */
+ /** Primary Redis client (server-owned); undefined in standalone mode. */
redis?: RedisClientType | undefined;
/** Request-reply dispatch table served by this replica's executor. */
requestReplyRouter: RequestReplyRouter;
diff --git a/packages/server/src/cli.ts b/packages/server/src/cli.ts
new file mode 100644
index 000000000..c800a71dd
--- /dev/null
+++ b/packages/server/src/cli.ts
@@ -0,0 +1,59 @@
+/**
+ * CLI entry for `@truefoundry/utils` (`package.json` `bin` → `dist/cli.js`).
+ *
+ * Kept separate from `main.ts` so Docker / `pnpm start` can boot with env only
+ * (`node dist/main.js`), while `npx @truefoundry/utils` gets a shebang, `--help`,
+ * and `--port`. Flags must be applied before importing `./main` because config
+ * reads `process.env` at module load.
+ *
+ * Topology defaults from env / config (`STANDALONE=true` unless set): standalone
+ * uses SQLite with no Redis; `STANDALONE=false` uses Postgres + Redis peering.
+ */
+import { parseArgs } from 'node:util';
+
+function printUsage(): void {
+ console.log(`Usage:
+ npx @truefoundry/utils
+ npx @truefoundry/utils --port <n>
+
+Start the agent server. Defaults to standalone mode (SQLite, no Redis).
+Set STANDALONE=false with Postgres and Redis for multi-replica peering.
+
+Options:
+ --port <n> HTTP port (default: 8790, or PORT env)
+ -h, --help Show this help
+`);
+}
+
+function applyPort(raw: string | undefined): void {
+ if (raw === undefined) {
+ return;
+ }
+ const port = Number(raw);
+ if (!Number.isInteger(port) || port < 1 || port > 65535) {
+ throw new Error(`Invalid --port "${raw}" (expected integer 1–65535)`);
+ }
+ process.env['PORT'] = String(port);
+}
+
+try {
+ const { values } = parseArgs({
+ args: process.argv.slice(2),
+ options: {
+ port: { type: 'string' },
+ help: { type: 'boolean', short: 'h', default: false },
+ },
+ allowPositionals: false,
+ strict: true,
+ });
+
+ if (values.help) {
+ printUsage();
+ } else {
+ applyPort(values.port);
+ await import('./main.js');
+ }
+} catch (error) {
+ console.error(error instanceof Error ? error.message : error);
+ process.exit(1);
+}
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index 74dd79525..f1dd7dea6 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -5,8 +5,36 @@
* `configuration` object exported as default. Any invalid value throws at
* import time, so a misconfigured server fails fast at boot instead of
* mid-run.
+ *
+ * `STANDALONE` is a discriminated mode selector:
+ * - `true` (default): SQLite only; no Redis / executor peering.
+ * - `false`: Postgres + Redis (defaults to local harness credentials /
+ * `redis://localhost:6379`).
*/
+import { existsSync } from 'node:fs';
import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import envPaths from 'env-paths';
+
+const DEFAULT_PORT = 8790;
+/**
+ * Package root whether this module runs as `src/config.ts` (tsx) or is bundled
+ * into `dist/main.js` / `dist/cli.js` (`import.meta` → `dist/` → parent).
+ */
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/** Turn ids minted by a standalone process; no peer can ever own them. */
+const LOCAL_EXECUTOR_ID = 'local';
+/** OS-standard data dir for SQLite in standalone mode. */
+const ENV_PATHS_APP_NAME = 'truefoundry-utils';
+const DEFAULT_SQLITE_FILENAME = 'db.sqlite';
+
+const DEFAULT_POSTGRES_USER = 'harness';
+const DEFAULT_POSTGRES_PASSWORD = 'harness';
+const DEFAULT_POSTGRES_DB = 'harness';
+const DEFAULT_POSTGRES_HOST = 'localhost';
+const DEFAULT_POSTGRES_PORT = 5432;
+const DEFAULT_REDIS_URL = 'redis://localhost:6379';
// ============================================================================
// HELPER FUNCTIONS
@@ -17,7 +45,7 @@ export interface GetEnvOptions {
required?: boolean;
}
-export const getEnv = (key: string, options?: GetEnvOptions): string | undefined => {
+function getEnv(key: string, options?: GetEnvOptions): string | undefined {
const value = process.env[key];
if (value !== undefined) {
return value;
@@ -33,13 +61,13 @@ export const getEnv = (key: string, options?: GetEnvOptions): string | undefined
}
return undefined;
-};
+}
function randomAlphanumeric(length: number): string {
return Array.from({ length }, () => Math.floor(Math.random() * 36).toString(36)).join('');
}
-export const parsePort = (raw: string | undefined): number => {
+function parsePort(raw: string | undefined): number {
if (raw === undefined || raw.trim() === '') {
return DEFAULT_PORT;
}
@@ -48,14 +76,10 @@ export const parsePort = (raw: string | undefined): number => {
throw new Error(`Environment variable PORT must be an integer between 1 and 65535, got "${raw}"`);
}
return port;
-};
+}
/** Parses a positive-integer env var, falling back to `defaultValue` when unset/blank. */
-export const parsePositiveInt = (options: {
- envKey: string;
- raw: string | undefined;
- defaultValue: number;
-}): number => {
+function parsePositiveInt(options: { envKey: string; raw: string | undefined; defaultValue: number }): number {
const { envKey, raw, defaultValue } = options;
if (raw === undefined || raw.trim() === '') {
return defaultValue;
@@ -65,10 +89,10 @@ export const parsePositiveInt = (options: {
throw new Error(`Environment variable ${envKey} must be a positive integer, got "${raw}"`);
}
return value;
-};
+}
/** Parses a boolean env var; anything but `true`/`false` throws instead of reading as `false`. */
-const parseBoolean = (options: { envKey: string; raw: string | undefined; defaultValue: boolean }): boolean => {
+function parseBoolean(options: { envKey: string; raw: string | undefined; defaultValue: boolean }): boolean {
const { envKey, raw, defaultValue } = options;
if (raw === undefined || raw.trim() === '') {
return defaultValue;
@@ -77,60 +101,118 @@ const parseBoolean = (options: { envKey: string; raw: string | undefined; defaul
if (value === 'true') return true;
if (value === 'false') return false;
throw new Error(`Environment variable ${envKey} must be "true" or "false", got "${raw}"`);
-};
+}
-/** Required env var that also rejects blank strings. */
-export const requireNonEmptyEnv = (key: string): string => {
- const value = getEnv(key, { required: true });
- if (value === undefined || value.trim() === '') {
- throw new Error(`Environment variable ${key} is required but was not specified.`);
+/**
+ * Prefer `dist/_frontend` shipped in the npm tarball (npx / `pnpm start`).
+ * Fall back to the monorepo sibling `../frontend/dist` (host-dev before a copy).
+ */
+function resolveDefaultFrontendDir(): string {
+ const packaged = path.join(PACKAGE_ROOT, 'dist', '_frontend');
+ if (existsSync(path.join(packaged, 'index.html'))) {
+ return packaged;
}
- return value;
-};
+ return path.join(PACKAGE_ROOT, '..', 'frontend', 'dist');
+}
+
+function resolveFrontendDir(): string {
+ const override = getEnv('FRONTEND_DIR');
+ if (override !== undefined && override.trim() !== '') {
+ return path.resolve(override);
+ }
+ return resolveDefaultFrontendDir();
+}
+
+/** Absolute path from an optional env override; unset/blank → `undefined`. */
+function resolveOptionalPathEnv(envKey: string): string | undefined {
+ const override = getEnv(envKey);
+ if (override === undefined || override.trim() === '') {
+ return undefined;
+ }
+ return path.resolve(override);
+}
+
+/**
+ * Absolute SQLite file path for standalone mode.
+ * Env: `SQLITE_PATH` (optional). Default: `{env-paths data}/db.sqlite`.
+ */
+function resolveSqlitePath(): string {
+ const override = getEnv('SQLITE_PATH');
+ if (override !== undefined && override.trim() !== '') {
+ return path.resolve(override);
+ }
+ const paths = envPaths(ENV_PATHS_APP_NAME, { suffix: '' });
+ return path.join(paths.data, DEFAULT_SQLITE_FILENAME);
+}
+
+/** Redis peering URL for distributed mode. Env: `REDIS_URL`. */
+function resolveRedisUrl(): string {
+ const raw = getEnv('REDIS_URL', { defaultValue: DEFAULT_REDIS_URL }) ?? DEFAULT_REDIS_URL;
+ if (raw.trim() === '') {
+ throw new Error('Environment variable REDIS_URL must be non-empty when STANDALONE=false.');
+ }
+ return raw;
+}
+
+/** Postgres connection string derived from `POSTGRES_*` for distributed mode. */
+function resolvePostgresDatabaseUrl(): string {
+ const postgresUser = getEnv('POSTGRES_USER', { defaultValue: DEFAULT_POSTGRES_USER }) ?? DEFAULT_POSTGRES_USER;
+ const postgresPassword =
+ getEnv('POSTGRES_PASSWORD', { defaultValue: DEFAULT_POSTGRES_PASSWORD }) ?? DEFAULT_POSTGRES_PASSWORD;
+ const postgresDb = getEnv('POSTGRES_DB', { defaultValue: DEFAULT_POSTGRES_DB }) ?? DEFAULT_POSTGRES_DB;
+ const postgresHost = getEnv('POSTGRES_HOST', { defaultValue: DEFAULT_POSTGRES_HOST }) ?? DEFAULT_POSTGRES_HOST;
+ const postgresPort = parsePositiveInt({
+ envKey: 'POSTGRES_PORT',
+ raw: getEnv('POSTGRES_PORT'),
+ defaultValue: DEFAULT_POSTGRES_PORT,
+ });
+ if (
+ postgresUser.trim() === '' ||
+ postgresPassword.trim() === '' ||
+ postgresDb.trim() === '' ||
+ postgresHost.trim() === ''
+ ) {
+ throw new Error(
+ 'POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and POSTGRES_HOST must be non-empty when STANDALONE=false.',
+ );
+ }
+ return buildPostgresConnectionString({
+ user: postgresUser,
+ password: postgresPassword,
+ host: postgresHost,
+ port: postgresPort,
+ database: postgresDb,
+ });
+}
/** Builds a Postgres connection URL from discrete `POSTGRES_*` parts. */
-export const buildPostgresConnectionString = (parts: {
+function buildPostgresConnectionString(parts: {
user: string;
password: string;
host: string;
port: number;
database: string;
-}): string => {
+}): string {
return `postgres://${encodeURIComponent(parts.user)}:${encodeURIComponent(parts.password)}@${parts.host}:${String(parts.port)}/${encodeURIComponent(parts.database)}`;
-};
-
-// ============================================================================
-// CONFIGURATION INTERFACE
-// ============================================================================
-
-export const DEFAULT_PORT = 8790;
-
-/** Relative to the working directory; the image sets an absolute FRONTEND_DIR. */
-const DEFAULT_FRONTEND_DIR = '../frontend/dist';
-
-/** Turn ids minted by a single-binary process; no peer can ever own them. */
-const LOCAL_EXECUTOR_ID = 'local';
+}
-/** Dropped in single-binary mode so nothing downstream can connect to a Redis it must not use. */
-const resolveRedisUrl = (singleBinary: boolean): string | undefined => {
- if (singleBinary) {
- return undefined;
+/** Defaults to `http://localhost:${PORT}` so local standalone boots without an env file. */
+function resolvePublicBaseUrl(port: number): string {
+ const override = getEnv('PUBLIC_BASE_URL');
+ if (override !== undefined && override.trim() !== '') {
+ return override;
}
- return requireNonEmptyEnv('REDIS_URL');
-};
+ return `http://localhost:${String(port)}`;
+}
-/** Always longer than `LOCAL_EXECUTOR_ID`, so a peer can never be mistaken for a local owner. */
-const resolveExecutorId = (singleBinary: boolean): string => {
- if (singleBinary) {
- return LOCAL_EXECUTOR_ID;
- }
- return randomAlphanumeric(6);
-};
+// ============================================================================
+// CONFIGURATION TYPES
+// ============================================================================
-export interface ServerConfiguration {
+export interface SharedServerConfiguration {
/** HTTP port the server listens on. Env: `PORT`. */
PORT: number;
- /** Peering identity embedded in the turn ids this process mints; `local` in single-binary mode. */
+ /** Peering identity embedded in the turn ids this process mints; `local` in standalone mode. */
EXECUTOR_ID: string;
/**
* Optional override for the model catalog YAML (discovery presets for
@@ -158,7 +240,8 @@ export interface ServerConfiguration {
SANDBOX_CATALOG_PATH: string | undefined;
/**
* Frontend build served alongside the API; a missing directory leaves the server API-only.
- * Env: `FRONTEND_DIR`, defaults to `../frontend/dist` relative to the working directory.
+ * Env: `FRONTEND_DIR`. Default: packaged `dist/_frontend` (npx tarball) or
+ * monorepo `packages/frontend/dist` — always absolute, independent of CWD.
*/
FRONTEND_DIR: string;
/** Max milliseconds for one MCP request. Env: `MCP_REQUEST_TIMEOUT_MS`. Default 4 minutes. */
@@ -168,7 +251,7 @@ export interface ServerConfiguration {
/**
* Public base URL of this server used as the origin of the MCP OAuth callback
* (`{PUBLIC_BASE_URL}/api/v1/mcp-servers/oauth/callback`). Not trimmed.
- * Env: `PUBLIC_BASE_URL` (required).
+ * Env: `PUBLIC_BASE_URL`. Default: `http://localhost:${PORT}`.
*/
PUBLIC_BASE_URL: string;
/**
@@ -192,120 +275,126 @@ export interface ServerConfiguration {
*/
SERVER_EXECUTION_TIMEOUT_SECONDS: number;
/**
- * Postgres connection string derived from `POSTGRES_*` (not read from env directly).
- * Form: `postgres://USER:PASSWORD@HOST:PORT/DB` with user/password URL-encoded.
+ * TTL for a running turn's resumable event stream.
+ * Env: `TURN_STREAM_TTL_SECONDS`. Default execution timeout + 300.
*/
- DATABASE_URL: string;
- /** Max connections in the `pg` Pool. Env: `DATABASE_POOL_MAX`. Default 10. */
- DATABASE_POOL_MAX: number;
+ TURN_STREAM_TTL_SECONDS: number;
/**
- * Postgres `statement_timeout` for app and migrations (same pool).
- * Env: `POSTGRES_STATEMENT_TIMEOUT_MS`. Default 60000.
+ * TTL retained after `turn.done` so subscribers can drain remaining events.
+ * Env: `TURN_STREAM_POST_COMPLETION_TTL_SECONDS`. Default 300.
*/
- POSTGRES_STATEMENT_TIMEOUT_MS: number;
+ TURN_STREAM_POST_COMPLETION_TTL_SECONDS: number;
/**
- * Postgres `idle_in_transaction_session_timeout` for app and migrations (same pool).
- * Env: `POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS`. Default 60000.
+ * Max ms to keep a turn subscription open.
+ * Env: `TURN_SUBSCRIBE_TIMEOUT_MS`. Default 600000.
*/
- POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: number;
- /** Peering URL shared by all replicas; undefined in single-binary mode. Env: `REDIS_URL`. */
- REDIS_URL: string | undefined;
+ TURN_SUBSCRIBE_TIMEOUT_MS: number;
/**
* Max ms to wait for a peer executor's reply before failing with 424.
* Env: `REDIS_REQUEST_REPLY_TIMEOUT_MS`. Default 60000.
+ * Only used when a Redis client is wired (distributed mode).
*/
REDIS_REQUEST_REPLY_TIMEOUT_MS: number;
/**
* How often this process refreshes its peering heartbeat key.
* Env: `REDIS_REQUEST_REPLY_HEARTBEAT_INTERVAL_MS`. Default 5000.
+ * Only used when a Redis client is wired (distributed mode).
*/
REDIS_REQUEST_REPLY_HEARTBEAT_INTERVAL_MS: number;
/**
* TTL for reply values so abandoned reply keys are reclaimed.
* Env: `REDIS_REQUEST_REPLY_REPLY_TTL_MS`. Default 120000.
+ * Only used when a Redis client is wired (distributed mode).
*/
REDIS_REQUEST_REPLY_REPLY_TTL_MS: number;
/**
* Sleep between reply poll attempts while waiting on a peer.
* Env: `REDIS_REQUEST_REPLY_POLL_INTERVAL_MS`. Default 500.
+ * Only used when a Redis client is wired (distributed mode).
*/
REDIS_REQUEST_REPLY_POLL_INTERVAL_MS: number;
+}
+
+export type StandaloneServerConfiguration = SharedServerConfiguration & {
/**
- * TTL for a running turn's resumable event stream.
- * Env: `TURN_STREAM_TTL_SECONDS`. Default execution timeout + 300.
+ * Single-process topology: SQLite persistence, no Redis / executor peering.
+ * Env: `STANDALONE`. Default: true.
*/
- TURN_STREAM_TTL_SECONDS: number;
+ STANDALONE: true;
/**
- * TTL retained after `turn.done` so subscribers can drain remaining events.
- * Env: `TURN_STREAM_POST_COMPLETION_TTL_SECONDS`. Default 300.
+ * Absolute SQLite database file path.
+ * Env: `SQLITE_PATH` (optional). Default: env-paths data dir + `db.sqlite`.
*/
- TURN_STREAM_POST_COMPLETION_TTL_SECONDS: number;
+ SQLITE_PATH: string;
+};
+
+export type DistributedServerConfiguration = SharedServerConfiguration & {
/**
- * Max ms to keep a turn subscription open.
- * Env: `TURN_SUBSCRIBE_TIMEOUT_MS`. Default 600000.
+ * Multi-replica topology: Postgres persistence + Redis executor peering.
+ * Env: `STANDALONE`. Default: true (so this branch requires an explicit `false`).
*/
- TURN_SUBSCRIBE_TIMEOUT_MS: number;
-}
+ 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.
+ */
+ DATABASE_URL: string;
+ /** Max connections in the `pg` Pool. Env: `DATABASE_POOL_MAX`. Default 10. */
+ DATABASE_POOL_MAX: number;
+ /**
+ * Postgres `statement_timeout` for app and migrations (same pool).
+ * Env: `POSTGRES_STATEMENT_TIMEOUT_MS`. Default 60000.
+ */
+ POSTGRES_STATEMENT_TIMEOUT_MS: number;
+ /**
+ * Postgres `idle_in_transaction_session_timeout` for app and migrations (same pool).
+ * Env: `POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS`. Default 60000.
+ */
+ POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: number;
+ /** Peering URL shared by all replicas. Env: `REDIS_URL`. Default `redis://localhost:6379`. */
+ REDIS_URL: string;
+};
+
+export type ServerConfiguration = StandaloneServerConfiguration | DistributedServerConfiguration;
// ============================================================================
// CONFIGURATION VALUES
// ============================================================================
-const postgresUser = requireNonEmptyEnv('POSTGRES_USER');
-const postgresPassword = requireNonEmptyEnv('POSTGRES_PASSWORD');
-const postgresDb = requireNonEmptyEnv('POSTGRES_DB');
-const postgresHost = requireNonEmptyEnv('POSTGRES_HOST');
-const postgresPort = parsePositiveInt({
- envKey: 'POSTGRES_PORT',
- raw: requireNonEmptyEnv('POSTGRES_PORT'),
- defaultValue: 5432,
-});
const serverExecutionTimeoutSeconds = parsePositiveInt({
envKey: 'SERVER_EXECUTION_TIMEOUT_SECONDS',
raw: getEnv('SERVER_EXECUTION_TIMEOUT_SECONDS'),
defaultValue: 600,
});
-const singleBinary = parseBoolean({
- envKey: 'SINGLE_BINARY',
- raw: getEnv('SINGLE_BINARY'),
+const standalone = parseBoolean({
+ envKey: 'STANDALONE',
+ raw: getEnv('STANDALONE'),
defaultValue: true,
});
-const mcpRequestTimeoutMs = parsePositiveInt({
- envKey: 'MCP_REQUEST_TIMEOUT_MS',
- raw: getEnv('MCP_REQUEST_TIMEOUT_MS'),
- defaultValue: 4 * 60 * 1000,
-});
-const mcpConnectTimeoutMs = parsePositiveInt({
- envKey: 'MCP_CONNECT_TIMEOUT_MS',
- raw: getEnv('MCP_CONNECT_TIMEOUT_MS'),
- defaultValue: 30 * 1000,
-});
+const port = parsePort(getEnv('PORT'));
+
+const shared: SharedServerConfiguration = {
+ PORT: port,
+ EXECUTOR_ID: standalone ? LOCAL_EXECUTOR_ID : randomAlphanumeric(6),
+ MODEL_CATALOG_PATH: resolveOptionalPathEnv('MODEL_CATALOG_PATH'),
+ MCP_CATALOG_PATH: resolveOptionalPathEnv('MCP_CATALOG_PATH'),
+ SKILL_CATALOG_PATH: resolveOptionalPathEnv('SKILL_CATALOG_PATH'),
+ SANDBOX_CATALOG_PATH: resolveOptionalPathEnv('SANDBOX_CATALOG_PATH'),
+ FRONTEND_DIR: resolveFrontendDir(),
+ PUBLIC_BASE_URL: resolvePublicBaseUrl(port),
-const configuration: ServerConfiguration = {
- PORT: parsePort(getEnv('PORT')),
- EXECUTOR_ID: resolveExecutorId(singleBinary),
- MODEL_CATALOG_PATH: (() => {
- const override = getEnv('MODEL_CATALOG_PATH');
- return override === undefined || override === '' ? undefined : path.resolve(override);
- })(),
- MCP_CATALOG_PATH: (() => {
- const override = getEnv('MCP_CATALOG_PATH');
- return override === undefined || override === '' ? undefined : path.resolve(override);
- })(),
- SKILL_CATALOG_PATH: (() => {
- const override = getEnv('SKILL_CATALOG_PATH');
- return override === undefined || override === '' ? undefined : path.resolve(override);
- })(),
- SANDBOX_CATALOG_PATH: (() => {
- const override = getEnv('SANDBOX_CATALOG_PATH');
- return override === undefined || override === '' ? undefined : path.resolve(override);
- })(),
- FRONTEND_DIR: path.resolve(getEnv('FRONTEND_DIR', { defaultValue: DEFAULT_FRONTEND_DIR }) ?? DEFAULT_FRONTEND_DIR),
- MCP_REQUEST_TIMEOUT_MS: mcpRequestTimeoutMs,
- MCP_CONNECT_TIMEOUT_MS: mcpConnectTimeoutMs,
- PUBLIC_BASE_URL: requireNonEmptyEnv('PUBLIC_BASE_URL'),
+ MCP_REQUEST_TIMEOUT_MS: parsePositiveInt({
+ envKey: 'MCP_REQUEST_TIMEOUT_MS',
+ raw: getEnv('MCP_REQUEST_TIMEOUT_MS'),
+ defaultValue: 4 * 60 * 1000,
+ }),
+ MCP_CONNECT_TIMEOUT_MS: parsePositiveInt({
+ envKey: 'MCP_CONNECT_TIMEOUT_MS',
+ raw: getEnv('MCP_CONNECT_TIMEOUT_MS'),
+ defaultValue: 30 * 1000,
+ }),
OAUTH_CLIENT_NAME: getEnv('OAUTH_CLIENT_NAME', { defaultValue: 'truefoundry-harness' }) ?? 'truefoundry-harness',
SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD: parsePositiveInt({
envKey: 'SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD',
@@ -318,29 +407,21 @@ const configuration: ServerConfiguration = {
defaultValue: 30,
}),
SERVER_EXECUTION_TIMEOUT_SECONDS: serverExecutionTimeoutSeconds,
- DATABASE_URL: buildPostgresConnectionString({
- user: postgresUser,
- password: postgresPassword,
- host: postgresHost,
- port: postgresPort,
- database: postgresDb,
- }),
- DATABASE_POOL_MAX: parsePositiveInt({
- envKey: 'DATABASE_POOL_MAX',
- raw: getEnv('DATABASE_POOL_MAX'),
- defaultValue: 10,
+ TURN_STREAM_TTL_SECONDS: parsePositiveInt({
+ envKey: 'TURN_STREAM_TTL_SECONDS',
+ raw: getEnv('TURN_STREAM_TTL_SECONDS'),
+ defaultValue: serverExecutionTimeoutSeconds + 300,
}),
- POSTGRES_STATEMENT_TIMEOUT_MS: parsePositiveInt({
- envKey: 'POSTGRES_STATEMENT_TIMEOUT_MS',
- raw: getEnv('POSTGRES_STATEMENT_TIMEOUT_MS'),
- defaultValue: 60_000,
+ TURN_STREAM_POST_COMPLETION_TTL_SECONDS: parsePositiveInt({
+ envKey: 'TURN_STREAM_POST_COMPLETION_TTL_SECONDS',
+ raw: getEnv('TURN_STREAM_POST_COMPLETION_TTL_SECONDS'),
+ defaultValue: 300,
}),
- POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: parsePositiveInt({
- envKey: 'POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS',
- raw: getEnv('POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS'),
- defaultValue: 60_000,
+ TURN_SUBSCRIBE_TIMEOUT_MS: parsePositiveInt({
+ envKey: 'TURN_SUBSCRIBE_TIMEOUT_MS',
+ raw: getEnv('TURN_SUBSCRIBE_TIMEOUT_MS'),
+ defaultValue: 600_000,
}),
- REDIS_URL: resolveRedisUrl(singleBinary),
REDIS_REQUEST_REPLY_TIMEOUT_MS: parsePositiveInt({
envKey: 'REDIS_REQUEST_REPLY_TIMEOUT_MS',
raw: getEnv('REDIS_REQUEST_REPLY_TIMEOUT_MS'),
@@ -361,21 +442,34 @@ const configuration: ServerConfiguration = {
raw: getEnv('REDIS_REQUEST_REPLY_POLL_INTERVAL_MS'),
defaultValue: 500,
}),
- TURN_STREAM_TTL_SECONDS: parsePositiveInt({
- envKey: 'TURN_STREAM_TTL_SECONDS',
- raw: getEnv('TURN_STREAM_TTL_SECONDS'),
- defaultValue: serverExecutionTimeoutSeconds + 300,
- }),
- TURN_STREAM_POST_COMPLETION_TTL_SECONDS: parsePositiveInt({
- envKey: 'TURN_STREAM_POST_COMPLETION_TTL_SECONDS',
- raw: getEnv('TURN_STREAM_POST_COMPLETION_TTL_SECONDS'),
- defaultValue: 300,
- }),
- TURN_SUBSCRIBE_TIMEOUT_MS: parsePositiveInt({
- envKey: 'TURN_SUBSCRIBE_TIMEOUT_MS',
- raw: getEnv('TURN_SUBSCRIBE_TIMEOUT_MS'),
- defaultValue: 600_000,
- }),
-} as const;
+};
+
+const configuration: ServerConfiguration = standalone
+ ? {
+ ...shared,
+ STANDALONE: true,
+ SQLITE_PATH: resolveSqlitePath(),
+ }
+ : {
+ ...shared,
+ STANDALONE: false,
+ DATABASE_URL: resolvePostgresDatabaseUrl(),
+ DATABASE_POOL_MAX: parsePositiveInt({
+ envKey: 'DATABASE_POOL_MAX',
+ raw: getEnv('DATABASE_POOL_MAX'),
+ defaultValue: 10,
+ }),
+ POSTGRES_STATEMENT_TIMEOUT_MS: parsePositiveInt({
+ envKey: 'POSTGRES_STATEMENT_TIMEOUT_MS',
+ raw: getEnv('POSTGRES_STATEMENT_TIMEOUT_MS'),
+ defaultValue: 60_000,
+ }),
+ POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: parsePositiveInt({
+ envKey: 'POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS',
+ raw: getEnv('POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS'),
+ defaultValue: 60_000,
+ }),
+ REDIS_URL: resolveRedisUrl(),
+ };
export default configuration;
diff --git a/packages/server/src/db/migrateSqlite.ts b/packages/server/src/db/migrateSqlite.ts
index b2e275932..0bfc98eb2 100644
--- a/packages/server/src/db/migrateSqlite.ts
+++ b/packages/server/src/db/migrateSqlite.ts
@@ -9,8 +9,7 @@ import type { Database } from './sqlite/types';
/**
* Runs all pending SQLite migrations.
*
- * Test / packaging helper only — do not import from `main` or `migrate-cli`.
- * Production startup and `pnpm migrate` run Postgres via `migratePostgres`.
+ * Used at sqlite startup and by SQLite store tests.
* Resolves `…/sqlite/migrations` next to this module (source or `dist/`).
*/
export async function migrateSqliteToLatest(db: Kysely<Database>): Promise<void> {
diff --git a/packages/server/src/db/postgres/migrate-cli.ts b/packages/server/src/db/postgres/migrate-cli.ts
index dc779a8cb..a566e82cc 100644
--- a/packages/server/src/db/postgres/migrate-cli.ts
+++ b/packages/server/src/db/postgres/migrate-cli.ts
@@ -1,12 +1,18 @@
/**
* Run pending Postgres migrations and exit.
- * Usage: `pnpm migrate` from packages/server.
- * SQLite migrations are built into dist for packaging but are not run here.
+ * Usage: `pnpm migrate` from packages/server with `STANDALONE=false`.
+ * SQLite migrations run automatically when the server boots in standalone mode.
*/
import configuration from '../../config';
import { migrateToLatest } from '../migratePostgres';
import { createDb } from './client';
+if (configuration.STANDALONE) {
+ throw new Error(
+ 'pnpm migrate targets Postgres only; set STANDALONE=false (and provide POSTGRES_* / Redis env as needed). SQLite migrations run on standalone server boot.',
+ );
+}
+
const db = createDb({
connectionString: configuration.DATABASE_URL,
poolMax: configuration.DATABASE_POOL_MAX,
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 1275bb0bf..dcf8c9075 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -1,58 +1,172 @@
/**
- * Server entry point: validates config, migrates Postgres, wires DB stores
- * and starts the HTTP server. Any config, migration, or store error aborts startup.
- * SQLite migrations are packaged under dist/ but are not run at startup.
+ * Server entry point: validates config, migrates the selected database, wires
+ * stores, and starts the HTTP server. Any config, migration, or store error
+ * aborts startup.
+ *
+ * `STANDALONE=true` (default): SQLite, no Redis. `STANDALONE=false`: Postgres + Redis.
+ *
+ * Config is validated at import time (`./config`). Runtime startup failures
+ * (migrate, Redis, listen) are caught below and exit non-zero. SQLite vs
+ * Postgres store modules stay dynamic so only the active engine is loaded.
*/
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+
+let configuration: typeof import('./config').default;
+
+try {
+ ({ default: configuration } = await import('./config'));
+} catch (error) {
+ console.error(
+ 'Failed to start server: Failed to load configuration:',
+ error instanceof Error ? error.message : error,
+ );
+ process.exit(1);
+}
+
import { serve } from '@hono/node-server';
-import type { TurnStreamingEvent } from '@truefoundry/utils-core/agent-session';
+import {
+ CancellationReason,
+ Sessions,
+ type ISessionStore,
+ type TurnStreamingEvent,
+} from '@truefoundry/utils-core/agent-session';
+import { RequestReplyExecutor, RequestReplyRouter } from '@truefoundry/utils-core/request-reply';
import type { RedisClientType } from 'redis';
-import winston from 'winston';
+import winston, { type Logger } from 'winston';
-try {
+import { createServerApp } from './app';
+import { McpCatalog } from './catalog/McpCatalog';
+import { ModelCatalog } from './catalog/ModelCatalog';
+import { SandboxCatalog } from './catalog/SandboxCatalog';
+import { SkillCatalog } from './catalog/SkillCatalog';
+import { type DistributedServerConfiguration } from './config';
+import type { IMcpServerStore } from './db/mcpServerStore';
+import type { IModelProviderStore } from './db/modelProviderStore';
+import type { ISandboxProviderStore } from './db/sandboxProviderStore';
+import type { ISkillStore } from './db/skillStore';
+import { mountFrontend } from './frontend';
+import type { IOAuthTokenStore } from './mcp/auth/types';
+import { ActiveTurnRegistry } from './runtime/activeTurns';
+import { EventSubscriptionRegistry } from './runtime/event-subscription';
+
+/** Persistence + optional Redis wired for the selected topology. */
+interface ServerPersistence {
+ sessionStore: ISessionStore;
+ modelProviderStore: IModelProviderStore;
+ mcpServerStore: IMcpServerStore;
+ tokenStore: IOAuthTokenStore;
+ skillStore: ISkillStore;
+ sandboxProviderStore: ISandboxProviderStore;
+ destroyDb: () => Promise<void>;
+ redis: RedisClientType | undefined;
+}
+
+/** SQLite stores; Redis unused (executor peering disabled). */
+async function createStandalonePersistence(options: {
+ sqlitePath: string;
+ logger: Logger;
+}): Promise<ServerPersistence> {
+ const { sqlitePath, logger } = options;
+ await mkdir(path.dirname(sqlitePath), { recursive: true });
+ const [{ createSqliteDb }, { migrateSqliteToLatest }, sqliteStores] = await Promise.all([
+ import('./db/sqlite/client'),
+ import('./db/migrateSqlite'),
+ Promise.all([
+ import('./db/sqlite/session-store/SqliteSessionStore'),
+ import('./db/sqlite/model-provider-store/SqliteModelProviderStore'),
+ import('./db/sqlite/mcp-server-store/SqliteMcpServerStore'),
+ import('./db/sqlite/token-store/SqliteOAuthTokenStore'),
+ import('./db/sqlite/skill-store/SqliteSkillStore'),
+ import('./db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore'),
+ ]),
+ ]);
+ const [
+ { SqliteSessionStore },
+ { SqliteModelProviderStore },
+ { SqliteMcpServerStore },
+ { SqliteOAuthTokenStore },
+ { SqliteSkillStore },
+ { SqliteSandboxProviderStore },
+ ] = sqliteStores;
+
+ const db = createSqliteDb(sqlitePath);
+ await migrateSqliteToLatest(db);
+ logger.info(`Standalone mode: sqlite at ${sqlitePath}`);
+ logger.info('Standalone mode: executor peering disabled and Redis unused');
+
+ return {
+ sessionStore: new SqliteSessionStore(db),
+ modelProviderStore: new SqliteModelProviderStore(db),
+ mcpServerStore: new SqliteMcpServerStore(db),
+ tokenStore: new SqliteOAuthTokenStore(db),
+ skillStore: new SqliteSkillStore(db),
+ sandboxProviderStore: new SqliteSandboxProviderStore(db),
+ destroyDb: () => db.destroy(),
+ redis: undefined,
+ };
+}
+
+/** Postgres stores + Redis for executor peering. */
+async function createDistributedPersistence(options: {
+ configuration: DistributedServerConfiguration;
+ logger: Logger;
+}): Promise<ServerPersistence> {
+ const { configuration, logger } = options;
+ const {
+ DATABASE_URL: databaseUrl,
+ DATABASE_POOL_MAX: databasePoolMax,
+ POSTGRES_STATEMENT_TIMEOUT_MS: statementTimeoutMs,
+ POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: idleInTransactionSessionTimeoutMs,
+ REDIS_URL: redisUrl,
+ EXECUTOR_ID: executorId,
+ } = configuration;
+
+ const [{ createDb }, { migrateToLatest }, { connectRedis }, postgresStores] = await Promise.all([
+ import('./db/postgres/client'),
+ import('./db/migratePostgres'),
+ import('./runtime/redis'),
+ Promise.all([
+ import('./db/postgres/session-store/PostgresSessionStore'),
+ import('./db/postgres/model-provider-store/PostgresModelProviderStore'),
+ import('./db/postgres/mcp-server-store/PostgresMcpServerStore'),
+ import('./db/postgres/token-store/PostgresOAuthTokenStore'),
+ import('./db/postgres/skill-store/PostgresSkillStore'),
+ import('./db/postgres/sandbox-provider-store/PostgresSandboxProviderStore'),
+ ]),
+ ]);
const [
- { createServerApp },
- { mountFrontend },
- { default: configuration },
- { createDb },
- { migrateToLatest },
- { Sessions, CancellationReason },
- { ActiveTurnRegistry },
- { connectRedis },
- { RequestReplyExecutor, RequestReplyRouter },
{ PostgresSessionStore },
- { EventSubscriptionRegistry },
- { ModelCatalog },
{ PostgresModelProviderStore },
- { McpCatalog },
{ PostgresMcpServerStore },
{ PostgresOAuthTokenStore },
- { SkillCatalog },
{ PostgresSkillStore },
- { SandboxCatalog },
{ PostgresSandboxProviderStore },
- ] = await Promise.all([
- import('./app'),
- import('./frontend'),
- import('./config'),
- import('./db/postgres/client'),
- import('./db/migratePostgres'),
- import('@truefoundry/utils-core/agent-session'),
- import('./runtime/activeTurns'),
- import('./runtime/redis'),
- import('@truefoundry/utils-core/request-reply'),
- import('./db/postgres/session-store/PostgresSessionStore'),
- import('./runtime/event-subscription'),
- import('./catalog/ModelCatalog'),
- import('./db/postgres/model-provider-store/PostgresModelProviderStore'),
- import('./catalog/McpCatalog'),
- import('./db/postgres/mcp-server-store/PostgresMcpServerStore'),
- import('./db/postgres/token-store/PostgresOAuthTokenStore'),
- import('./catalog/SkillCatalog'),
- import('./db/postgres/skill-store/PostgresSkillStore'),
- import('./catalog/SandboxCatalog'),
- import('./db/postgres/sandbox-provider-store/PostgresSandboxProviderStore'),
- ]);
+ ] = postgresStores;
+ const db = createDb({
+ connectionString: databaseUrl,
+ poolMax: databasePoolMax,
+ statementTimeoutMs,
+ idleInTransactionSessionTimeoutMs,
+ });
+ await migrateToLatest(db);
+ logger.info('Distributed mode: postgres');
+ logger.info(`Executor id: ${executorId}`);
+
+ return {
+ sessionStore: new PostgresSessionStore(db),
+ modelProviderStore: new PostgresModelProviderStore(db),
+ mcpServerStore: new PostgresMcpServerStore(db),
+ tokenStore: new PostgresOAuthTokenStore(db),
+ skillStore: new PostgresSkillStore(db),
+ sandboxProviderStore: new PostgresSandboxProviderStore(db),
+ destroyDb: () => db.destroy(),
+ redis: await connectRedis({ url: redisUrl, logger }),
+ };
+}
+
+try {
// Console logger shared by the server runtime (harness components require one).
const logger = winston.createLogger({
level: process.env['LOG_LEVEL'] ?? 'info',
@@ -60,38 +174,33 @@ try {
transports: [new winston.transports.Console()],
});
- const db = createDb({
- connectionString: configuration.DATABASE_URL,
- poolMax: configuration.DATABASE_POOL_MAX,
- statementTimeoutMs: configuration.POSTGRES_STATEMENT_TIMEOUT_MS,
- idleInTransactionSessionTimeoutMs: configuration.POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS,
- });
- await migrateToLatest(db);
+ const {
+ sessionStore,
+ modelProviderStore,
+ mcpServerStore,
+ tokenStore,
+ skillStore,
+ sandboxProviderStore,
+ destroyDb,
+ redis,
+ } = configuration.STANDALONE
+ ? await createStandalonePersistence({ sqlitePath: configuration.SQLITE_PATH, logger })
+ : await createDistributedPersistence({ configuration, logger });
- const sessionStore = new PostgresSessionStore(db);
- const skillStore = new PostgresSkillStore(db);
const activeTurns = new ActiveTurnRegistry();
-
- let redis: RedisClientType | undefined;
- if (configuration.REDIS_URL === undefined) {
- logger.info('Single-binary mode: executor peering disabled and Redis unused');
- } else {
- logger.info(`Executor id: ${configuration.EXECUTOR_ID}`);
- redis = await connectRedis({ url: configuration.REDIS_URL, logger });
- }
const requestReplyRouter = new RequestReplyRouter();
const eventSubscriptions = new EventSubscriptionRegistry<TurnStreamingEvent>(redis);
const app = createServerApp({
modelCatalog: ModelCatalog.load(),
- modelProviderStore: new PostgresModelProviderStore(db),
mcpCatalog: McpCatalog.load(),
- mcpServerStore: new PostgresMcpServerStore(db),
- tokenStore: new PostgresOAuthTokenStore(db),
skillCatalog: SkillCatalog.load(),
- skillStore,
sandboxCatalog: SandboxCatalog.load(),
- sandboxProviderStore: new PostgresSandboxProviderStore(db),
+ modelProviderStore,
+ mcpServerStore,
+ tokenStore,
+ skillStore,
+ sandboxProviderStore,
sessionStore,
sessions: new Sessions({ sessionStore }),
activeTurns,
@@ -106,7 +215,7 @@ try {
} else {
logger.warn(
`No frontend build at ${configuration.FRONTEND_DIR}: serving the API only. ` +
- 'Run `pnpm --filter frontend build` to serve the UI from here, or `pnpm dev:frontend` for UI work.',
+ 'Run `pnpm --filter frontend build` (and copy via build:frontend-assets) to serve the UI, or `pnpm standalone:dev` / `pnpm dev` for Vite.',
);
}
@@ -117,7 +226,7 @@ try {
// the initial subscribe + heartbeat — the replica is reachable for peering
// before the HTTP server starts.
let requestReplySubscriber: RedisClientType | undefined;
- let requestReplyExecutor: InstanceType<typeof RequestReplyExecutor> | undefined;
+ let requestReplyExecutor: RequestReplyExecutor | undefined;
if (redis) {
requestReplySubscriber = redis.duplicate();
requestReplySubscriber.on('error', (error: Error) => {
@@ -186,7 +295,7 @@ try {
error: error instanceof Error ? error.message : String(error),
});
});
- await db.destroy();
+ await destroyDb();
process.exit(0);
};
process.on('SIGTERM', signal => {
diff --git a/packages/server/tsup.config.ts b/packages/server/tsup.config.ts
index 1787d1113..9ea6ba650 100644
--- a/packages/server/tsup.config.ts
+++ b/packages/server/tsup.config.ts
@@ -2,7 +2,7 @@ import { readdirSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
-import { defineConfig } from 'tsup';
+import { defineConfig, type Options } from 'tsup';
const packageDir = path.dirname(fileURLToPath(import.meta.url));
const srcDbDir = path.join(packageDir, 'src/db');
@@ -19,19 +19,38 @@ function migrationEntries(engine: 'postgres' | 'sqlite'): Record<string, string>
);
}
-export default defineConfig({
- entry: {
- main: 'src/main.ts',
- // Emit both engines under dist/{postgres,sqlite}/migrations/.
- // Only Postgres is applied at runtime (main) and via `pnpm migrate`.
- ...migrationEntries('postgres'),
- ...migrationEntries('sqlite'),
- },
+const shared: Options = {
format: ['esm'],
dts: false,
splitting: false,
sourcemap: true,
- clean: true,
target: 'esnext',
outDir: 'dist',
-});
+};
+
+// tsup builds every config here concurrently, so neither may use `clean`: it wipes the
+// shared dist/ mid-flight and can delete the sibling config's output. The build script
+// clears dist/ before invoking tsup instead.
+export default defineConfig([
+ {
+ ...shared,
+ entry: {
+ main: 'src/main.ts',
+ // Emit both engines under dist/{postgres,sqlite}/migrations/.
+ // Runtime selects migrations via STANDALONE (false → postgres, true → sqlite).
+ ...migrationEntries('postgres'),
+ ...migrationEntries('sqlite'),
+ },
+ },
+ {
+ ...shared,
+ entry: {
+ cli: 'src/cli.ts',
+ },
+ // Keep cli as a thin launcher that dynamically imports ./main.js.
+ external: ['./main.js'],
+ banner: {
+ js: '#!/usr/bin/env node',
+ },
+ },
+]);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 08afe18fc..6f6b3fb99 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -222,6 +222,9 @@ importers:
better-sqlite3:
specifier: ^13.0.2
version: 13.0.2
+ env-paths:
+ specifier: ^4.0.0
+ version: 4.0.0
hono:
specifier: ^4.12.34
version: 4.13.0
@@ -3653,6 +3656,10 @@ packages:
resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
engines: {node: '>=0.12'}
+ resolution: {integrity: sha512-pxP8eL2SwwaTRi/KHYwLYXinDs7gL3jxFcBYmEdYfZmZXbaVDvdppd0XBU8qVz03rDfKZMXg1omHCbsJjZrMsw==}
+ engines: {node: '>=20'}
+
resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}
engines: {node: '>=18'}
@@ -4226,6 +4233,10 @@ packages:
resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
+ resolution: {integrity: sha512-4SrR7AdnY11LHfDKTZY1u6Ga3RuxZdl3YKWWShO5iyuG5h8QS4GD2tOb04peBJ5I7pXbR+CGBNEhTcwK+FzN3g==}
+ engines: {node: '>=20'}
+
resolution: {integrity: sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==}
engines: {node: '>=8'}
@@ -9459,6 +9470,10 @@ snapshots:
+ dependencies:
+ is-safe-filename: 0.1.1
+
@@ -10212,6 +10227,8 @@ snapshots:
+