feat(cloud): rename ProjectStack to RuntimeStack and update configurations for cloud-connected runtime mode

Author: hotlong

CHANGELOG.md

@@ -8,7 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- **ObjectOS Cloud Runtime mode (default)** — `apps/server` (and any host using `createBootStack`) now boots `project` mode through ObjectStack Cloud (`https://cloud.objectstack.ai` by default) instead of an embedded control-plane DB. The cloud URL is configurable via `OBJECTSTACK_CLOUD_URL` (or `project.cloudUrl` in `objectstack.config.ts`); auth via `OBJECTSTACK_CLOUD_API_KEY` / `project.cloudApiKey`. To opt out and run against a local `control.db` (legacy single-machine dev), set `OBJECTSTACK_CLOUD_URL=local`. New building blocks in `@objectstack/service-cloud`: `ArtifactApiClient` (TTL-cached HTTP client for `GET /api/v1/cloud/resolve-hostname` and `GET /api/v1/cloud/projects/:id/artifact`), `ArtifactEnvironmentRegistry` (replaces `DefaultEnvironmentDriverRegistry` — resolves hostnames over HTTP, falls back to the artifact's default datasource when no runtime block is supplied), and `ArtifactKernelFactory` (boots a kernel directly from `artifact.metadata` with `DriverPlugin + ObjectQLPlugin + MetadataPlugin + AppPlugin`, no `ControlPlaneProxyDriver`). Closes the "Artifact API loader + local cache durability" item under §7 Missing in the North Star.
+- **`OBJECTSTACK_MODE=runtime` (renamed from `project`)** — The cloud-connected runtime node mode is now called **`runtime`**, better describing its role as a kernel runtime that pulls metadata from a control plane (instead of hosting its own). The previous mode name `project` is preserved as a deprecated alias (warns at boot). The `BootStackConfig.runtime` config field replaces `BootStackConfig.project`; the old field name is still accepted with a deprecation. **The default `OBJECTSTACK_MODE` also changes from `project` to `standalone`** — the safer, zero-config baseline (runtime-only ObjectQL + REST + Driver). Hosts that want the runtime node behavior must now opt in explicitly with `OBJECTSTACK_MODE=runtime`.
+- **`OBJECTSTACK_CLOUD_URL` defaults to local `apps/cloud` (`http://localhost:4000`)** — The runtime mode's default control-plane URL is now the local `apps/cloud` instance, not the hosted `https://cloud.objectstack.ai`. `apps/cloud`'s `dev` / `start` scripts now bind to port 4000 by default (override via `PORT`). Dev workflow: start `apps/cloud` first, then start `apps/server` in runtime mode against it. For the hosted control plane, set `OBJECTSTACK_CLOUD_URL=https://cloud.objectstack.ai`. To disable cloud routing entirely and boot from a local `control.db`, set `OBJECTSTACK_CLOUD_URL=local`.
+- **ObjectOS Cloud Runtime building blocks (`@objectstack/service-cloud`)** — `ArtifactApiClient` (TTL-cached HTTP client for `GET /api/v1/cloud/resolve-hostname` and `GET /api/v1/cloud/projects/:id/artifact`), `ArtifactEnvironmentRegistry` (replaces `DefaultEnvironmentDriverRegistry` — resolves hostnames over HTTP, falls back to the artifact's default datasource when no runtime block is supplied), and `ArtifactKernelFactory` (boots a kernel directly from `artifact.metadata` with `DriverPlugin + ObjectQLPlugin + MetadataPlugin + AppPlugin`, no `ControlPlaneProxyDriver`). Auth via `OBJECTSTACK_CLOUD_API_KEY` / `runtime.cloudApiKey`. Closes the "Artifact API loader + local cache durability" item under §7 Missing in the North Star.
 
 ### Changed
 - **`OBJECTSTACK_MODE` redefined into three values** — Boot-mode selection now accepts `project` (default), `cloud`, and `standalone`. The previous semantics — where `standalone` meant "single-project local dev with full Auth + Studio" — moved under `project`. The new `standalone` value is **runtime-only**: ObjectQL + REST + Driver, no Auth, no control plane, no Studio data. Designed for embedding ObjectStack in other frameworks. Aliases `local` / `single-project` continue to map to `project`; `multi-project` continues to map to `cloud`. Default also changed: an unset `OBJECTSTACK_MODE` now resolves to `project` (was: `standalone`).

apps/cloud/package.json

@@ -5,9 +5,9 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "objectstack dev",
+    "dev": "PORT=${PORT:-4000} objectstack dev",
     "build": "tsup",
-    "start": "objectstack serve dist/objectstack.config.js --prebuilt",
+    "start": "PORT=${PORT:-4000} objectstack serve dist/objectstack.config.js --prebuilt",
     "doctor": "objectstack doctor",
     "typecheck": "tsc --noEmit",
     "test": "objectstack test",

apps/server/objectstack.config.ts

@@ -1,27 +1,37 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * ObjectStack Server — Host Configuration (local)
+ * ObjectStack Server — Host Configuration (runtime node)
  *
  * Booted by `objectstack dev` / `objectstack serve` (see `package.json`).
  *
  * ## Boot modes
  *
- * Selected via the `OBJECTSTACK_MODE` environment variable:
+ * Selected via the `OBJECTSTACK_MODE` environment variable. Default:
+ * `standalone`.
  *
- *   - `project`   (default) — local single-project deployment. Reuses the
- *                            cloud (multi-project) plugin stack but backs
- *                            it with two SQLite files (`control.db` for
- *                            the control plane, `proj_local.db` for the
- *                            single project's business data).
- *                            Aliases: `local`, `single-project`.
- *   - `standalone`         — runtime-only (ObjectQL + REST + Driver).
+ *   - `standalone` (default) — Runtime-only (ObjectQL + REST + Driver).
+ *                              Single artifact, no control plane, no
+ *                              auth. Best for embedding ObjectStack into
+ *                              another framework or running headless.
+ *   - `runtime`              — Cloud-connected runtime node. Resolves
+ *                              projects by hostname against ObjectStack
+ *                              Cloud (`apps/cloud` on
+ *                              `http://localhost:4000` by default — start
+ *                              that service first) and boots per-project
+ *                              kernels from artifacts pulled over HTTP.
+ *                              Override the cloud URL via
+ *                              `OBJECTSTACK_CLOUD_URL`. Set it to
+ *                              `local` for the legacy two-SQLite shape
+ *                              (`control.db` + `proj_local.db`).
+ *                              Aliases: `project`, `local`,
+ *                              `single-project` (deprecated).
  *
- * The `cloud` (multi-project, hosted) mode lives in `apps/cloud`.
+ * The `cloud` (multi-project control plane) mode lives in `apps/cloud`.
  *
- * All boot orchestration now lives in @objectstack/service-cloud.
- * This file only supplies the apps/server-specific knobs (filesystem
- * app bundle resolution).
+ * All boot orchestration lives in `@objectstack/service-cloud`. This
+ * file only supplies the apps/server-specific knobs (filesystem app
+ * bundle resolution).
  */
 
 import { resolve as resolvePath, dirname } from 'node:path';
@@ -35,13 +45,14 @@ const localArtifactPath = process.env.OBJECTSTACK_ARTIFACT_PATH
     ?? resolvePath(serverDir, 'dist/objectstack.json');
 
 const config = await createBootStack({
-    project: {
+    runtime: {
         dataDir,
         artifactPath: localArtifactPath,
         appBundles: createFsAppBundleResolver(),
-        // ObjectStack Cloud runtime is the default; set
-        // `OBJECTSTACK_CLOUD_URL=local` to fall back to a local control
-        // DB for offline / single-machine development.
+        // Default: connect to the local apps/cloud (port 4000). Override
+        // with `OBJECTSTACK_CLOUD_URL=https://cloud.objectstack.ai` for
+        // the hosted control plane, or `OBJECTSTACK_CLOUD_URL=local` to
+        // fall back to a single-machine `control.db` shape.
         cloudUrl: process.env.OBJECTSTACK_CLOUD_URL,
         cloudApiKey: process.env.OBJECTSTACK_CLOUD_API_KEY,
     },

packages/cli/src/commands/serve.ts

@@ -175,17 +175,17 @@ export default class Serve extends Command {
         throw new Error(`No default export found in ${args.config}`);
       }
 
-      // Project mode is the canonical OS dev workflow. Every bare
+      // Standalone is the default OS dev workflow. Every bare
       // `defineStack()` is booted via `@objectstack/service-cloud`'s
-      // `createBootStack()` (project / cloud / standalone are selected
-      // by `OBJECTSTACK_MODE`, default `project`). Set
+      // `createBootStack()` (runtime / cloud / standalone selected by
+      // `OBJECTSTACK_MODE`, default `standalone`). Set
       // `OBJECTSTACK_MODE=off` to fall back to the legacy lightweight
       // assembler.
       if (shouldBootWithLibrary(config)) {
         const { createBootStack } = await import('@objectstack/service-cloud');
         const bootResult = await createBootStack({
           mode: config.bootMode,
-          project: config.project,
+          runtime: config.runtime ?? config.project,
           cloud: config.cloud,
           standalone: config.standalone,
         });

packages/cli/src/utils/plugin-detection.ts

@@ -34,9 +34,11 @@ export function isHostConfig(config: any): boolean {
  * `@objectstack/service-cloud/boot-env`.
  */
 const RECOGNISED_MODES = new Set([
-  'project',
+  'runtime',
   'cloud',
   'standalone',
+  // Deprecated aliases (kept for back-compat — emit a console warning at boot).
+  'project',
   'local',
   'single-project',
   'multi-project',
@@ -47,7 +49,7 @@ export function shouldBootWithLibrary(config: any): boolean {
   const mode = process.env.OBJECTSTACK_MODE?.trim().toLowerCase();
   if (mode === 'off' || mode === 'none' || mode === 'legacy') return false;
   if (mode && !RECOGNISED_MODES.has(mode)) {
-    console.warn(`[objectstack] Unknown OBJECTSTACK_MODE=${mode}; falling back to project mode.`);
+    console.warn(`[objectstack] Unknown OBJECTSTACK_MODE=${mode}; falling back to standalone mode.`);
   }
   if (config?.bootMode === 'off') return false;
   return true;

packages/services/service-cloud/src/boot-stack.ts

@@ -13,7 +13,7 @@
 import { z } from 'zod';
 import { resolveMode, resolveAuthSecret, resolveBaseUrl } from './boot-env.js';
 import type { BootMode } from './boot-env.js';
-import { createProjectStack, ProjectStackConfigSchema } from './project-stack.js';
+import { createRuntimeStack, RuntimeStackConfigSchema } from './runtime-stack.js';
 import { createStandaloneStack, StandaloneStackConfigSchema } from './standalone-stack.js';
 import { createCloudStack } from './cloud-stack.js';
 import type { CloudStackConfig } from './cloud-stack.js';
@@ -35,9 +35,14 @@ const CloudStackConfigSchema = z.object({
 
 export const BootStackConfigSchema = z.object({
     /** Explicit mode override. When unset, resolves from env. */
-    mode: z.enum(['project', 'cloud', 'standalone']).optional(),
-    /** Project-mode options (used when mode resolves to `project`). */
-    project: ProjectStackConfigSchema.optional(),
+    mode: z.enum(['runtime', 'cloud', 'standalone', 'project']).optional(),
+    /** Runtime-mode options (used when mode resolves to `runtime`). */
+    runtime: RuntimeStackConfigSchema.optional(),
+    /**
+     * @deprecated Use `runtime`. Kept for back-compat with hosts that
+     * already pass `project: { … }` to `createBootStack()`.
+     */
+    project: RuntimeStackConfigSchema.optional(),
     /** Cloud-mode options (used when mode resolves to `cloud`). */
     cloud: CloudStackConfigSchema.optional(),
     /** Standalone-mode options (used when mode resolves to `standalone`). */
@@ -57,11 +62,18 @@ export interface BootStackResult {
  * Selection precedence:
  *   1. `config.mode` (explicit override)
  *   2. `OBJECTSTACK_MODE` environment variable
- *   3. Default: `'project'`
+ *   3. Default: `'standalone'`
+ *
+ * Note: `'project'` is accepted as a deprecated alias for `'runtime'`
+ * (renamed v4.x to better describe the mode's role: a runtime node
+ * connected to ObjectStack Cloud).
  */
 export async function createBootStack(config?: BootStackConfig): Promise<BootStackResult> {
     const cfg = BootStackConfigSchema.parse(config ?? {});
-    const mode: BootMode = cfg.mode ?? resolveMode();
+    const explicitMode: BootMode | undefined = cfg.mode
+        ? (cfg.mode === 'project' ? 'runtime' : cfg.mode as BootMode)
+        : undefined;
+    const mode: BootMode = explicitMode ?? resolveMode();
 
     if (mode === 'cloud') {
         const cloudCfg = cfg.cloud ?? {};
@@ -84,5 +96,6 @@ export async function createBootStack(config?: BootStackConfig): Promise<BootSta
         return createStandaloneStack(cfg.standalone);
     }
 
-    return createProjectStack(cfg.project);
+    // runtime (also reached via deprecated `mode: 'project'`)
+    return createRuntimeStack(cfg.runtime ?? cfg.project);
 }

packages/services/service-cloud/src/index.ts

@@ -67,8 +67,13 @@ export {
 } from './boot-env.js';
 export type { BootMode, BootEnv } from './boot-env.js';
 
-export { createProjectStack, ProjectStackConfigSchema, DEFAULT_CLOUD_URL } from './project-stack.js';
-export type { ProjectStackConfig, ProjectStackResult } from './project-stack.js';
+export { createRuntimeStack, RuntimeStackConfigSchema, DEFAULT_CLOUD_URL } from './runtime-stack.js';
+export type { RuntimeStackConfig, RuntimeStackResult } from './runtime-stack.js';
+
+/** @deprecated Use `createRuntimeStack`. */
+export { createProjectStack, ProjectStackConfigSchema } from './runtime-stack.js';
+/** @deprecated Use `RuntimeStackConfig`/`RuntimeStackResult`. */
+export type { ProjectStackConfig, ProjectStackResult } from './runtime-stack.js';
 
 export { createStandaloneStack, StandaloneStackConfigSchema } from './standalone-stack.js';
 export type { StandaloneStackConfig, StandaloneStackResult } from './standalone-stack.js';

packages/services/service-cloud/src/objectos-stack.ts

@@ -9,7 +9,7 @@
  * dispatcher can resolve hostnames and route every request to the
  * matching project kernel built from a remote-fetched artifact.
  *
- * Invoked by `createProjectStack()` whenever `OBJECTSTACK_CONTROL_PLANE_URL`
+ * Invoked by `createRuntimeStack()` whenever `OBJECTSTACK_CLOUD_URL`
  * (or `config.controlPlaneUrl`) is set. The same plugin shape is returned
  * as `createCloudStack()` so host configs can swap stacks transparently.
  */

packages/services/service-cloud/src/runtime-stack.ts

@@ -4,9 +4,12 @@
  * Runtime-mode stack factory.
  *
  * Default behavior — boots a "runtime node" connected to ObjectStack
- * Cloud (`https://cloud.objectstack.ai`). The node fetches per-project
- * artifacts over HTTP and routes incoming requests to the matching
- * project kernel; no local control-plane database is provisioned.
+ * Cloud at `http://localhost:4000` (the local `apps/cloud` instance —
+ * start it before the runtime). For the hosted control plane, set
+ * `OBJECTSTACK_CLOUD_URL=https://cloud.objectstack.ai`. The node
+ * fetches per-project artifacts over HTTP and routes incoming requests
+ * to the matching project kernel; no local control-plane database is
+ * provisioned.
  *
  * Local opt-out — set `OBJECTSTACK_CLOUD_URL=local` (or
  * `cloudUrl: 'local'`) to fall back to the legacy single-control-plane
@@ -33,12 +36,18 @@ import type { AppBundleResolver } from './project-kernel-factory.js';
 import { createObjectOSStack } from './objectos-stack.js';
 
 /**
- * Default ObjectStack Cloud base URL used when neither `cloudUrl` nor
- * `OBJECTSTACK_CLOUD_URL` is set. Override via the env var or
- * `RuntimeStackConfig.cloudUrl`. Set to `local` to disable cloud routing
- * and boot from a local `control.db` instead.
+ * Default ObjectStack Cloud base URL — the local `apps/cloud` instance
+ * running on port 4000. Override via `OBJECTSTACK_CLOUD_URL` (or
+ * `RuntimeStackConfig.cloudUrl`) to point at a remote control plane
+ * (e.g. `https://cloud.objectstack.ai`). Set to `local` to disable
+ * cloud routing entirely and boot from a local `control.db` instead.
+ *
+ * Why a local default? Runtime nodes are designed to be paired with a
+ * control plane. Defaulting to `localhost:4000` lets contributors run
+ * `apps/cloud` (the open-source control plane) and `apps/server` (the
+ * runtime) side-by-side with zero env config — the natural dev loop.
  */
-export const DEFAULT_CLOUD_URL = 'https://cloud.objectstack.ai';
+export const DEFAULT_CLOUD_URL = 'http://localhost:4000';
 
 export const RuntimeStackConfigSchema = z.object({
     /** Auth secret (defaults to env / dev fallback). Local-mode only. */
@@ -56,8 +65,9 @@ export const RuntimeStackConfigSchema = z.object({
     /** API prefix (passed through to the cloud preset). */
     apiPrefix: z.string().optional(),
     /**
-     * ObjectStack Cloud base URL. Defaults to `https://cloud.objectstack.ai`
-     * (override via the `OBJECTSTACK_CLOUD_URL` env var or this field).
+     * ObjectStack Cloud base URL. Defaults to `http://localhost:4000`
+     * (the local `apps/cloud` dev instance). For the hosted control
+     * plane, set `OBJECTSTACK_CLOUD_URL=https://cloud.objectstack.ai`.
      *
      * When non-empty (the default), the runtime stack runs as a
      * **cloud-connected runtime node**: no local control-plane database,