Quickstart

Run TrueForge

TrueForge runs in two modes: 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.

npx (Local)
Docker Compose (Hosted)
Kubernetes (Hosted)
Railway (Hosted)

Requires Node.js 22.14 or newer on macOS, Linux, or Windows. One command, no other infrastructure — the UI and backend run locally, and data is stored in a local SQLite file:

npx @truefoundry/trueforge@latest

Then open http://localhost:8790. The defaults work out of the box — see the FAQ to change the port or data location.

Local (standalone) mode is meant for personal use on your own machine. It is 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 deployment, use hosted mode below.

Runs the full hosted topology on your machine: the server (UI + API), Postgres, and Redis.

git clone https://github.com/truefoundry/trueforge && cd trueforge
cp packages/trueforge/.env.example packages/trueforge/.env
docker compose up --build

Then open http://localhost:8791.

Configuration	Default	Description
`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`	from `.env`	Postgres credentials, read from `packages/trueforge/.env`.
	`http://localhost:8791`	Public origin, used for MCP OAuth callbacks.
Host ports	`8791`, `5433`, `6380`	App, Postgres, and Redis.

The Helm chart deploys the server in hosted mode with bundled Postgres and Redis (or point it at your own).Create a Secret for the controller↔server API key, then point apiKey at it. The chart ships a well-known placeholder (placeholder-value-please-generate-your-own) — strongly recommended to replace with a Secret before any shared deploy (the chart does not create one):

kubectl create secret generic trueforge-api-key \
  --from-literal=TRUEFORGE_API_KEY="$(openssl rand -hex 32)"

# values.yaml (snippet)
apiKey:
  valueFrom:
    secretKeyRef:
      name: trueforge-api-key
      key: TRUEFORGE_API_KEY

helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
  --version <x.y.z> \
  --values values.yaml

Find the version you want to install in the published Helm charts. See the chart README for full apiKey details.To expose TrueForge through an Istio gateway, save this VirtualService in values.yaml under extraObjects. Replace the host and gateway with your own values:

extraObjects:
  - apiVersion: networking.istio.io/v1
    kind: VirtualService
    metadata:
      name: '{{ include "trueforge.fullname" . }}'
    spec:
      hosts:
        - trueforge.example.com
      gateways:
        - istio-system/public-gateway
      http:
        - route:
            - destination:
                host: '{{ include "trueforge.fullname" . }}'
                port:
                  name: http

Then install (or upgrade) with the values file that includes both apiKey and extraObjects:

helm upgrade --install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
  --version <x.y.z> \
  --values values.yaml

Value	Default	Description
`apiKey`	placeholder string	Controller↔server key (`TRUEFORGE_API_KEY`). Prefer `valueFrom.secretKeyRef`.
`replicaCount`	`1`	Number of server replicas (peered over Redis).
`postgresql.enabled`	`true`	Bundle Postgres; set `false` + `externalPostgres.*` to bring your own.
`redis.enabled`	`true`	Bundle Redis; set `false` + `externalRedis.url` (string or `valueFrom`).
`server.publicBaseUrl`	`""`	Public origin; required for OIDC and MCP OAuth callbacks.
`configs.oidc.enabled`	`false`	Enable IdP login via `configs.oidc.*`. Default off = shared local admin — see chart README.

Hosted topology on Railway is defined with Infrastructure as Code in .railway/railway.ts: one project with the server (UI + API), Postgres, and Redis. Railway builds the from-source image (Dockerfile), and wires DATABASE_URL, REDIS_URL, and PUBLIC_BASE_URL in that file.From a clone of this repo:

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.

Without OIDC login, anyone who can reach the URL is admin. Enable login before sharing a Railway deployment beyond personal use.

STANDALONE=false and HOST=0.0.0.0 are baked into Dockerfile. Railway injects PORT automatically.

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 client across them.

Build your first agent

With TrueForge open in your browser, this walkthrough takes you from an empty workspace to a saved, reusable agent. The example builds a web research briefer — an agent that searches the web, fans out to parallel subagents, and turns its findings into an interactive one-page brief.

Add a model provider

Open Settings → Models, find a provider in the catalog, and click Configure. Paste your API key in Configure Provider Details and click Create — the provider’s models become available immediately.

Settings → Models listing providers such as OpenAI, Anthropic, and Google, each with a Configure button — Pick a provider from the catalog.

The Configure Provider Details dialog with an API key field and a collapsed Advanced custom endpoint section — Paste an API key and click Create.

Connect a web-search tool

Open Settings → Connectors and add a Model Context Protocol (MCP) server — this is how your agent reaches external tools and data. TrueForge ships a catalog you can connect in one click; each entry shows its auth type (OAuth, an API key, or none), and you can register your own server by URL with Add MCP Server.For this walkthrough, connect Exa — a web-search server that needs no authentication. Find it in the catalog and click Connect; it moves to Configured.

Settings → Connectors with Exa connected, above a catalog of more MCP servers labelled by auth type

Add a skill

