ObjectStackSingle-Environment Mode
Run ObjectStack as a one-environment local stack without a Cloud control plane.
Single-Environment Mode
Single-environment mode is the default boot shape for this repository's framework runtime and examples. One process owns one active environment, loads the configured metadata, and serves REST plus the published console bundle. There is no organization picker, hostname router, or Cloud control-plane hop.
This is the mode used by:
pnpm dev,pnpm dev:showcase,pnpm dev:crm, andpnpm dev:todoos dev,os start, andos servein a local appcreateStandaloneStack()/createDefaultHostConfig()in@objectstack/runtime
Use Deployment Modes when you need to publish to an ObjectOS Cloud control plane or test environment-scoped routing.
How it differs from Cloud mode
| Concern | Single environment | Cloud-aware host |
|---|---|---|
| Active id | OS_ENVIRONMENT_ID or the runtime default | Resolved per request |
| Routing | Direct /api/v1/... routes | Optional /api/v1/environments/:environmentId/..., hostname, header, or session |
| Console | Served from packages/console / bundled ObjectUI | Same console can target a resolved environment |
| Metadata source | Local stack config or compiled artifact | Published package/environment artifact and deployment config |
| Control plane | Not part of this repo's default dev server | Lives in the Cloud distribution |
Environment variables
# Active environment identity
OS_ENVIRONMENT_ID=env_local
# Business database
OS_DATABASE_URL=file:./.objectstack/data/app.db
OS_DATABASE_DRIVER=sqlite
# Compiled artifact for `os serve` / standalone hosts
OS_ARTIFACT_PATH=./dist/objectstack.json
# Auth, required outside dev
OS_AUTH_SECRET=<random 32-byte secret>ObjectStack-owned variables use the OS_ prefix. The old project-scoped names
are not aliases in current docs or examples.
Local commands
From the framework repo:
OS_PORT=3000 pnpm dev
# showcase example, persistent state, console at /_console
pnpm dev:crm -- --fresh -p 38421
# minimal CRM example with an ephemeral tempdirFrom a generated app:
os dev
os start
OS_ARTIFACT_PATH=./dist/objectstack.json os serveThe CLI forwards the active environment through OS_ENVIRONMENT_ID and, when
needed, the X-Environment-Id request header.
Standalone runtime APIs
@objectstack/runtime exposes the standalone helpers used by the CLI:
import { createDefaultHostConfig, createStandaloneStack } from '@objectstack/runtime';
const stack = await createStandaloneStack({
environmentId: 'env_local',
artifactPath: './dist/objectstack.json',
});
const host = await createDefaultHostConfig({
environmentId: 'env_local',
artifactPath: './dist/objectstack.json',
});These helpers are for one active environment. They do not create Cloud environments, provision databases, or mount a control plane.