ObjectOS

The Business Operating System.

State. Identity. Synchronization. Orchestration. Admin Console.

Built on ObjectQL & ObjectStack.

---

Introduction

ObjectOS is the system layer of the ObjectStack ecosystem.

Layer	Repo	Responsibility
ObjectQL	objectql/objectql	Data — metadata, drivers, queries
ObjectUI	objectql/objectui	Views — amis-like control library
ObjectOS	this repo	State, Identity, Sync, Orchestration, Admin Console

ObjectOS acts as the "Kernel" that boots up, loads drivers (ObjectQL) and applications (Plugins), then governs every request through Authentication, Authorization, and Audit.

---

Key Features

• Identity & Auth — BetterAuth integration, SSO, 2FA, multi-tenant organization management
• RBAC Engine — Object/Field/Record-level security with permission sets
• Audit Logging — CRUD event capture, field-level history, IP/UA/session tracking
• Workflow Engine — State machines, BPMN-Lite approval processes
• Automation Triggers — WorkflowRule, 7 action types, formula engine, queue with retry
• Background Jobs — Multi-priority queues, cron scheduling, concurrency control
• Notifications — Email/SMS/Push/Webhook with Handlebars templates
• Realtime — WebSocket server, subscribe/unsubscribe, presence
• Cache — LRU + Redis, TTL, namespace isolation
• KV Storage — Memory/Redis/SQLite backends
• Metrics — Counter/Gauge/Histogram, Prometheus export
• i18n — Multi-locale, interpolation, pluralization
• Offline Sync — SQLite WASM, OPFS, Service Worker (browser package)

---

Tech Stack

Server (ObjectStack Kernel)

