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.
Local mode (npx)
Hosted mode (Docker Compose)
Hosted mode (Kubernetes)
Requires Node.js 22 or newer. One command, no other infrastructure — the UI and backend run locally, and data is stored in a local SQLite file:
npx @truefoundry/trueforge
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 trueforgecp packages/trueforge/.env.example packages/trueforge/.envdocker compose up --build
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.
Local mode (npx) uses SQLite and needs no other services. Docker Compose and Kubernetes run hosted mode: Postgres
replaces SQLite as durable storage, and Redis peers the replicas so streams and cancellations follow the client
across them.
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.
1
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.
Pick a provider from the catalog.
Paste an API key and click Create.
2
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.
3
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.
4
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.
Back in the chat, assemble the agent for this conversation. Pick a model from the selector in the composer, then open the Tools menu and set three things:
Connectors — enable Exa.
Skills — enable web-artifacts-builder.
Capabilities — leave Dynamic sub-agents on (it’s the default). This lets the agent research each item in parallel instead of one at a time.
Connectors
Skills
Capabilities
Then send your first message. 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 result — an interactive brief the agent built from its web research: a comparison, feature chips, and a strengths chart.
6
Save it as an agent
Happy with the setup? Click Save Agent, then in Save agent give it a name and instructions and click Save changes — this captures the model, connectors, skills, and prompt together as a reusable agent. For this example:
Name — web-research-brief
Instructions —
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.
7
Find it in the Agents Library
Open Agents Library from the sidebar. Your saved agent is there — click Try to start a fresh chat with the same setup, or Edit to tweak it. See Agent Library for shared-visibility notes in hosted mode.
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:
