Forgebase Core

Forgebase Core is the independent core checkout of the Forgebase PostgreSQL-first data platform. It is a Node.js API that owns a single PostgreSQL schema and exposes a typed REST API, an official MCP interface, a JSON/CSV transfer surface, a browser Studio, and a TypeScript SDK. PostgreSQL is the only external system. Docker is not required: Forgebase runs directly on a host with Node.js, npm, and PostgreSQL.

This checkout is independent from the separate forgebase-agent-runtime module. It contains no dependency on PJM, Directus, ChatGPT, OpenCode, or any agent runtime. Autonomous runners and model execution are explicitly out of scope; the MCP interface is generic and Forgebase-owned. See CORE_BOUNDARY.

Current Scope

The implemented/pending checklist is in PROJECT_STATE.md.

• PostgreSQL-only connection lifecycle and /health.
• Configurable single operational schema through FORGEBASE_SCHEMA.
• Prefixed internal model (forgebase_*) installed explicitly and inspected before startup.
• Metadata synchronization for ordinary tables, columns, and foreign keys.
• Password login, JWT access tokens, rotating hashed refresh sessions, direct role permissions, optional policies, browser sessions, and administrator CLI.
• Authorized catalog reads, administrator-only transactional schema writes, generic transactional CRUD, relational M2O/O2M/M2M deep reads, relation-aware filters, aggregates, and bounded atomic command graphs for authorized tables.
• Local file storage with durable lifecycle reconciliation (no S3).
• PostgreSQL-backed automation with flows, jobs, and dedicated workers.
• An official Model Context Protocol (MCP) interface on GET/POST /mcp, authenticated with the same API tokens as REST, covering reads, aggregates, durable mutations with idempotency and delete confirmation, resources, and an embedded read-only MCP App.
• Forgebase Studio, a Nuxt SPA that talks to the API exclusively through the SDK.
• REST/SDK clients and authenticated OpenAPI discovery at /v1/openapi.json.

Not implemented: agent runtimes and model execution, PJM/Directus integration, GraphQL, realtime, OAuth/SSO, shares, editorial versioning, dashboards, full-text search, arbitrary user scripts, and model-provider execution. Bounded JSON import and JSON/CSV export are available through /v1/items/:collection/{import,export} and the SDK.

Requirements

• Node.js 24 and npm 10.
• A PostgreSQL database with a user that can create tables in the configured schema.
• No Docker, containers, or external services are required.

Configuration

Copy .env.example to .env. The application validates all runtime configuration.

FORGEBASE_SCHEMA=public
JWT_ACCESS_SECRET=change-this-development-access-secret-32-characters-minimum
JWT_ACCESS_TTL=15m
REFRESH_TOKEN_TTL=30d

FORGEBASE_SCHEMA defaults to public, accepts safe PostgreSQL identifiers, and is quoted centrally for dynamic SQL. The schema must already exist; Forgebase never creates it. DATABASE_URL is not supported; use POSTGRES_* variables. Integration tests create their own isolated schemas, so run them with FORGEBASE_SCHEMA unset (npm run test:integration:local does this for you).

Forgebase creates its internal tables in that schema with the forgebase_ prefix. Business tables may already exist. A database is exclusive to one logical Forgebase installation: forgebase:install rejects any existing forgebase_* table and never creates databases, users, roles, schemas, or functional records.

Development

All commands run on the host:

npm install
cp .env.example .env
npm run forgebase:install
npm run admin:create -- --email [email protected]
npm run token:create -- --email [email protected] --name development
npm run dev

The API and Studio share the origin under /admin/. A clean installation has no users; create an administrator explicitly after installation. start only runs when the configured schema is structurally installed; it never installs, migrates, or repairs PostgreSQL.

Installation lifecycle

npm run status is read-only and reports uninstalled, installed, incomplete, or incompatible for the configured schema. npm run forgebase:install creates the 12 internal tables in one transaction and leaves every table empty. It refuses any existing forgebase_* table instead of repairing or completing it. After install, use npm run admin:create -- --email ... to create the first user.

