ObjectStack

The ontology is the software.

One executable business ontology. AI writes it, the runtime runs it, agents operate it, you own it.

本体即软件。

Apps small enough for AI to hold whole.

Executable · AI-writable · Agent-operable · You own it · Apache-2.0

_{1 · One definition, and the app runs  ·  2 · An agent creates a record over MCP  ·  3 · A read-only identity is refused}
▶  Watch: ObjectStack in 90 Seconds

You build & ask with Claude Code or any coding agent: the agent writes the metadata in your repo and operates the running app over MCP. Want the same loop hosted, in the browser, nothing to install? That's ObjectOS, the commercial runtime environment built on this stack.

_{One typed definition → database · REST API · client SDK · UI · MCP tools.}

Try it in five minutes

1 · Create a project. The scaffolder installs the AI skills bundle and writes an AGENTS.md, so your agent starts with the protocol's rules already loaded — not with generic "write me some TypeScript" priors.

npm create objectstack@latest my-app && cd my-app

2 · Describe the requirement. Open the project in Claude Code (or Cursor, Copilot, …) and say what the business needs:

Build a support desk. Add a ticket object with subject, description, a priority select and a status select. Add a Resolve action that only shows on tickets that aren't already resolved. Add an "Open tickets" list view and a Support nav group. Run npm run validate when you're done.

The agent writes typed metadata — not a codebase. The gate rejects what would fail silently at runtime, and the agent fixes it before you ever see it.

3 · Preview in the browser.

npx os dev --ui   # → http://localhost:3000/_console/

The Console renders the real app — records, boards, dashboards. Something wrong? Say what to change. Requirement changes run the same loop, on a diff you can actually read.

No install at all? Open a live app on StackBlitz.

_{Prefer clicking? Studio authors the same metadata visually — same artifacts, same gate.}

What we mean by ontology

Your app's definition — objects and fields, relations, actions, permissions, flows, and agent and tool definitions — is a business ontology: open, versioned, and yours, not code scattered across a framework. It is executable, not a knowledge-representation ontology: no inheritance, no axioms, no reasoner — validated rather than reasoned over — and it is not a semantic layer over your existing systems (federating an external datasource is read-only by default and early). Views, dashboards, apps, and translations are projections of the ontology, not part of it, and code does not disappear: it moves into the runtime, as hooks, action bodies, CEL, and constrained JSX. The full account is Business Ontology; the short form is the glossary entry.

The runtime runs it

Point an agent at an empty repo and you get a one-off codebase: every screen hand-invented, every mistake yours to find at runtime. ObjectStack gives the agent a vocabulary instead — typed, validated primitives for what enterprise software is actually made of. The agent composes the definition; the runtime already knows how to run it.

	Capability
Objects & fields	Typed schemas with relations, validation, formulas, files
Permissions	RBAC plus row- and field-level security, enforced by the runtime
Automation	DAG flows, record triggers, scheduled jobs, webhooks
Approvals	Multi-step chains with queues and a full audit trail
Views	Lists, kanban, calendars, gantt, galleries — declared, not coded
Dashboards & reports	Charts, aggregations, KPIs bound to live data
Actions	Permission-checked buttons and server operations
APIs & SDK	Generated REST + realtime endpoints, typed client SDK
AI tools	Every object and exposed action doubles as a governed MCP tool
Translations	Labels and UI text as metadata, per locale
Seed data	Fixtures and demo datasets that ship with the app
Datasources	PostgreSQL, MySQL, SQLite, MongoDB, or in-memory

Here's the shape of it — one object, and the database table, REST API, UI views, and MCP tools all follow:

import { ObjectSchema, Field } from '@objectstack/spec/data';

export const Ticket = ObjectSchema.create({
  name: 'support_desk_ticket',
  label: 'Ticket',
  sharingModel: 'private',            // org-wide default — the security gate requires it
  fields: {
    subject: Field.text({ label: 'Subject', required: true, searchable: true }),
    status: Field.select({
      label: 'Status',
      required: true,
      options: [
        { label: 'Open', value: 'open', color: '#3B82F6', default: true },
        { label: 'Resolved', value: 'resolved', color: '#10B981' },
      ],
    }),
    due_date: Field.date({ label: 'Due Date' }),
  },
});