Open Settings → Skills. A skill is a git-backed SKILL.md instruction pack the agent loads on demand. Enable one from the built-in list, or click Import from GitHub to add a skill from any public repository.For this walkthrough, enable web-artifacts-builder from the built-in list — it lets the agent turn its findings into a self-contained, interactive web page. Click Enable; it moves to Enabled.

Settings → Skills with web-artifacts-builder enabled, above the built-in skill catalog

Add a sandbox provider

A sandbox lets the agent run code, work with files, and use skills — so it’s required for the skill you just enabled. TrueForge supports Daytona today. It’s a one-time setup:

Create a Daytona API key with permission to write and delete snapshots and write sandboxes.
Open Settings → Sandbox providers, choose Daytona, click Configure, paste your API key, and click Save.

The Configure Daytona dialog with an API key field and a collapsed Advanced settings section — Paste your Daytona API key.

Settings → Sandbox providers showing Daytona as Connected — Connected and ready.

See the Sandbox guide for provider setup details.

Build the agent

Open Build Agent from the sidebar. It’s a split view: assemble the agent in the Agent Config panel on the left, and test it in a live chat on the right as you go.In the left panel, set:

Model — pick one from the selector at the top and choose a reasoning effort.
Instructions — define the agent’s role and behavior. For this example:

You are a web research assistant. Given a topic or question, use Exa to search the web and pull content from the most relevant, recent sources. When the request compares several items, research each one in parallel, then synthesize the findings into a clear one-page brief.

MCP Servers — open Select MCP Tools, choose Exa, and enable its tools.
Skills — open the Skills picker and enable web-artifacts-builder.
Runtime Config — open it to review execution and context settings. Keep Dynamic sub-agents on so the agent researches each item in parallel, and leave Generative UI, Sandbox, and Context compaction on.

Tools
Skills
Runtime Config

The Select MCP Tools dialog with Exa selected and its web_search and web_fetch tools enabled

Then test it in the chat on the right. For example:

Research the current state of open-source vector databases. Compare Qdrant, Weaviate, and Milvus on performance, features, and licensing, then write a one-page brief with sources.

The agent searches with Exa, delegates each database to a parallel subagent, and uses web-artifacts-builder in the sandbox to render an interactive brief.

The Build Agent page with the Agent Config panel on the left (model, instructions, runtime config, MCP servers, and skills) and, on the right, an interactive brief comparing Qdrant, Weaviate, and Milvus with a radar chart of relative strengths and recommendation cards — The Build Agent page: Agent Config on the left, and on the right the interactive brief the agent produced, including a Generative UI radar chart of the databases' relative strengths.

Save it as an agent

Happy with the setup? Click Save Agent at the top right, give it a name and a short description, and click Save changes. This captures the model, instructions, tools, skills, and runtime settings together as a reusable agent. For this example:

Agent name — web-research-brief
Description — Web research brief agent

The Save agent dialog with an agent name and a description field

Find it under Agents

Open Agents from the sidebar. Your saved agent is listed with a summary of its model, skills, and connectors. Click Try to start a fresh chat with the same setup, or use the row’s menu to manage it. See Agents for shared-visibility notes in hosted mode.

The Agents list showing the saved web-research-brief agent with its model and tool summary and a Try action

FAQ

How do I run the server on a different port?

Pass --port, or set the PORT environment variable:

npx @truefoundry/trueforge --port 3000
# or
PORT=3000 npx @truefoundry/trueforge

In hosted mode, change the host port mappings in docker-compose.yml instead.

Where does local mode store its data?

In a SQLite file in your OS’s application data directory. To put it somewhere else, set the SQLITE_PATH environment variable:

SQLITE_PATH=~/trueforge/db.sqlite npx @truefoundry/trueforge

What is PUBLIC_BASE_URL and when do I need to set it?

The public origin the server hands to MCP servers for OAuth callbacks. It defaults to http://localhost:<port>, which is correct as long as you access TrueForge from the same machine.Set it when the server is reachable at a different address — behind a domain, reverse proxy, or on another host:

PUBLIC_BASE_URL=https://trueforge.myorg.com npx @truefoundry/trueforge

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.

Next steps

Initial Setup

Models, MCP servers, skills, sandbox — and how catalogs work.

Create an Agent

Select resources and configure approvals, questions, and Generative UI.

Sessions

Inspect the run you just made: turns, tool calls, subagents, tokens, and timing.

Schedules

Run a saved agent on a recurring cadence, unattended.

Harness Capabilities

Subagents, deferred tools, code mode, compaction, and more.

SDK

Sessions, turns, events, and the agent spec.

Getting Started

TrueForge Harness

SDK

UI Chat

Project

Run TrueForge

Build your first agent

FAQ

Next steps

Initial Setup

Create an Agent

Sessions

Schedules

Harness Capabilities

SDK

​Run TrueForge

​Build your first agent

​FAQ

​Next steps

Initial Setup

Create an Agent

Sessions

Schedules

Harness Capabilities

SDK

Run TrueForge

Build your first agent

FAQ

Next steps