Optional modules such as the MCP interface, files, automation, security policies, and durable commands are delivered as explicit schema upgrades (mcp.upgrade, files.upgrade, automation.upgrade, ...) applied with the versioned schema-plan commands. A fresh core install stays at 12 tables until an upgrade is applied; startup never installs or migrates.

Forgebase does not migrate installations or promote data between schemas automatically. Explicit npm run schema -- status|snapshot|diff|plan|preflight|apply commands provide versioned, checksum-bound schema-plans for reviewed upgrades. Startup remains read-only. See schema upgrades.

Internal model

The configured schema contains 12 system tables:

forgebase_collection  forgebase_field       forgebase_relation
forgebase_role        forgebase_user        forgebase_permission
forgebase_session     forgebase_api_token   forgebase_setting
forgebase_migration   forgebase_activity    forgebase_revision

Only ordinary tables (pg_class.relkind = 'r') are managed. Tables, columns, and foreign keys detected by Forgebase receive persistent metadata automatically. Metadata is never deleted automatically. Forgebase system tables are first-class governed collections: catalog permissions control visibility, and item permissions control their reads and writes. Credential and hash fields are hidden and read-only, omitted from item payloads, and recursively redacted in audit data; schema DDL and metadata mutation remain unavailable for system collections.

Users have zero or one role. Permissions belong directly to roles and support exact collection/action values plus * wildcards. Refresh-token sessions store hashes only and preserve revocation and replacement-chain detection. API tokens are general-purpose hashed Bearer credentials tied to a real Forgebase user; they work for REST, SDK, and MCP clients alike.

MCP adds three module tables when mcp.upgrade is applied:

forgebase_mcp_idempotency   forgebase_mcp_confirmation   forgebase_mcp_audit

See docs/mcp.md for transport, authentication, tools, mutations, idempotency, confirmation, and audit.

Commands

npm run status
npm run schema -- status
npm run forgebase:install
npm run admin:create -- --email [email protected]
npm run token:create -- --email [email protected] --name development
npm run lint
npm run typecheck
npm test
npm run test:integration:local
npm run test:integration
npm run build
npm run dev
npm run dev:studio
npm run forgebase -- --help
npm run forgebase -- status
npm run forgebase -- update --backup
npm run forgebase -- start

Host updates

For installations managed as a Node project, forgebase update performs a read-only installation check, optionally creates a PostgreSQL custom-format backup, applies one reviewed schema plan when passed with --apply, verifies schema drift, records the installed package version in .forgebase/instance.json, without managing the process supervisor. forgebase start and npm start run the Node process in the foreground; process supervision is deliberately outside Forgebase and may be provided by systemd, PM2, Docker, Kubernetes, a hosting platform, or another operator-selected mechanism. It never overwrites .env, application data, or applies migrations implicitly.

npm install forgebase-core
npx forgebase-core init
npm update forgebase-core
npx forgebase update --backup

For an explicit schema upgrade, preflight and apply a plan in the same update:

npx forgebase update --apply releases/1.1.0.plan.json

The --apply path requires pg_dump, creates a backup before writing, repeats the plan checks at apply time, and uses the existing transactional migration journal. forgebase init creates a new .env with a generated JWT secret and an instance metadata file; it does not create PostgreSQL databases, roles, or schemas.

npm distribution

The source of truth is GitHub: development, forks, commits, pull requests, tags, and release review happen there. A version tag such as v0.1.0 runs the release workflow, validates the checkout, builds a self-contained package, and publishes forgebase-core to npm. The package exposes the forgebase command and includes the API, migrations, and generated Studio without requiring the Forgebase monorepo or private workspaces on the target host.

GET /health is public. GET /v1/system/schema is authenticated and exposes physical ordinary-table discovery through the shared catalog. All schema-write routes require a global * / * administrator permission and operate only on non-system tables in FORGEBASE_SCHEMA.

See ARCHITECTURE.md, CORE_BOUNDARY.md, docs/collections.md, docs/items-api.md, docs/schema-api.md, docs/mcp.md, docs/studio.md, and PROJECT_STATE.md. The docs/ directory also contains a clearly-marked historical archive from the extraction source; those files do not describe current Forgebase behavior.