Quickstart

There are two ways to start, depending on what you're doing.

Both produce a running server with the UI — account sign-in, registration and self-service are routes inside that UI, not a separate surface. The difference is whether you scaffold source files.

Prerequisites

• Node.js 22 or newer — node --version
• A terminal

That's it. No Docker. No database. No account signup.

Path A — os start (operator / first-time evaluator)

Install the CLI globally, then run it:

npm i -g @objectstack/cli
os start

You'll see:

◆ ObjectStack
────────────────────────────────────────
🏠 Home: ~/.objectstack
📦 Artifact: none (empty kernel — install apps via the Console marketplace)
🗄️ Database: file:~/.objectstack/data/objectstack.db
🎯 Environment: env_local
  → Starting server...

  ✓ Server is ready

  ➜  API:       http://localhost:3000/
  ➜  Console:   http://localhost:3000/_console/
  ➜  MCP:       http://localhost:3000/api/v1/mcp
      connect an AI client (Claude Code, Cursor, …) · skill: http://localhost:3000/api/v1/mcp/skill

  Mode:    production
  Driver:  SqlDriver(better-sqlite3)  → ~/.objectstack/data/objectstack.db
  Tenancy: single
  Plugins: 30 loaded

  Press Ctrl+C to stop

That's it. You're running ObjectOS.

That block is transcribed from @objectstack/cli 17.3.0 booting an empty kernel. Home paths show as ~/… — the CLI prints yours expanded. Your own boot also prints a No objectstack.config.ts or artifact found line before the server starts, plus startup advisories (local storage driver, dev crypto key, schema-sync notes from the SQL driver, boot diagnostics) and the full list of loaded plugin names, both of which depend on your environment.

What's running

The runtime boots into an empty kernel — no objects, no apps — and exposes the marketplace so you can install ready-made apps in seconds.

Both probes answer 200 here, and locally there is nothing to wire them to — but they are not interchangeable, and it is worth knowing which is which before you deploy. Liveness reports only that the process is executing, so it stays green straight through a database outage; readiness answers 503 as soon as a data driver stops answering. Docker and Kubernetes show which probe goes where.

Build by chat — the AI Builder

Once you're signed in, open the AI assistant (top-right sparkle icon) and describe what you need:

"I need to track customer support tickets. Each has a subject, description, priority (low/medium/high/urgent), status, and assignee. Add a kanban view grouped by status."

The AI proposes a plan, you approve, and the metadata is live — REST endpoints, generated views, audit log entries, permission gates. No file edited, no restart. See Build → AI Builder for the full vocabulary.

Hand-coding in your IDE? Run npx skills add objectstack-ai/objectstack/skills to teach Claude Code / Cursor / Copilot / Codex how to author ObjectOS metadata against the real Zod schemas. See Build → IDE Skills.

Install an app from the marketplace

Open http://localhost:3000/_console/, sign in, and pick an app:

Install → reload → it's there, with its objects, views, permissions, and seed data. No restart required.

Common flags

os start --port 3200                       # different port
os start --database postgres://...         # external database
os start --auth-secret "$(openssl rand -hex 32)"  # enable auth in /api/v1/auth/*
os start --home /var/lib/objectos          # persistent home (production)

See Runtime Configuration for every option, and Docker for the production-shaped path.

Path B — os init (developer)

Use this when you're writing TypeScript to define your own data model, views, and flows.

npx @objectstack/cli init my-app -t app --install
cd my-app
pnpm dev

You'll see:

◆ Development Mode
────────────────────────────────────────
📂 Config: my-app/objectstack.config.ts
  → Compiling objectstack.config.ts → dist/objectstack.json...

◆ Compile
────────────────────────────────────────
  ✓ Build complete (143ms)

  Data: 1 Objects  3 Fields
  UI: 0 Apps
  Logic: 0 Flows
  Security: 0 Positions  0 Permissions
  Runtime: 0 plugins

  Artifact: my-app/dist/objectstack.json (1.8 KB)

  → Starting dev server (local mode)...
🎯 Environment ID: env_local
📦 Artifact: dist/objectstack.json
🗄️ Database: file:my-app/.objectstack/data/objectstack.db
  👁  watching objectstack.config.ts, src — rebuild + restart on change

  ✓ Server is ready

  ➜  API:       http://localhost:3000/
  ➜  Console:   http://localhost:3000/_console/
  ➜  MCP:       http://localhost:3000/api/v1/mcp
      connect an AI client (Claude Code, Cursor, …) · skill: http://localhost:3000/api/v1/mcp/skill

  🔑  Dev admin: admin@objectos.ai / admin123
      seeded on empty DB · dev only — do not use in production

  Config:  objectstack.config.ts
  Mode:    development
  Driver:  SqlDriver(better-sqlite3)  → my-app/.objectstack/data/objectstack.db
  Tenancy: single
  Plugins: 30 loaded

  Press Ctrl+C to stop

That block is transcribed from pnpm dev on a scaffold created by @objectstack/cli 17.3.0. Project paths show as my-app/… — the CLI prints yours expanded, and the Build complete timing is whatever the transcribing machine measured, so yours will differ. Your own run also prints pnpm's script header above the block, per-step compile progress, startup advisories (configuration load, dev secret-field crypto, schema-sync notes from the SQL driver), the full list of loaded plugin names, boot diagnostics, and an MCP connection trailer above the banner.

Note the dev server asks for port 3000, the same port os start uses. If that port is taken it binds the next free one and says so: ↪ server bound to port 3001 (requested 3000).

Add your own object

Edit src/objects/task.ts:

// src/objects/task.ts
import { ObjectSchema, Field } from '@objectstack/spec/data';

export const Task = ObjectSchema.create({
  name: 'task',
  label: 'Task',
  fields: {
    subject:   Field.text({ label: 'Subject', required: true, maxLength: 200 }),
    done:      Field.boolean({ label: 'Done', defaultValue: false }),
    due:       Field.date({ label: 'Due' }),
    assignee:  Field.lookup({ label: 'Assignee', reference: 'sys_user' }),
  },
});

Save. The dev server recompiles and you immediately have:

• /api/v1/data/task — full CRUD with filter/sort/paginate
• A "Task" view — list, form, detail, all generated
• Permission rows in Setup — grant read/write per role
• Audit log entries — every create/update/delete recorded

No migrations. No code generation. No restarting.

Project layout

my-app/
├── objectstack.config.ts    # Stack definition (manifest + objects)
├── src/
│   └── objects/             # Your data model — add files here
├── dist/
│   └── objectstack.json     # Compiled artifact (regenerated on save)
├── package.json
└── tsconfig.json

dist/objectstack.json is what you ship to production — mount it on a running ObjectOS container and that becomes your app.

Or start from a template

Production-shaped starters live in github.com/objectstack-ai/templates:

git clone https://github.com/objectstack-ai/templates.git
cd templates/packages/todo
pnpm install
pnpm dev    # http://localhost:4002

Each template is < 2500 LOC, readable in one sitting, runs standalone.

What's loaded out of the box

Either path gives you these plugins automatically:

HTTP server, REST API, Dispatcher, MCP server, Auth, Security (RBAC + RLS + FLS), Audit, Sharing, Platform objects, Metadata, ObjectQL, the default datasource plus the external-datasource and datasource-admin services, Queue, Jobs, Cache, Settings, Email, SMS, Messaging, Storage, Analytics, external validation, Marketplace, the Setup and Account apps, and the Console UI.

You don't import or wire any of them — they activate when something declares it needs them.

Next steps