Quickstart

This page boots the open-source ObjectStack runtime on your own machine — the stack ObjectOS is built on. ObjectOS itself needs none of it: ObjectOS Cloud is hosted in the browser with nothing to install (sign in at www.objectos.ai), and ObjectOS Enterprise is the same runtime environment self-managed on your infrastructure, deployed from the licensed image described under Deployment. What you build here is ordinary ObjectStack metadata, so it runs on either.

There are two ways to start the open runtime, 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: 31 loaded

  Press Ctrl+C to stop

That's it. You're running the open-source ObjectStack runtime — the stack ObjectOS is built on, not ObjectOS itself. See License & Pricing for what the ObjectOS editions add on top of it.

That block is transcribed from @objectstack/cli 17.5.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, boot diagnostics) and the full list of loaded plugin names, both of which depend on your environment. It also logs a SQL-driver warning, Paged read of 'sys_migration' is NOT deterministic, and a DATABASE_ERROR for a missing sys_migration table, neither of which stops the server.

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

The in-product AI Builder is ObjectOS's: it ships in ObjectOS Cloud and ObjectOS Enterprise, not in the open runtime you just started, whose AI path is the MCP endpoint printed in the banner (http://localhost:3000/api/v1/mcp — point Claude Code or any MCP client at it). On ObjectOS, 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 ObjectStack metadata — the ontology ObjectOS runs — 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 (175ms)

  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.9 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
      platform admin — Setup, Studio and every record, but NO app-declared capability, so
      an app that gates navigation on requiredPermissions may show it an empty menu; grant
      it a permission set under Setup → Users, or sign in as an account your app seeds

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

  Press Ctrl+C to stop

That block is transcribed from pnpm dev on a scaffold created by @objectstack/cli 17.5.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), the full list of loaded plugin names, boot diagnostics, and an MCP connection trailer. A separate process prints that trailer, so it usually lands inside the banner, often interleaved line by line with it. The run also logs a SQL-driver warning, Paged read of 'sys_migration' is NOT deterministic, and a DATABASE_ERROR for a missing sys_migration table, neither of which stops the server.

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('sys_user', { label: 'Assignee' }),
  },
});

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 the runtime, the open ObjectStack image or an ObjectOS Enterprise deployment, 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, Package management, the Setup and Account apps, and the Console UI.

Path B also loads the automation service plus the record-change, schedule, time-relative and inbound HTTP/webhook flow triggers, because the scaffold's objectstack.config.ts declares requires: ['automation', 'triggers'].

You don't import or wire any of them — the list above loads even when nothing declares it, and the rest activate when something declares it needs them.

Next steps