---
title: Single-Environment Mode
description: 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`, and `pnpm dev:todo`
- `os dev`, `os start`, and `os serve` in a local app
- `createStandaloneStack()` / `createDefaultHostConfig()` in
  `@objectstack/runtime`

Use [Deployment Modes](./cloud-deployment) when you need to publish to an
ObjectStack 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

```bash
# 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
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:

```bash
PORT=3000 pnpm dev
# showcase example, persistent state, console at /_console

pnpm dev:crm -- --fresh -p 38421
# minimal CRM example with an ephemeral tempdir
```

From a generated app:

```bash
os dev
os start
os serve --artifact ./dist/objectstack.json
```

The 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:

```typescript
import { createDefaultHostConfig, createStandaloneStack } from '@objectstack/runtime';

const stack = createStandaloneStack({
  environmentId: 'env_local',
  artifactPath: './dist/objectstack.json',
});

const host = 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.

---

## Related

- [Environment-Scoped Routing](./project-scoping)
- [Deployment Modes](./cloud-deployment)
- [CLI reference](../getting-started/cli)
