TrueForge (truefoundry/trueforge) is Atlas's general agent runtime. It is the first agents-family service where agents are saved configurations, not code. You pick a model, attach MCP tool connectors, set an approval policy, and optionally add a schedule. It complements the fixed-purpose agents (Local Deep Researcher, Hermes, OpenClaw). Atlas adopted it at upstream v0.2.0 as an experimental-tier service after the #1159 evaluation.

The family runs three containers off one image:

• trueforge — the server: API, chat UI, session/turn execution.
• trueforge-controller — the schedule dispatcher (hourly/daily/weekly unattended runs).
• trueforge-init — one-shot settings seeding on every start (model provider + MCP connector), then exits.

Boundary vs Open WebUI: Open WebUI is the RAG chat surface — conversations, knowledge collections, document Q&A. TrueForge is the agent harness — tool-using agents with human approval gates, schedules, and per-session cost accounting. For "talk to my documents", use Open WebUI. For "an agent that acts through tools, on demand or on a schedule", use TrueForge.

Platform note: upstream publishes a linux/amd64 image only; on Apple Silicon, Docker Desktop runs it under emulation (same arrangement as chatterbox and docling).

TrueForge has no login of its own. The OIDC triple is unset, so the server runs with its fixed local admin identity: anyone who can reach it is admin (see §4.3).

TRUEFORGE_SOURCE=disabled             # container | disabled
TRUEFORGE_IMAGE=tfy.jfrog.io/tfy-images/trueforge:0.2.0-8b1d98e   # pinned upstream image
TRUEFORGE_PORT=                       # topology-assigned
TRUEFORGE_ENDPOINT=                   # auto-managed
TRUEFORGE_API_KEY=                    # auto-generated
TRUEFORGE_DB_NAME=trueforge           # dedicated database on supabase-db
TRUEFORGE_DB_USER=trueforge
TRUEFORGE_DB_PASSWORD=atlas-db-password   # placeholder; replaced on first start

Enable with ./start.sh --trueforge-source container or through the wizard (track gen-ai-eng). Everything else is derived:

• The Supabase init chain creates the database and its owner role (idempotent).
• The bootstrapper keeps the *_URI DSN twins in sync.
• TRUEFORGE_API_KEY (the controller→server credential) is generated on first run and then kept.

Model, MCP, skill and sandbox configuration does not use env catalogs. trueforge-init seeds the live settings API instead (§4.2). That survives image upgrades and follows what the LiteLLM gateway serves.

• Postgres: a dedicated trueforge database on the shared supabase-db, owned by a restricted trueforge role (the litellm/langfuse isolation pattern). The tables are in a trueforge schema.
• Redis: the shared stack Redis on logical database 5, used only for executor peering (cross-replica turn cancellation).
• Kong: trueforge.localhost fronts the UI/API; PUBLIC_BASE_URL points at the Kong URL so MCP OAuth/DCR callbacks resolve.

1. Reads the gateway's live /v1/models catalog. It rejects an empty or unusable catalog before key generation. A failed read also stops init. TrueForge keeps its working key.

2. Reads all key-inventory pages and captures only settled generations with the exact Atlas ownership metadata and generation-alias format. If inventory is unavailable, it defers retirement and continues the mint/fallback path.

3. Mints a LiteLLM virtual key with a unique trueforge-<uuid> alias and marks it pending. Previous keys stay valid. Mint failure retains the logged master-key fallback.