• Runtime: Node.js (LTS)
• Language: TypeScript 5.0+ (Strict)
• HTTP Server: Hono + @hono/node-server (via objectstack serve)
• Architecture: Modular Monolith / Micro-kernel
• APIs: REST /api/v1/* · GraphQL /api/v1/graphql · WebSocket

Admin Console (apps/web)

• Bundler: Vite 6
• Framework: React 19
• Routing: React Router 7
• Styling: Tailwind CSS 4 + shadcn/ui
• Auth Client: better-auth/react → /api/v1/auth

Documentation (apps/site)

• Framework: Next.js 16 + Fumadocs (MDX)
• Output: Static export

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   objectstack serve (:5320)                  │
│                                                              │
│  ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌─────────────┐  │
│  │  Hono    │ │ BetterAuth │ │ ObjectQL │ │  Plugins    │  │
│  │  Router  │ │ /api/v1/   │ │  Driver  │ │  (13 svcs)  │  │
│  └────┬─────┘ └──────┬─────┘ └────┬─────┘ └──────┬──────┘  │
│       └──────────────┴────────────┴──────────────┘          │
│                                                              │
│  Static Mounts:                                              │
│    /console/*  → apps/web/dist   (Vite SPA)                │
│    /docs/*     → apps/site/out   (Static HTML)              │
└─────────────────────────────────────────────────────────────┘

Three-Layer UI Architecture

ObjectUI (Controls)  →  apps/web (App Shell)  →  ObjectStack Hono (API)
     npm import              HTTP / WebSocket        Kernel + Plugins

• ObjectUI = Control Library (Form, Grid, Chart, Kanban — amis-like)
• apps/web = App Shell (routes, layout, auth, navigation)
• ObjectStack = API Server (data, auth, permissions, workflow)

---

Monorepo Structure

Kernel Packages

Package	Role
@objectos/auth	Identity — BetterAuth, SSO, 2FA, Sessions
@objectos/permissions	Authorization — RBAC, Permission Sets
@objectos/audit	Compliance — CRUD events, field history
@objectos/workflow	Flow — FSM engine, approval processes
@objectos/automation	Triggers — WorkflowRule, action types
@objectos/jobs	Background — queues, cron, retry
@objectos/notification	Outbound — Email/SMS/Push/Webhook
@objectos/realtime	Sync — WebSocket, presence
@objectos/cache	Performance — LRU + Redis
@objectos/storage	Persistence — KV (Memory/Redis/SQLite)
@objectos/metrics	Observability — Prometheus export
@objectos/i18n	Localization — multi-locale
@objectos/browser	Offline — SQLite WASM, OPFS

Application Packages

Package	Role	Stack
apps/web	Admin Console	Vite + React 19 + React Router 7
apps/site	Documentation	Next.js 16 + Fumadocs

---

Getting Started

Prerequisites

• Node.js 22+
• pnpm 9+
• PostgreSQL or MongoDB (optional — SQLite by default)

Installation

git clone https://github.com/objectstack-ai/objectos.git
cd objectos
pnpm install

Environment Setup

Before running the application, you need to configure environment variables. Copy the example file and update it with your settings:

cp .env.example .env

Required Configuration:

At minimum, you need to set the AUTH_SECRET for authentication to work:

# Generate a secure random secret (32+ characters recommended)
export AUTH_SECRET=$(openssl rand -base64 32)

Or add it to your .env file:

AUTH_SECRET=your-super-secret-key-change-this-in-production

Optional Configuration:

• Database: Defaults to SQLite (objectstack.db). Set OBJECTQL_DATABASE_URL for PostgreSQL or MongoDB.
• OAuth Providers: Configure GOOGLE_CLIENT_ID, GITHUB_CLIENT_ID, etc. for social login.
• Enterprise SSO: Set up Auth0, Okta, Keycloak, or Azure AD via environment variables.

See .env.example for all available options.

Development

# Start API server (:5320) + Admin Console (:5321) together
pnpm dev

# Start everything including docs site
pnpm dev:all

# Or use ObjectStack CLI directly
pnpm objectstack:serve    # API server only
pnpm objectstack:studio   # API + Console UI together

The Admin Console is available at http://localhost:5321/console/ with API proxy to ObjectStack at :5320.

All Commands

Development Commands

Command	Description
pnpm dev	API :5320 + Web :5321 (daily development)
pnpm dev:all	API + Web + Site (full stack)
pnpm start	Production — single process with static mounts
pnpm build	Build all packages (Turborepo)
pnpm test	Run all tests
pnpm lint	Lint all packages
pnpm type-check	TypeScript check all packages

ObjectStack CLI Commands

Command	Description
pnpm objectstack:serve	Start ObjectStack server (port 5320)
pnpm objectstack:dev	Start dev mode with hot-reload
pnpm objectstack:studio	Launch Console UI with dev server
pnpm objectstack:validate	Validate configuration against protocol
pnpm objectstack:compile	Compile configuration to JSON artifact
pnpm objectstack:info	Display metadata summary
pnpm objectstack:doctor	Check development environment health

Code Generation Commands

Command	Description
pnpm generate	Generate metadata files (interactive)
pnpm generate:object <name>	Generate a new object schema
pnpm generate:flow <name>	Generate a new workflow/flow
pnpm generate:view <name>	Generate a new view definition
pnpm generate:action <name>	Generate a new action
pnpm generate:agent <name>	Generate a new AI agent
pnpm generate:dashboard <name>	Generate a new dashboard
pnpm generate:app <name>	Generate a new application
pnpm create:plugin <name>	Create a new plugin from template
pnpm create:example <name>	Create a new example from template

App-Specific Commands

Command	Description
pnpm web:dev	Admin Console only (port 5321)
pnpm web:build	Build Admin Console
pnpm site:dev	Documentation site only
pnpm site:build	Build documentation

Production

# Build all packages and apps
pnpm build

# Start single-process server
# Serves API + /console (SPA) + /docs (static)
pnpm start

Deploy to Vercel

The project includes vercel.json and api/index.ts for Vercel deployment. Static assets are served from CDN; the API runs as a serverless function.

See Deployment Guide for full details.

---

Documentation

• Architecture Guide
• Deployment Guide
• Development Plan
• Contributing Guide

Spec & Guides (docs site)

• Platform Architecture
• Data Modeling
• Plugin Development
• Security Guide
• HTTP Protocol
• Metadata Format
• Query Language

---

License & Commercial Usage

ObjectOS is open-source software licensed under the GNU Affero General Public License v3.0 (AGPLv3).

• ✅ Free for internal use within your organization
• ✅ Free for open source AGPL-licensed projects
• ⚠️ Copyleft — SaaS usage requires open-sourcing under AGPL or purchasing a commercial license

Commercial License: Contact us

---

Part of the ObjectStack Ecosystem

ObjectQL (Data) · ObjectOS (System) · ObjectUI (View)