Your first project — from zero to running

This is the hands-on path for developers building on ObjectStack from the published npm packages — you never clone the framework repository. In about ten minutes you will scaffold a project, run it, add a field by hand, call the generated REST API, and compile the artifact you would deploy.

Prerequisites

That's all. A standalone project does not need pnpm, TypeScript pre-installed, or a database server — the default template runs on an in-memory driver, and TypeScript comes in as a dev dependency.

1. Scaffold

npm create objectstack@latest my-app
cd my-app

The scaffolder (create-objectstack) does four things:

1. Copies a template into my-app/ and rewrites its identity — the npm package name, the manifest name/displayName, and a namespace derived from your project name (my-app → my_app). Every object in the template is renamed to carry that prefix (my_app_note), which is what os validate later enforces.
2. Installs dependencies (pnpm if available, otherwise npm).
3. Installs the AI skills bundle for one coding agent from the @objectstack/skills package, at your installed @objectstack/spec's version — copied once into .claude/skills/, to commit with the project — so a coding agent is productive in the project from the first prompt. The closing summary prints the command for any other runtime you use (Installing skills has the steps, the versions the package is published at, and the one scaffolder version that is an exception).
4. Writes AGENTS.md (and .github/copilot-instructions.md) with the project conventions — including the rule to run npm run validate after every metadata change.

Steps 3–4 cost nothing if you never use an agent; skip step 3 (the skills bundle) with --skip-skills if you prefer — AGENTS.md is always written.

Templates

npm create objectstack@latest my-app -- --template blank

blank is bundled inside the npm package, so scaffolding always works offline.

The remote content templates (todo, compliance, content, contracts, procurement) have been retired: they were delisted from the ObjectStack template marketplace and are no longer maintained. Asking for one by name says so explicitly.

2. What was generated

my-app/
├── objectstack.config.ts        # defineStack() — the single entry point
├── objectstack.manifest.json    # name, namespace, specVersion
├── package.json
├── tsconfig.json
├── note.test.ts                 # the starter test `npm test` runs
├── vitest.config.ts             # its test-runner config
├── AGENTS.md                    # conventions for coding agents
└── src/
    ├── objects/
    │   ├── index.ts             # barrel — re-exports every object
    │   └── note.object.ts       # a sample object
    ├── views/index.ts           # an empty barrel for each directory
    ├── actions/index.ts         # `os generate` writes into, already
    ├── flows/index.ts           # wired into objectstack.config.ts
    ├── dashboards/index.ts
    ├── apps/index.ts
    └── skills/index.ts

Two files matter most:

objectstack.config.ts wires everything together. There is no filename-suffix magic — metadata exists in the app only if it is imported here. Every directory os generate writes into is already imported, so a generated view, action or flow adds a file and one export line to its directory's index.ts and is part of the stack with no edit to this file:

import { defineStack } from '@objectstack/spec';
import { ConnectorRestPlugin } from '@objectstack/connector-rest';
import { ConnectorOpenApiPlugin } from '@objectstack/connector-openapi';
import { ConnectorMcpPlugin } from '@objectstack/connector-mcp';
import * as objects from './src/objects';
import * as views from './src/views';
import * as actions from './src/actions';
import * as flows from './src/flows';
import * as dashboards from './src/dashboards';
import * as apps from './src/apps';
import * as skills from './src/skills';

// Object.values, typed by what the barrel exports, so an empty barrel still
// type-checks.
const exportsOf = <M extends object>(barrel: M): M[keyof M][] => Object.values(barrel);

export default defineStack({
  manifest: {
    id: 'com.example.my-app',
    namespace: 'my_app',
    version: '0.1.0',
    type: 'app',
    name: 'My App',
    // Protocol major this app is authored against (ADR-0087 load-time check).
    engines: { protocol: '^18' },
  },
  // `automation` runs flows and, per ADR-0097, materializes declarative
  // `connectors:` entries at boot. The three generic executors below register
  // their `rest` / `openapi` / `mcp` provider factories with it. `triggers`
  // fires a flow that starts on a record change, the kind `os generate flow`
  // writes.
  requires: ['automation', 'triggers'],
  plugins: [
    new ConnectorRestPlugin(),
    new ConnectorOpenApiPlugin(),
    new ConnectorMcpPlugin(),
  ],
  objects: exportsOf(objects),
  views: exportsOf(views),
  actions: exportsOf(actions),
  flows: exportsOf(flows),
  dashboards: exportsOf(dashboards),
  apps: exportsOf(apps),
  skills: exportsOf(skills),
});

export default defineStack({ /* … */ });

// ⛔ Read as a top-level stack key called `collectPackageDirs`.
//    `os build` refuses it: Unrecognized key(s) on this stack definition.
export const collectPackageDirs = () => [ /* … */ ];

