Skip to content

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

Add fancy ascii art for standalone mode

Chirag Jaind72536cf11b3
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9f6529c79..32b8dce66 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -44,7 +44,7 @@ There are two dev topologies. Both serve the UI on [http://localhost:3000](http:
### Standalone (zero infra)
-SQLite only — good for most day-to-day development:
+SQLite only — good for most day-to-day development. Standalone mode is intended for local use; it is not a production-safe topology (no login by default, local SQLite). Please do not expose it beyond localhost.
```bash
pnpm standalone:dev
diff --git a/README.md b/README.md
index b6cd5956a..30c303344 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,8 @@ To work on TrueForge from this repository, see [CONTRIBUTING.md](CONTRIBUTING.md
| Local | Personal use, trying it out | SQLite | None | `npx @truefoundry/trueforge` |
| Hosted | Teams, multi-replica | Postgres | Postgres + Redis | Docker Compose or Helm |
+> **Local mode is for your machine only.** It is a convenient way to try TrueForge — not a production or internet-facing setup. There is no login by default, and data lives in a local SQLite file. Please keep it on localhost. We cannot take responsibility for data loss or unauthorized access if local mode is used beyond that. For a shared or production deployment, use hosted mode.
+
## Documentation
| Section | What you'll find |
diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdx
index 2b0ee18ca..9ee976f8a 100644
--- a/docs/authentication/overview.mdx
+++ b/docs/authentication/overview.mdx
@@ -14,7 +14,7 @@ Login in TrueForge is **optional**. Run it without auth for personal, local use,
| **OIDC login** | Hosted or shared team deployments | Sign-in with your IdP; each person is an `admin` or a `user` |
<Note>
- Standalone / local mode ignores OIDC even if the variables are set. OIDC login applies to hosted deployments (Docker Compose or Helm).
+ Standalone / local mode ignores OIDC even if the variables are set. OIDC login applies to hosted deployments (Docker Compose or Helm). Local mode is intended for personal use on your own machine — it is not a production or internet-facing setup. Please keep it on localhost; we cannot take responsibility for data loss or unauthorized access if it is used beyond that.
</Note>
## Option A — leave login off
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index 862a09c55..0f87a2a20 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -99,6 +99,13 @@ The agent features are identical in both modes — only the backend around the s
| **Extra infra** | None | Postgres + Redis |
| **Replicas** | Single process | Multiple replicas behind a load balancer. Redis peers them so streams and cancellations follow the client across replicas. |
+<Warning>
+ Local (standalone) mode is meant for personal use on your own machine. It is not hardened for production or shared
+ internet access — there is no login by default, and your 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
+ team or production deployment, use hosted mode with Postgres, Redis, and [login](/authentication/overview) enabled.
+</Warning>
+
## Start building
<CardGroup cols={3}>
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index f743daf42..bdb2d642b 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -18,6 +18,13 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**
Then open [http://localhost:8790](http://localhost:8790). The defaults work out of the box — see the [FAQ](#faq) to change the port or data location.
+ <Warning>
+ 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.
+ </Warning>
+
</Tab>
<Tab title="Hosted mode (Docker Compose)">
Runs the full hosted topology on your machine: the server (UI + API), Postgres, and Redis.
diff --git a/packages/trueforge/.env.example b/packages/trueforge/.env.example
index 763916b7b..7dcc44e2e 100644
--- a/packages/trueforge/.env.example
+++ b/packages/trueforge/.env.example
@@ -35,9 +35,11 @@ PORT=8790
# 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.
+## disables Redis/executor peering. Standalone is for local use only and is
+## not production-safe (no login by default; keep it on localhost). 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
## Absolute path to the SQLite database file. Used when STANDALONE=true;
diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.ts
index 7441a3616..8d0ff6fc7 100644
--- a/packages/trueforge/src/app.ts
+++ b/packages/trueforge/src/app.ts
@@ -33,6 +33,7 @@ import type { ISandboxProviderStore } from './db/sandboxProviderStore';
import type { ISkillStore } from './db/skillStore';
import type { WithTransaction } from './db/transaction';
import type { IOAuthTokenStore } from './mcp/auth/types';
+import { PACKAGE_VERSION } from './packageVersion';
import type { ActiveTurnRegistry } from './runtime/activeTurns';
import type { EventSubscriptionRegistry } from './runtime/event-subscription';
import { zodErrorResponse, zodValidationHook } from './zodErrorResponse';
@@ -70,7 +71,7 @@ const openApiDocConfig = {
'or `Authorization: Bearer` ID token. There is no built-in API-key scheme; ' +
'pass custom headers only if your reverse proxy or IdP layer requires them.\n\n' +
'Covers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.',
- version: '0.1.0',
+ version: PACKAGE_VERSION,
},
};
diff --git a/packages/trueforge/src/cli.ts b/packages/trueforge/src/cli.ts
index a107792da..4871d729b 100644
--- a/packages/trueforge/src/cli.ts
+++ b/packages/trueforge/src/cli.ts
@@ -11,12 +11,15 @@
*/
import { parseArgs } from 'node:util';
+import { PACKAGE_VERSION } from './packageVersion';
+
function printUsage(): void {
console.log(`Usage:
npx @truefoundry/trueforge
npx @truefoundry/trueforge --port <n>
-Start the agent server. Defaults to standalone mode (SQLite, no Redis).
+TrueForge v${PACKAGE_VERSION}. Start the agent server.
+Defaults to standalone mode (SQLite, no Redis) — local use only, not production-safe.
Set STANDALONE=false with Postgres and Redis for multi-replica peering.
Options:
diff --git a/packages/trueforge/src/logger.ts b/packages/trueforge/src/logger.ts
new file mode 100644
index 000000000..0c6479e57
--- /dev/null
+++ b/packages/trueforge/src/logger.ts
@@ -0,0 +1,79 @@
+/**
+ * Process logger: human-readable lines in standalone mode, JSON otherwise.
+ * Both formats include `version` (defaultMeta) so hosted aggregators can filter.
+ */
+import winston, { type Logger } from 'winston';
+
+const STANDALONE_META_SKIP = new Set(['level', 'message', 'timestamp', 'version', 'stack', 'splat']);
+
+export function shouldColorize(): boolean {
+ const noColor = process.env['NO_COLOR'];
+ if (noColor !== undefined && noColor !== '') {
+ return false;
+ }
+ const forceColor = process.env['FORCE_COLOR'];
+ if (forceColor === '0') {
+ return false;
+ }
+ if (forceColor !== undefined && forceColor !== '') {
+ return true;
+ }
+ return process.stderr.isTTY;
+}
+
+function standaloneMeta(info: object): string {
+ const copied: Record<string, unknown> = { ...info };
+ const meta: Record<string, unknown> = {};
+ for (const key of Object.keys(copied)) {
+ if (STANDALONE_META_SKIP.has(key)) {
+ continue;
+ }
+ meta[key] = copied[key];
+ }
+ if (Object.keys(meta).length === 0) {
+ return '';
+ }
+ return ` ${JSON.stringify(meta)}`;
+}
+
+function standaloneFormat(color: boolean): winston.Logform.Format {
+ const parts: winston.Logform.Format[] = [
+ winston.format.timestamp({ format: 'HH:mm:ss' }),
+ winston.format.errors({ stack: true }),
+ ];
+ if (color) {
+ parts.push(winston.format.colorize({ level: true }));
+ }
+ parts.push(
+ winston.format.printf(info => {
+ const extra = standaloneMeta(info);
+ const stack = typeof info['stack'] === 'string' ? `\n${info['stack']}` : '';
+ return `${String(info['timestamp'])} ${info.level} ${String(info.message)}${extra}${stack}`;
+ }),
+ );
+ return winston.format.combine(...parts);
+}
+
+function jsonFormat(): winston.Logform.Format {
+ return winston.format.combine(
+ winston.format.timestamp(),
+ winston.format.errors({ stack: true }),
+ winston.format.json(),
+ );
+}
+
+function serverLogFormat(options: { standalone: boolean }): winston.Logform.Format {
+ if (options.standalone) {
+ return standaloneFormat(shouldColorize());
+ }
+ return jsonFormat();
+}
+
+export function createServerLogger(options: { level: string; standalone: boolean; version: string }): Logger {
+ return winston.createLogger({
+ level: options.level,
+ defaultMeta: { version: options.version },
+ format: serverLogFormat({ standalone: options.standalone }),
+ transports: [new winston.transports.Console()],
+ });
+}
diff --git a/packages/trueforge/src/main.ts b/packages/trueforge/src/main.ts
index 0b5ff94d5..6611fc6ef 100644
--- a/packages/trueforge/src/main.ts
+++ b/packages/trueforge/src/main.ts
@@ -36,7 +36,7 @@ import {
import { RequestReplyExecutor, RequestReplyRouter } from '@truefoundry/trueforge-core/request-reply';
import type { Transaction } from 'kysely';
import type { RedisClientType } from 'redis';
-import winston, { type Logger } from 'winston';
+import type { Logger } from 'winston';
import { createServerApp } from './app';
import { initOidc } from './auth/oidc';
@@ -54,9 +54,12 @@ import type { ISkillStore } from './db/skillStore';
import type { Database as SqliteDatabase } from './db/sqlite/types';
import type { WithTransaction } from './db/transaction';
import { mountFrontend } from './frontend';
+import { createServerLogger, shouldColorize } from './logger';
import type { IOAuthTokenStore } from './mcp/auth/types';
+import { PACKAGE_VERSION } from './packageVersion';
import { ActiveTurnRegistry } from './runtime/activeTurns';
import { EventSubscriptionRegistry } from './runtime/event-subscription';
+import { printStandaloneStartupBanner } from './startupBanner';
/** Persistence + optional Redis wired for the selected topology. */
interface ServerPersistence<TTransaction> {
@@ -237,13 +240,18 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
}
try {
- // Console logger shared by the server runtime (harness components require one).
- const logger = winston.createLogger({
+ const logger = createServerLogger({
level: configuration.LOG_LEVEL,
- format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
- transports: [new winston.transports.Console()],
+ standalone: configuration.STANDALONE,
+ version: PACKAGE_VERSION,
});
+ if (configuration.STANDALONE) {
+ printStandaloneStartupBanner({ version: PACKAGE_VERSION, color: shouldColorize() });
+ } else {
+ logger.info('TrueForge starting', { mode: 'distributed' });
+ }
+
const { activeTurns, app, destroyDb, redis, requestReplyRouter } = configuration.STANDALONE
? await createServerRuntime(
await createStandalonePersistence({ sqlitePath: configuration.SQLITE_PATH, logger }),
@@ -289,7 +297,7 @@ try {
}
const server = serve({ fetch: app.fetch, port: configuration.PORT }, info => {
- console.log(`Agent server listening on http://localhost:${String(info.port)} (docs at /api/v1/docs)`);
+ logger.info(`Agent server listening on http://localhost:${String(info.port)} (docs at /api/v1/docs)`);
});
server.on('error', (error: unknown) => {
diff --git a/packages/trueforge/src/packageVersion.ts b/packages/trueforge/src/packageVersion.ts
new file mode 100644
index 000000000..dc6ac2aae
--- /dev/null
+++ b/packages/trueforge/src/packageVersion.ts
@@ -0,0 +1,26 @@
+/**
+ * Package version for logs, the OpenAPI document, and the CLI.
+ *
+ * Read from `package.json` next to this module's package root — the same
+ * `src/` vs `dist/` layout as `config.ts` (`import.meta` → parent).
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function readPackageVersion(): string {
+ const packageJsonPath = path.join(PACKAGE_ROOT, 'package.json');
+ const parsed: unknown = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+ if (typeof parsed !== 'object' || parsed === null || !('version' in parsed)) {
+ throw new Error(`${packageJsonPath} is missing a version field`);
+ }
+ const { version } = parsed;
+ if (typeof version !== 'string' || version.length === 0) {
+ throw new Error(`${packageJsonPath} version must be a non-empty string`);
+ }
+ return version;
+}
+
+export const PACKAGE_VERSION = readPackageVersion();
diff --git a/packages/trueforge/src/startupBanner.ts b/packages/trueforge/src/startupBanner.ts
new file mode 100644
index 000000000..e34eb310e
--- /dev/null
+++ b/packages/trueforge/src/startupBanner.ts
@@ -0,0 +1,127 @@
+/**
+ * Standalone boot chrome: wordmark, version, and a boxed local-only warning.
+ * Printed raw (not through winston) so the art is not prefixed with timestamps.
+ */
+
+const STANDALONE_MODE_DISCLAIMER =
+ 'Standalone mode is intended for local use on your own machine. It is not hardened for production or shared internet access — please keep it on localhost. We cannot take responsibility for data loss or unauthorized access if this mode is used beyond that.';
+
+/** ANSI Shadow glyphs used to render `TRUEFORGE`. Each letter is six equal-width rows. */
+const ANSI_SHADOW: Record<string, readonly string[]> = {
+ T: ['████████╗', '╚══██╔══╝', ' ██║ ', ' ██║ ', ' ██║ ', ' ╚═╝ '],
+ R: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██║ ██║', '╚═╝ ╚═╝'],
+ U: ['██╗ ██╗', '██║ ██║', '██║ ██║', '██║ ██║', '╚██████╔╝', ' ╚═════╝ '],
+ E: ['███████╗', '██╔════╝', '█████╗ ', '██╔══╝ ', '███████╗', '╚══════╝'],
+ F: ['███████╗', '██╔════╝', '█████╗ ', '██╔══╝ ', '██║ ', '╚═╝ '],
+ O: [' ██████╗ ', '██╔═══██╗', '██║ ██║', '██║ ██║', '╚██████╔╝', ' ╚═════╝ '],
+ G: [' ██████╗ ', '██╔════╝ ', '██║ ███╗', '██║ ██║', '╚██████╔╝', ' ╚═════╝ '],
+};
+
+const WORDMARK_TEXT = 'TRUEFORGE';
+const WARNING_INNER_WIDTH = 72;
+const BRAND_COLOR = '\x1b[38;5;99m';
+const YELLOW = '\x1b[33m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+function glyphFor(ch: string): readonly string[] {
+ const glyph = ANSI_SHADOW[ch];
+ if (glyph === undefined) {
+ throw new Error(`No ASCII glyph for ${JSON.stringify(ch)}`);
+ }
+ return glyph;
+}
+
+function rowOf(glyph: readonly string[], row: number): string {
+ const cell = glyph[row];
+ if (cell === undefined) {
+ throw new Error(`Glyph is missing row ${String(row)}`);
+ }
+ return cell;
+}
+
+function renderTrueForgeWordmark(): string {
+ const glyphs: (readonly string[])[] = [];
+ for (let i = 0; i < WORDMARK_TEXT.length; i += 1) {
+ const ch = WORDMARK_TEXT[i];
+ if (ch === undefined) {
+ throw new Error(`Missing character at index ${String(i)}`);
+ }
+ glyphs.push(glyphFor(ch));
+ }
+ const rowCount = glyphs[0]?.length;
+ if (rowCount === undefined) {
+ throw new Error('Wordmark text must not be empty');
+ }
+ const rows: string[] = [];
+ for (let row = 0; row < rowCount; row += 1) {
+ rows.push(glyphs.map(glyph => rowOf(glyph, row)).join(''));
+ }
+ return rows.join('\n');
+}
+
+function wrapText(text: string, width: number): string[] {
+ const words = text.split(/\s+/).filter(word => word.length > 0);
+ const lines: string[] = [];
+ let current = '';
+ for (const word of words) {
+ if (current.length === 0) {
+ if (word.length > width) {
+ lines.push(word);
+ } else {
+ current = word;
+ }
+ continue;
+ }
+ const next = `${current} ${word}`;
+ if (next.length <= width) {
+ current = next;
+ } else {
+ lines.push(current);
+ current = word.length > width ? '' : word;
+ if (word.length > width) {
+ lines.push(word);
+ }
+ }
+ }
+ if (current.length > 0) {
+ lines.push(current);
+ }
+ return lines;
+}
+
+function paint(options: { text: string; color: string; enabled: boolean }): string {
+ if (!options.enabled) {
+ return options.text;
+ }
+ return `${options.color}${options.text}${RESET}`;
+}
+
+function warningBox(message: string): string {
+ const label = ' WARNING ';
+ const inner = wrapText(message, WARNING_INNER_WIDTH);
+ const width = Math.max(WARNING_INNER_WIDTH, ...inner.map(line => line.length), label.length);
+ const topPad = width + 1 - label.length;
+ const top = `┌─${label}${'─'.repeat(topPad)}┐`;
+ const body = inner.map(line => `│ ${line.padEnd(width)} │`);
+ const bottom = `└${'─'.repeat(width + 2)}┘`;
+ return [top, ...body, bottom].join('\n');
+}
+
+function formatStandaloneStartupBanner(options: { version: string; color: boolean }): {
+ wordmark: string;
+ warning: string;
+} {
+ const { version, color } = options;
+ const wordmark = paint({ text: renderTrueForgeWordmark(), color: `${BOLD}${BRAND_COLOR}`, enabled: color });
+ const subtitle = paint({ text: ` TrueForge v${version} · standalone`, color: DIM, enabled: color });
+ const warning = paint({ text: warningBox(STANDALONE_MODE_DISCLAIMER), color: `${BOLD}${YELLOW}`, enabled: color });
+ return { wordmark: `\n${wordmark}\n${subtitle}\n`, warning };
+}
+
+export function printStandaloneStartupBanner(options: { version: string; color: boolean }): void {
+ const { wordmark, warning } = formatStandaloneStartupBanner(options);
+ console.log(wordmark);
+ console.warn(warning);
+}