The REST API exists the moment the object does — no controllers to write. It runs under the same permissions as the UI, so a data call needs a session: sign in once as the dev admin os dev seeds on an empty database, then call it.

curl -c cookies.txt -X POST http://localhost:3000/api/v1/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@objectos.ai","password":"admin123"}'

curl -b cookies.txt http://localhost:3000/api/v1/data/support_desk_ticket

In the browser, the typed client SDK and React hooks (useQuery, useMutation, usePagination) live in @objectstack/client-react.

Agents are the first users

Objects are tools, actions are tools, permissions decide what an agent may call, and audit records what it did. Because the app is typed metadata, the runtime serves it as an MCP server at /api/v1/mcp — on by default. Point any MCP client at it and an agent can inspect and operate the app you just built, under the same permissions and RLS as a human:

claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp

The first tool call opens a browser to sign you in — each deployment is its own OAuth server, so there's no token to copy-paste. Headless setups (CI, containers) use an API key instead. Objects are exposed automatically; actions opt in with ai: { exposed: true }. See Connect an MCP Client for both flows.

Why the mistakes don't ship

"AI writes it" is only useful if AI's mistakes don't reach production. Four gates stand between the agent and your users:

Gate	Catches
Typed	Strict TypeScript + Zod — shape errors die in the editor, seconds after the agent writes them
Validated	os validate rejects metadata that type-checks but would fail silently at runtime: dangling bindings, bad CEL predicates, missing security posture
Reviewed	You approve a small readable diff in the Console — not a pile of generated glue
Governed	The runtime enforces permissions and audit on every call, so even a wrong app stays inside the fence

The reason this works is the same reason TypeScript was the right host language: an agent's errors become located, corrective text it can read and fix itself, in seconds — instead of a silent runtime failure nobody traces back.

The other half is size: apps small enough for AI to hold whole. The bundled example CRM — examples/app-crm: objects, views, a dashboard, a lead-conversion flow, permission sets, actions, translations — is small enough for an agent to load end-to-end, reason about every dependency, and refactor across data, API, UI, and permissions in one change. It can answer "what breaks if I change this?" instead of grepping and hoping. Measure it yourself:

find examples/app-crm/src -name '*.ts' -not -name '*.test.ts' | xargs cat | wc -l

You own it

Everything in this repo is the open stack — protocol, microkernel, SDK, CLI, and the production runtime, Apache-2.0 with no open-core asterisks (LICENSING.md). The definition lives in your repository as ordinary TypeScript, versioned in your VCS and reviewable as a diff — not a graph held inside a vendor's system.

The ontology is the software. Your objects, relations, actions, permissions, flows, and agent and tool definitions are your business ontology — and the definition layer of the AI era should be an open protocol you own. Read why.

Ship it

The scaffolded project is container-ready, on the official runtime image ghcr.io/objectstack-ai/objectstack:

docker build -t my-app . && docker compose up -d   # app + Postgres

See Self-Hosted Deployment for bare Node, Kubernetes, and the secrets you must pin — and Build with Claude Code to run the whole loop end-to-end.

Hack on the framework

git clone https://github.com/objectstack-ai/objectstack.git
cd objectstack
pnpm install          # Node 22+, pnpm 10 (corepack enable)
pnpm build            # build all packages
pnpm objectui:build   # build the Console SPA (not part of pnpm build)
pnpm dev              # showcase example: REST + Console on :3000

pnpm objectui:build builds objectui at the commit pinned in .objectui-sha into packages/console/dist (gitignored). It builds from a ../objectui checkout if one sits next to this repo, otherwise from a shallow clone of objectui into .cache/; either way it installs objectui's dependencies, so it needs network. Skip it and pnpm dev still serves the REST API, without the Console. Rerun it when .objectui-sha moves.

A first run is slow, not stuck. Measured once on a fresh clone of main (4-vCPU container, Node 22.22, pnpm 10.31):

Command	Time
pnpm install	16 s
pnpm build	6 m 54 s	72 turbo tasks
pnpm objectui:build	10 m 36 s	clones objectui and builds the Console
pnpm test	54 m 03 s	the full suite: 135 turbo tasks

For your own change, test what it reaches instead of the full suite:

