Run ObjectOS Community locally

ObjectOS Community is the open-source edition of ObjectOS: the runtime and its UI, built on the Apache-2.0 ObjectStack framework, free to run anywhere. This page boots it on your own machine with one CLI and one command. Nothing here needs an account, a license or Docker.

The other two ways in are their own pages: Start on ObjectOS Cloud if you want it hosted with nothing to install, and Start on ObjectOS Enterprise for the licensed edition on your own infrastructure. What you build here is ordinary ObjectStack metadata, so it runs on every edition.

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: 32 loaded

  Press Ctrl+C to stop

That's it. You're running ObjectOS Community, the open-source runtime. See Compare Editions for what ObjectOS Cloud and ObjectOS Enterprise add on top of it.

That block is transcribed from @objectstack/cli 17.7.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.

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 (312ms)

  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 (2.2 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

  Artifact: dist/objectstack.json
  Mode:    development
  Driver:  SqlDriver(better-sqlite3)  → my-app/.objectstack/data/objectstack.db
  Tenancy: single
  Plugins: 38 loaded

  Press Ctrl+C to stop

That block is transcribed from pnpm dev on a scaffold created by @objectstack/cli 17.7.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.

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

Every object you add carries your project's namespace. os init derived it from the project name (my-app → my_app) and wrote it into objectstack.config.ts as manifest.namespace, so a task object is my_app_task. The compile refuses a bare task with Rename it to 'my_app_task' (namespace = 'my_app'), and states the rule: Every object.name must be `${manifest.namespace}_${shortName}`.

Create src/objects/task.object.ts:

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

const task = ObjectSchema.create({
  name: 'my_app_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' }),
  },
  // Org-wide default: who sees records they don't own. Required — the
  // compile refuses an object that declares none.
  sharingModel: 'private',
});

export default task;

Then export it from src/objects/index.ts. objectstack.config.ts loads each directory through that index.ts barrel, so a file the barrel does not export is never loaded. Add this line below the sample object's: export { default as task } from './task.object';

npx objectstack generate object task writes a stub of the file and the same barrel line for you.

Save. The dev server recompiles, prints ✚ new object(s): my_app_task — table & seeds sync on restart, and restarts itself on the new build: no migration to write, no restart to run. If it prints only ✗ compile failed, run pnpm build to see why. You now have:

• /api/v1/data/my_app_task — create, read, update and delete, with filter, sort and pagination (REST API). It answers signed-in callers only, so sign in as the dev admin first (below).
• A generated list, form and record page — the scaffold declares no app yet, so nothing in the Console links to them; open http://localhost:3000/_console/apps/setup/my_app_task.
• A Task row in the permission-set editor — Setup → Permission Sets, open a set, Design in Studio: create, read, edit and delete for that set.
• Audit log entries — each create, update and delete, listed under Setup → Audit Logs.

curl -c cookies.txt -H 'Content-Type: application/json' \
  -d '{"email":"admin@objectos.ai","password":"admin123"}' \
  http://localhost:3000/api/v1/auth/sign-in/email
curl -b cookies.txt -H 'Content-Type: application/json' \
  -d '{"subject":"Try the API"}' \
  http://localhost:3000/api/v1/data/my_app_task
curl -b cookies.txt http://localhost:3000/api/v1/data/my_app_task

Project layout

my-app/
├── objectstack.config.ts    # defineStack(): manifest + one key per barrel
├── src/                     # one index.ts barrel per directory
│   ├── actions/
│   ├── apps/
│   ├── dashboards/
│   ├── flows/
│   ├── objects/             # index.ts + my_app_item.object.ts, the sample object
│   ├── picklists/
│   ├── skills/
│   └── views/
├── dist/
│   └── objectstack.json     # Compiled artifact (regenerated on save)
├── .objectstack/            # Local SQLite databases (pnpm dev creates them)
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.json

os init also writes a .gitignore and your installer's lockfile.

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, Migration recovery, 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']. It also opens a dedicated telemetry datasource, a second SQLite file beside the database, because pnpm dev runs in development mode.

You don't import or wire any of them — the list above loads even when nothing declares it, the automation service and flow triggers activate when something declares it needs them, and development mode adds the telemetry datasource.

Next steps