The REST API needs no configuration — it is on by default for every object with apiEnabled. The plugins: array ships the three generic connector executors, so you can integrate an external REST / OpenAPI / MCP service as pure metadata: add a connectors: entry naming a provider and the automation capability materializes it into a live connector at boot — see Automation → Flows.

src/objects/note.object.ts is a complete data model — schema, validation, API surface, and searchability in one typed definition:

import { ObjectSchema, Field } from '@objectstack/spec/data';

export const Note = ObjectSchema.create({
  name: 'my_app_note',          // namespace-prefixed, snake_case
  label: 'Note',
  pluralLabel: 'Notes',
  icon: 'sticky-note',

  fields: {
    title: Field.text({ label: 'Title', required: true, searchable: true, maxLength: 200 }),
    body: Field.textarea({ label: 'Body' }),
  },

  sharingModel: 'private',      // org-wide default — an explicit, authored decision
  enable: { apiEnabled: true, searchable: true },
});

The packages you depend on

A standalone project uses a handful of published packages — this is the entire framework surface you install:

No driver package is listed because none is installed directly: @objectstack/runtime depends on driver-sql, driver-sqlite-wasm and driver-memory, and the CLI carries them too. objectstack dev resolves SQLite by default; point OS_DATABASE_URL at Postgres / MySQL / MongoDB for production — no code changes.

3. Run it

npm run dev            # objectstack dev — rebuild + server restart on change

Or with the visual Console (data browser, metadata explorer, API docs):

npx os dev --ui        # then open http://localhost:3000/_console/

4. Call your API

The REST API is derived from the object metadata — you wrote no routes. Data endpoints run under the same permission model as the UI, so first sign in as the dev admin the server seeds on an empty database (admin@objectos.ai / admin123):

# Sign in once — stores the session cookie
curl -c cookies.txt -X POST http://localhost:3000/api/v1/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@objectos.ai", "password": "admin123"}'

# Create a record
curl -b cookies.txt -X POST http://localhost:3000/api/v1/data/my_app_note \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello ObjectStack", "body": "Created via the generated API"}'

# Query records (filtering, sorting, pagination built in)
curl -b cookies.txt "http://localhost:3000/api/v1/data/my_app_note?select=title&sort=-created_at&top=10"

See the Data API for the full CRUD, batch, and analytics surface, and the Client SDK for the typed TypeScript client (@objectstack/client).

5. Extend the model

Add a field and a second object by hand — the same edit an agent would make.

  fields: {
    title: Field.text({ label: 'Title', required: true, searchable: true, maxLength: 200 }),
    body: Field.textarea({ label: 'Body' }),
    status: Field.select({
      label: 'Status',
      options: [
        { label: 'Draft', value: 'draft', default: true },
        { label: 'Published', value: 'published' },
      ],
    }),
  },

New objects follow the same pattern: create src/objects/<name>.object.ts with a name of <namespace>_<short_name>, then re-export it from src/objects/index.ts (the barrel is what the config imports).

After every metadata change, run the gate:

npm run validate

os validate checks schema compliance, CEL predicate scoping, and widget bindings — the classes of mistakes that otherwise fail silently at runtime. See Validating Metadata.

Beyond pass/fail, npx os lint --score grades the data model 0–100 against the platform's design conventions (relationship patterns, missing select options, roll-ups, name fields) — a quick health check as the model grows.

6. Build the deployable artifact

npm run build          # objectstack build → dist/objectstack.json

The artifact is a portable, self-describing deployment unit: one JSON file containing your entire app. Any server with @objectstack/cli can boot it — no TypeScript, no build step on the host:

npx os start --artifact ./dist/objectstack.json --port 8080

Database URL, auth secret, and environment identity stay outside the artifact and are injected at boot via flags or OS_* environment variables — which is exactly what makes it container-friendly.

7. Hand the project to your agent

You just did by hand what an agent does in seconds — and the scaffolder already prepared the project for that handoff: the skills bundle is installed (step 1.3) and AGENTS.md routes each task to the right skill and enforces the validate gate. Open the project in Claude Code (or Cursor / Copilot) and describe the next feature instead of typing it:

Add a status filter to the note list view, a dashboard with a metric of published notes, and a daily flow that archives notes older than 90 days. Run npm run validate when done.

Each of those lands in a different metadata domain (UI, dashboards, automation) — the agent loads the matching skill per task. The full loop, and a per-domain prompt catalog, is on Build with Claude Code. The catalog's version is your installed @objectstack/spec's (step 1.3): when you upgrade, bump @objectstack/skills with the other @objectstack/* packages, then re-run npx skills@1.7.2 experimental_sync --agent claude-code --copy -y and commit what it changed, to keep the agent in sync with the schemas you run. Name your own runtime after --agent if it is not Claude Code.

Next steps