pnpm turbo run test --affected          # packages your branch changes, and their dependents
pnpm --filter @objectstack/<pkg> test   # one package

--affected compares your branch with your local main, so a stale main widens the set; keep it current, or set TURBO_SCM_BASE=origin/main.

Other examples: pnpm dev:crm, pnpm dev:todo. Docs site: pnpm docs:dev. AGENTS.md is the working rulebook for both humans and agents; CONTRIBUTING.md covers the workflow.

Three layers sit on a microkernel — ObjectQL (data), Kernel (control), ObjectUI (view). Everything starts as a Zod schema; TypeScript types, JSON Schemas, REST routes, UI metadata, and agent tools are all derived from that one source. The kernel provides only DI, the event bus, and lifecycle; every capability — drivers, server, auth, security, automation, AI — is a plugin.

Design details, the plugin lifecycle state machine, and the dependency graph are in ARCHITECTURE.md.

CLI

The CLI binary ships as both os and objectstack; os --help lists everything.

os init [name]    # Scaffold a new project
os create         # Interactive project / object scaffolder
os dev            # Dev server with hot-reload (REST + console)
os start          # Production server
os compile        # Build a deployable JSON environment artifact
os serve          # Serve a compiled artifact
os validate       # Validate metadata against the protocol
os lint           # Lint metadata for best-practice violations
os verify         # Boot the app in-process and verify it over real HTTP
os generate       # Scaffold objects, views, flows, agents, migrations
os diff           # Diff two metadata artifacts
os doctor         # Check environment health
os explain        # Explain protocol concepts on the command line

Cloud, package registry, secrets, and environment subcommands (os package …, os environments …, os login, os cloud …) target an ObjectStack Cloud control plane.

Package directory

Everything in packages/, grouped by layer — click to expand.

Protocol & core

Package	Description
@objectstack/spec	The protocol — Zod schemas, TypeScript types, JSON Schemas, constants
@objectstack/core	Microkernel — plugin system, DI container, EventBus, Logger
@objectstack/types	Shared interfaces describing the runtime environment
@objectstack/formula	Expression engine — CEL plus the ObjectStack stdlib, for formulas, predicates, defaults
@objectstack/platform-objects	Built-in platform objects — identity, security, audit, tenant, metadata
@objectstack/lint	Static validation of a metadata graph, shared by os validate and AI authoring
@objectstack/sdui-parser	Constrained JSX source → SDUI schema tree compiler (parse, never execute)

Engine

Package	Description
@objectstack/objectql	Isomorphic ObjectQL query engine and schema registry
@objectstack/runtime	Runtime bootstrap — DriverPlugin, AppPlugin, environment artifacts
@objectstack/rest	Auto-generated REST API layer
@objectstack/metadata	Metadata loading, saving, and persistence
@objectstack/metadata-core	Metadata repository contracts — types, canonicalization, errors
@objectstack/metadata-fs	File-system metadata repository (JSON files + JSONL change log)
@objectstack/metadata-protocol	Metadata management protocol — CRUD, draft/publish, locks, diagnostics
@objectstack/observability	Metrics, error reporting, and logging contracts with noop / console / OTLP exporters
@objectstack/verify	Boot an app in-process and verify it through the real HTTP stack

Drivers

Package	Description
@objectstack/driver-memory	In-memory driver (development, testing, reference implementation)
@objectstack/driver-sql	SQL driver — PostgreSQL, MySQL, SQLite via Knex
@objectstack/driver-mongodb	MongoDB driver over the official client
@objectstack/driver-turso	Turso / libSQL driver — edge-first SQLite with embedded replicas
@objectstack/driver-sqlite-wasm	WASM SQLite driver for browsers and WebContainers (StackBlitz)

Client

Package	Description
@objectstack/client	Client SDK — CRUD, batch API, error handling
@objectstack/client-react	React hooks — useQuery, useMutation, usePagination

Plugins

