---
title: Deployment Modes
description: Choose between local standalone runtime and Cloud-managed environment deployment.
---

# Deployment Modes

This repository ships the framework runtime, examples, adapters, CLI, docs, and
the published console bundle. Local development is a single-environment runtime.
Cloud deployment uses a separate ObjectStack Cloud control plane plus the
environment-aware runtime seams exported from `@objectstack/runtime`.

| Mode | Runs from this repo | Environment selection | Typical use |
|:---|:---:|:---|:---|
| Local example | Yes | One active `OS_ENVIRONMENT_ID` | Framework development and smoke tests |
| Standalone app | Yes | One compiled artifact or stack config | Self-hosted app backend |
| Cloud-managed environment | Runtime seams only | Cloud control plane, hostname, scoped URL, header, or session | SaaS and multi-environment deployments |

---

## Local runtime

Use the repo scripts for framework development:

```bash
PORT=3000 pnpm dev
pnpm dev:crm -- --fresh -p 38421
pnpm docs:dev
```

`pnpm dev` starts the showcase kitchen-sink example. It is the best local
exercise path for objects, views, flows, AI metadata, security, and the console
bundle.

For a generated app:

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

The active environment is selected with `OS_ENVIRONMENT_ID`.

---

## Standalone artifact runtime

Any directory with a compiled `dist/objectstack.json` can boot through the CLI
or `@objectstack/runtime` helpers:

```bash
os compile
OS_ENVIRONMENT_ID=env_prod os serve --artifact ./dist/objectstack.json
```

Deployment config stays outside the artifact. Database URLs, auth secrets,
runtime credentials, and environment identity are injected through process env
or the host's deployment config.

---

## Cloud-managed deployment

Publishing and installing are **separate steps**. The CLI publishes a
**versioned package** to your organization's catalog — it does not touch any
environment, and you never pass an environment id:

```bash
os cloud login        # once: stores a cloud token
os package publish     # → sys_package + immutable, checksummed sys_package_version
```

See the cloud [package](/docs/references/cloud/package) and
[package-version](/docs/references/cloud/package-version) references.

Installing then happens **inside the target environment**: sign in to that
environment's Console → **Marketplace** → pick the package → **Install**. The
install is authorized by your environment login and applied to that environment
(metadata + sample data); the kernel is evicted so it is live on the next
request — no restart, and no environment id to remember.

> **CI shortcut.** A pipeline deploying to a *known* environment can publish and
> install in one call: `os package publish --env <id> --install`. This is for
> automation only — interactive installs happen in the environment Marketplace.

> **Legacy env-revision path.** `os publish` posts compiled metadata straight to
> an environment as a revision, rather than as a versioned package:
>
> ```bash
> OS_CLOUD_URL=https://cloud.example.com OS_ENVIRONMENT_ID=env_prod os publish
> # POST /api/v1/cloud/environments/:environment/metadata
> # rollback: POST /api/v1/cloud/environments/:environment/revisions/:commit/activate
> ```
>
> It still works, but the package flow above is the direction of travel
> (ADR-0006 v4): `sys_environment_revision` is retired once all publishes go
> through the package endpoints.

Cloud control-plane hosts, database provisioning, billing, and public SaaS
deployment are outside this framework repository. The framework runtime exposes
the environment registry, marketplace proxy, and runtime-config seams consumed
by that distribution.

---

## Routing precedence

Environment-aware hosts resolve requests in this order:

1. `/api/v1/environments/:environmentId/...`
2. Hostname through the environment registry
3. `X-Environment-Id`
4. `session.activeEnvironmentId`
5. Configured default environment
6. Single unambiguous environment

Control-plane paths under `/api/v1/cloud/environments/...` are not data-plane
requests and do not run through a target environment kernel.

---

## Environment variables

| Variable | Purpose |
|:---|:---|
| `OS_ENVIRONMENT_ID` | Active local or publish target environment. |
| `OS_CLOUD_URL` | Cloud control-plane base URL used by publish/package commands. |
| `OS_ARTIFACT_PATH` | Artifact path for `os serve` and standalone hosts. |
| `OS_DATABASE_URL` | Local runtime business database URL. |
| `OS_DATABASE_DRIVER` | Local runtime driver id. |
| `AUTH_SECRET` | Better Auth session secret for hosted runtimes. |
| `PORT` / `HOST` | HTTP bind settings. |

Third-party provider variables such as `OPENAI_API_KEY`, `TURSO_*`,
`SMTP_*`, `RESEND_API_KEY`, and OAuth client secrets keep their provider names.

---

## Related

- [Single-Environment Mode](./single-project-mode)
- [Environment-Scoped Routing](./project-scoping)
- [Publish, Versioning & Preview](./publish-and-preview)
