Quickstart

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

Both produce a running server with Console + Account. The difference is whether you scaffold source files.

Prerequisites

• Node.js 20 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 Console marketplace)
🗄️ Database: file:~/.objectstack/data/objectstack.db

  ✓ Server is ready

  ➜  API:       http://localhost:3000/
  ➜  Console:    http://localhost:3000/_console/
  ➜  Account:   http://localhost:3000/_account/
  ➜  Console:   http://localhost:3000/_console/

  Plugins: 23 loaded

That's it. You're running ObjectOS.

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.

Build by chat — the AI Builder

Once you're signed in, open the AI assistant in Console (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, Console 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/framework 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:

✓ Project initialized!

◆ Compile
  ✓ Build complete (462ms)
  Data: 1 Objects  3 Fields

◆ Development Mode
  ✓ Server is ready

  ➜  API:       http://localhost:3002/
  ➜  Console:    http://localhost:3002/_console/
  ➜  Account:   http://localhost:3002/_account/
  ➜  Console:   http://localhost:3002/_console/

Note the dev server uses port 3002 to avoid colliding with a running os start on 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 in Console — list, form, detail, all generated
• Permission rows in Console — 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 23 plugins automatically:

Auth, Security (RBAC + RLS + FLS), Audit, REST API, Console UI, Account UI, Console UI, AI Service, Queue, Jobs, Cache, Settings, Email, Storage, Marketplace, Metadata, ObjectQL, plus the SQL driver.

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

Next steps