4. Writes one custom provider (atlas-litellm → http://litellm:4000/v1) with the new key and catalog. It checks the provider confirmation before marking the key settled.

   All enabled Ollama and cloud models arrive through this provider. Ollama needs no direct wiring. Model availability follows the gateway at every restart.

5. Marks the replacement confirmed, then deletes only settled hashes captured before minting. It re-reads inventory to verify their removal. User-owned keys remain untouched.

6. When MCP_SERVERS_SOURCE=container, registers the in-stack atlas-tools MCP connector (http://mcp-servers:8000/mcp, streamable HTTP, no auth on the internal network). Its tools (Supabase Postgres queries, Neo4j graph queries, SearXNG web search) sit behind TrueForge's per-tool-call approvals and @write/@destructive gating.

   When the family is disabled, the pinned v0.2.0 settings API has no DELETE. The init therefore parks the connector on an unresolvable RFC 2606 .invalid address with a [disabled by Atlas] description. Re-enabling restores it without duplicates.

   Saved agents that reference the parked connector still start. Upstream rejects a session only when a referenced connector name is missing from settings (Unknown MCP server … — not configured). Calls to the parked tools fail at connect time, after upstream's MCP_CONNECT_TIMEOUT_MS (default 30 s).

   atlas-tools is reserved for Atlas; do not create a connector with that name. Atlas never changes user-created connectors.

A timed-out provider write can still finish on the server. Its key stays pending and remains valid. Legacy alias keys also remain valid. Reconcile these keys only after all earlier provider writes are known to have finished. The initializer never deletes pending or legacy keys automatically.

Successful serialized runs retire settled generation keys. Concurrent successes can leave additional confirmed generations, which a later serialized run retires. Logs report retained-key counts without credential values or hashes.

The pinned LiteLLM key API and TrueForge provider API define the endpoint contracts.

Settings writes replace by name. Each HTTP call has a per-request timeout, and the whole init has a 5-minute budget. A hung peer fails the init with the operation name. SIGTERM aborts in-flight work at once.

• No OIDC (fixed admin identity): the same network-trusted tier as the other Atlas UIs. Two mitigations apply. The Kong route has the dashboard-user basic-auth/ACL guard. The model provider normally holds a scoped LiteLLM virtual key, not raw provider credentials. If key minting fails, init uses the LiteLLM master key until the next start (§4.2). Wire the OIDC_* triple to an external IdP before any exposure beyond a trusted host.
• Skills and sandbox execution are off: no skill sources or sandbox provider are configured. The pinned settings API exposes Daytona only. TrueForge rejects agent specs that request either at session creation, so the boundary is explicit.

TrueForge is not wired to Langfuse directly — and does not need to be. All model traffic transits LiteLLM, so the existing LiteLLM→Langfuse success-callback path captures cost, tokens, and latency per agent turn whenever LANGFUSE_SOURCE=container. TrueForge additionally records per-turn token counts and total_cost_in_usd on its own sessions, visible in the UI.

Schedules run agents (goal-seeking, tool-using, non-deterministic) hourly, daily or weekly. Neither n8n (event-driven deterministic workflows) nor Airflow (data DAGs) covers this. Deterministic multi-step automation belongs in n8n. Data pipelines belong in Airflow. n8n's MCP Server Trigger can expose a workflow as an agent tool; that is the intended bridge.

Support tier: experimental — Capability contract declared for upstream v0.2.0; no cited cold-start, workflow, or upgrade qualification run yet (evidence at v0.1.0).

• trueforge exits immediately at boot: the server validates its full env contract at startup and refuses any invalid value. docker logs ${PROJECT_NAME}-trueforge names the variable. Usual causes:
  • an unprovisioned database: check that supabase-db-init completed;
  • an empty TRUEFORGE_API_KEY: run ./start.sh once so the bootstrapper generates it. Do not hand-write .env from scratch.
• No models in the UI: trueforge-init seeds the provider from LiteLLM's live catalog; check docker logs ${PROJECT_NAME}-trueforge-init. An empty gateway catalog (e.g. LLM_PROVIDER_SOURCE=none with no cloud keys) fails the seed on purpose rather than registering a dead provider.
• Agent creation rejected with a skills/sandbox error: expected: Atlas configures neither (§4.3). Remove the skills/sandbox blocks from the agent spec.
• Schedules never fire: the controller is a separate container. Check docker logs ${PROJECT_NAME}-trueforge-controller. Check that TRUEFORGE_API_KEY is the same for server and controller; it is, unless .env was edited by hand.
• Slow first boot on Apple Silicon: the amd64 image runs emulated; allow extra start-up time before the healthcheck settles (the compose healthcheck budgets for this).

Open the full-size diagram for a full-screen view.

No high-confidence opportunities identified.

No high-confidence opportunities identified.

No high-confidence opportunities identified.