Package	Description
@objectstack/plugin-hono-server	Hono-based HTTP server plugin
@objectstack/hono	Hono adapter — Node.js, Bun, Deno, Cloudflare Workers
@objectstack/mcp	MCP server — exposes objects and AI tools over stdio and Streamable HTTP
@objectstack/plugin-auth	Authentication and identity (better-auth)
@objectstack/plugin-security	RBAC, row-level and field-level security
@objectstack/plugin-sharing	Record-level sharing and sharingModel enforcement
@objectstack/organizations	Multi-organization row-level isolation
@objectstack/plugin-approvals	Multi-step approval engine
@objectstack/plugin-audit	Audit log object and audit trail
@objectstack/plugin-email	Pluggable outbound email transport
@objectstack/plugin-webhooks	Durable, cluster-aware outbound webhook delivery
@objectstack/plugin-pinyin-search	Pinyin recall for CJK search
@objectstack/plugin-dev	Zero-config local development assembly
@objectstack/knowledge-memory	In-memory knowledge adapter (dev / test)
@objectstack/knowledge-ragflow	RAGFlow knowledge adapter
@objectstack/embedder-openai	OpenAI-compatible embedder (OpenAI, DashScope, Ollama, and any drop-in endpoint)

Connectors & triggers

Package	Description
@objectstack/connector-rest	Generic REST connector for the automation engine
@objectstack/connector-openapi	Connector actions generated from an OpenAPI document
@objectstack/connector-mcp	Any MCP server's tools as connector actions
@objectstack/connector-slack	Slack Web API connector
@objectstack/trigger-record-change	Launch flows on insert / update / delete
@objectstack/trigger-schedule	Launch flows on a cron, interval, or one-off schedule
@objectstack/trigger-api	Inbound HTTP / webhook flow trigger with HMAC verification

Services

Package	Description
@objectstack/service-automation	Automation engine — DAG flows, triggers, workflow state machines
@objectstack/service-analytics	Aggregations, time series, funnels, dashboards
@objectstack/service-realtime	Real-time events and subscriptions
@objectstack/service-job	Cron and interval job scheduler
@objectstack/service-queue	Background job queue — in-memory or durable DB-backed
@objectstack/service-cache	Cache — in-memory and Redis
@objectstack/service-cluster	Cluster primitives — PubSub, Lock, KV, Counter
@objectstack/service-cluster-redis	Redis driver for the cluster service
@objectstack/service-storage	File storage — local filesystem and S3
@objectstack/service-datasource	External-table federation and datasource lifecycle
@objectstack/service-settings	Settings — manifest registry and K/V resolver (env > tenant > user)
@objectstack/service-i18n	Internationalization
@objectstack/service-messaging	Outbound notification dispatch across channels
@objectstack/service-sms	SMS delivery (Aliyun, Twilio, log)
@objectstack/service-knowledge	Knowledge / RAG orchestration over pluggable adapters
@objectstack/service-package	Package registry — publish, install, manage metadata packages
@objectstack/cloud-connection	Runtime-side client for an ObjectStack cloud control plane

Tools & apps

Package	Description
@objectstack/cli	The os / objectstack CLI
create-objectstack	Project scaffolder (npm create objectstack)
@objectstack/console	Prebuilt Console SPA pinned to this release; source lives in objectui
@objectstack/studio	Studio — the visual metadata builder app
@objectstack/setup	Setup — the platform administration app
@objectstack/account	Account — sign in, organizations, connected apps
@objectstack/docs	Documentation site (Fumadocs + Next.js)

Examples

Example	What it shows
examples/app-todo	The smallest app — objects, views, dashboards, flows
examples/app-crm	A minimal CRM exercising the full metadata pipeline: objects → views → app → dashboard → hooks → flows → seed
examples/app-showcase	Kitchen sink — every metadata type, view type, chart type, and capability chain; what pnpm dev runs
examples/app-multi-package	One release artifact carrying two packages that share a namespace
examples/embed-objectql	ObjectQL as a plain library — no kernel, no plugins
HotCRM	Full-featured enterprise CRM reference app (separate repo)

Community

• ⭐ Star this repo if ObjectStack is useful — it helps others find it.
• 🐛 Questions, bugs, or feature requests → open an issue.
• 🤝 Want to contribute? Start with CONTRIBUTING.md and ROADMAP.md.
• 📖 Full documentation at objectstack.ai/docs; upgrading between majors is covered in the upgrade guide.
• ☁️ Want it governed and hosted, with Build & Ask AI built in? ObjectOS is the commercial runtime for these definitions — objectstack-ai/objectos is its public home.

License

Apache-2.0. See LICENSE and LICENSING.md.