vercel · VaguelySerious · Nov 26, 2025 · Nov 26, 2025
diff --git a/.changeset/twenty-forks-grab.md b/.changeset/twenty-forks-grab.md
@@ -0,0 +1,11 @@
+---
+"@workflow/world-postgres": patch
+"@workflow/world-testing": patch
+"@workflow/world-local": patch
+"@workflow/core": patch
+"@workflow/next": patch
+"@workflow/cli": patch
+"@workflow/web": patch
+---
+
+Rename leftover references to "embedded world" to be "local world"
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
@@ -266,7 +266,7 @@
 ### Patch Changes
 
 - 66332f2: Rename vercel-static builder to standalone
-- dbf2207: Fix --backend flag not finding world when using embedded world package name explicitly
+- dbf2207: Fix --backend flag not finding world when using local world package name explicitly
 - Updated dependencies [dbf2207]
 - Updated dependencies [eadf588]
   - @workflow/[email protected]

diff --git a/packages/cli/src/lib/inspect/env.ts b/packages/cli/src/lib/inspect/env.ts
@@ -43,7 +43,7 @@ export const getEnvVars = (): Record<string, string> => {
     WORKFLOW_VERCEL_PROXY_URL: env.WORKFLOW_VERCEL_PROXY_URL || '',
     WORKFLOW_LOCAL_UI: env.WORKFLOW_LOCAL_UI || '',
     PORT: env.PORT || '',
-    WORKFLOW_EMBEDDED_DATA_DIR: env.WORKFLOW_EMBEDDED_DATA_DIR || '',
+    WORKFLOW_LOCAL_DATA_DIR: env.WORKFLOW_LOCAL_DATA_DIR || '',
   };
 };
 
@@ -75,10 +75,10 @@ async function findWorkflowDataDir(cwd: string) {
 }
 
 /**
- * Overwrites process.env variables related to embedded world configuration,
+ * Overwrites process.env variables related to local world configuration,
  * if relevant environment variables aren't set already.
  */
-export const inferEmbeddedWorldEnvVars = async () => {
+export const inferLocalWorldEnvVars = async () => {
   const envVars = getEnvVars();
   if (!envVars.PORT) {
     logger.warn(
@@ -89,12 +89,12 @@ export const inferEmbeddedWorldEnvVars = async () => {
   }
 
   // Paths to check, in order of preference
-  if (!envVars.WORKFLOW_EMBEDDED_DATA_DIR) {
+  if (!envVars.WORKFLOW_LOCAL_DATA_DIR) {
     const cwd = getWorkflowConfig().workingDir;
 
     const localPath = await findWorkflowDataDir(cwd);
     if (localPath) {
-      envVars.WORKFLOW_EMBEDDED_DATA_DIR = localPath;
+      envVars.WORKFLOW_LOCAL_DATA_DIR = localPath;
       writeEnvVars(envVars);
       return;
     }
@@ -104,7 +104,7 @@ export const inferEmbeddedWorldEnvVars = async () => {
     if (repoRoot) {
       const repoPath = await findWorkflowDataDir(repoRoot);
       if (repoPath) {
-        envVars.WORKFLOW_EMBEDDED_DATA_DIR = repoPath;
+        envVars.WORKFLOW_LOCAL_DATA_DIR = repoPath;
         writeEnvVars(envVars);
         return;
       }

diff --git a/packages/cli/src/lib/inspect/flags.ts b/packages/cli/src/lib/inspect/flags.ts
@@ -30,12 +30,12 @@ export const cliFlags = {
     description: 'backend to inspect',
     required: false,
     char: 'b',
-    default: 'embedded',
+    default: 'local',
     env: 'WORKFLOW_TARGET_WORLD',
     helpGroup: 'Target',
     helpLabel: '-b, --backend',
-    helpValue: ['embedded', 'vercel', '<your-package-name>'],
-    defaultHelp: 'embedded',
+    helpValue: ['local', 'vercel', '<your-package-name>'],
+    defaultHelp: 'local',
   }),
   authToken: Flags.string({
     description:

diff --git a/packages/cli/src/lib/inspect/setup.ts b/packages/cli/src/lib/inspect/setup.ts
@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import terminalLink from 'terminal-link';
 import { logger, setJsonMode, setVerboseMode } from '../config/log.js';
 import {
-  inferEmbeddedWorldEnvVars,
+  inferLocalWorldEnvVars,
   inferVercelEnvVars,
   writeEnvVars,
 } from './env.js';
@@ -52,10 +52,10 @@ export const setupCliWorld = async (
   ) {
     await inferVercelEnvVars();
   } else if (
-    flags.backend === 'embedded' ||
+    flags.backend === 'local' ||
     flags.backend === '@workflow/world-local'
   ) {
-    await inferEmbeddedWorldEnvVars();
+    await inferLocalWorldEnvVars();
   }
 
   logger.debug('Initializing world');

diff --git a/packages/cli/src/lib/inspect/web.ts b/packages/cli/src/lib/inspect/web.ts
@@ -369,7 +369,7 @@ function envToQueryParams(
     WORKFLOW_VERCEL_PROJECT: 'project',
     WORKFLOW_VERCEL_TEAM: 'team',
     PORT: 'port',
-    WORKFLOW_EMBEDDED_DATA_DIR: 'dataDir',
+    WORKFLOW_LOCAL_DATA_DIR: 'dataDir',
   };
 
   for (const [envName, paramName] of Object.entries(envToQueryParamMappings)) {

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -41,7 +41,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "clean": "tsc --build --clean && rm -r dist ||:",
-    "test": "cross-env WORKFLOW_TARGET_WORLD=embedded vitest run src",
+    "test": "cross-env WORKFLOW_TARGET_WORLD=local vitest run src",
     "test:e2e": "vitest run e2e",
     "typecheck": "tsc --noEmit"
   },

diff --git a/packages/core/src/runtime/world.ts b/packages/core/src/runtime/world.ts
@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import type { World } from '@workflow/world';
-import { createEmbeddedWorld } from '@workflow/world-local';
+import { createLocalWorld } from '@workflow/world-local';
 import { createVercelWorld } from '@workflow/world-vercel';
 
 const require = createRequire(join(process.cwd(), 'index.js'));
@@ -14,12 +14,12 @@ const globalSymbols: typeof globalThis & {
   [StubbedWorldCache]?: World;
 } = globalThis;
 
-function defaultWorld(): 'vercel' | 'embedded' {
+function defaultWorld(): 'vercel' | 'local' {
   if (process.env.VERCEL_DEPLOYMENT_ID) {
     return 'vercel';
   }
 
-  return 'embedded';
+  return 'local';
 }
 
 /**
@@ -42,9 +42,9 @@ export const createWorld = (): World => {
     });
   }
 
-  if (targetWorld === 'embedded') {
-    return createEmbeddedWorld({
-      dataDir: process.env.WORKFLOW_EMBEDDED_DATA_DIR,
+  if (targetWorld === 'local') {
+    return createLocalWorld({
+      dataDir: process.env.WORKFLOW_LOCAL_DATA_DIR,
     });
   }
 

diff --git a/packages/core/src/workflow.ts b/packages/core/src/workflow.ts
@@ -7,6 +7,7 @@ import * as nanoid from 'nanoid';
 import { monotonicFactory } from 'ulid';
 import { EventConsumerResult, EventsConsumer } from './events-consumer.js';
 import { ENOTSUP } from './global.js';
+import { parseWorkflowName } from './parse-name.js';
 import type { WorkflowOrchestratorContext } from './private.js';
 import {
   dehydrateWorkflowReturnValue,
@@ -28,7 +29,6 @@ import type { WorkflowMetadata } from './workflow/get-workflow-metadata.js';
 import { WORKFLOW_CONTEXT_SYMBOL } from './workflow/get-workflow-metadata.js';
 import { createCreateHook } from './workflow/hook.js';
 import { createSleep } from './workflow/sleep.js';
-import { parseWorkflowName } from './parse-name.js';
 
 export async function runWorkflow(
   workflowCode: string,
@@ -104,7 +104,7 @@ export async function runWorkflow(
       getWorkflowRunStreamId(workflowRun.runId, namespace);
 
     // TODO: there should be a getUrl method on the world interface itself. This
-    // solution only works for vercel + embedded worlds.
+    // solution only works for vercel + local worlds.
     const url = process.env.VERCEL_URL
       ? `https://${process.env.VERCEL_URL}`
       : `http://localhost:${port ?? 3000}`;

diff --git a/packages/next/src/index.ts b/packages/next/src/index.ts
@@ -13,7 +13,7 @@ export function withWorkflow(
     workflows,
   }: {
     workflows?: {
-      embedded?: {
+      local?: {
         port?: number;
         dataDir?: string;
       };
@@ -22,10 +22,10 @@ export function withWorkflow(
 ) {
   if (!process.env.VERCEL_DEPLOYMENT_ID) {
     if (!process.env.WORKFLOW_TARGET_WORLD) {
-      process.env.WORKFLOW_TARGET_WORLD = 'embedded';
-      process.env.WORKFLOW_EMBEDDED_DATA_DIR = '.next/workflow-data';
+      process.env.WORKFLOW_TARGET_WORLD = 'local';
+      process.env.WORKFLOW_LOCAL_DATA_DIR = '.next/workflow-data';
     }
-    const maybePort = workflows?.embedded?.port;
+    const maybePort = workflows?.local?.port;
     if (maybePort) {
       process.env.PORT = maybePort.toString();
     }

diff --git a/packages/web/src/components/display-utils/connection-status.tsx b/packages/web/src/components/display-utils/connection-status.tsx
@@ -25,22 +25,22 @@ const getConnectionInfo = (
     return { provider: 'Vercel', parts };
   }
 
-  if (backend === 'embedded') {
-    // Embedded backend
+  if (backend === 'local') {
+    // Local backend
     const parts: string[] = [];
     if (config.dataDir) {
       parts.push(`dir: ${config.dataDir}`);
     }
     if (config.port) parts.push(`port: ${config.port}`);
 
-    return { provider: 'Embedded', parts };
+    return { provider: 'Local', parts };
   }
 
   return { provider: config.backend || 'unknown', parts: [] };
 };
 
 export function ConnectionStatus({ config }: ConnectionStatusProps) {
-  const backend = config.backend || 'embedded';
+  const backend = config.backend || 'local';
   const { provider, parts } = getConnectionInfo(backend, config);
 
   return (

diff --git a/packages/web/src/components/settings-sidebar.tsx b/packages/web/src/components/settings-sidebar.tsx
@@ -30,8 +30,8 @@ export function SettingsSidebar() {
   const [errors, setErrors] = useState<ValidationError[]>([]);
   const [isValidating, setIsValidating] = useState(false);
 
-  const backend = localConfig.backend || 'embedded';
-  const isEmbedded = backend === 'embedded';
+  const backend = localConfig.backend || 'local';
+  const isLocal = backend === 'local';
 
   // Update local config when query params change
   useEffect(() => {
@@ -112,7 +112,7 @@ export function SettingsSidebar() {
                 <div className="space-y-2">
                   <Label htmlFor="backend">Backend</Label>
                   <Select
-                    value={localConfig.backend || 'embedded'}
+                    value={localConfig.backend || 'local'}
                     onValueChange={(value) =>
                       handleInputChange('backend', value)
                     }
@@ -121,13 +121,13 @@ export function SettingsSidebar() {
                       <SelectValue placeholder="Select backend" />
                     </SelectTrigger>
                     <SelectContent>
-                      <SelectItem value="embedded">Embedded</SelectItem>
+                      <SelectItem value="local">Local</SelectItem>
                       <SelectItem value="vercel">Vercel</SelectItem>
                     </SelectContent>
                   </Select>
                 </div>
 
-                {isEmbedded && (
+                {isLocal && (
                   <>
                     <div className="space-y-2">
                       <Label htmlFor="port">Port</Label>
@@ -175,7 +175,7 @@ export function SettingsSidebar() {
                   </>
                 )}
 
-                {!isEmbedded && (
+                {!isLocal && (
                   <>
                     <div className="space-y-2">
                       <Label htmlFor="env">Environment</Label>

diff --git a/packages/web/src/lib/config-world.ts b/packages/web/src/lib/config-world.ts
@@ -23,9 +23,9 @@ export async function validateWorldConfig(
   config: WorldConfig
 ): Promise<ValidationError[]> {
   const errors: ValidationError[] = [];
-  const backend = config.backend || 'embedded';
+  const backend = config.backend || 'local';
 
-  if (backend === 'embedded') {
+  if (backend === 'local') {
     // Check if data directory exists
     if (config.dataDir) {
       const resolvedPath = resolve(config.dataDir);

diff --git a/packages/web/src/lib/config.ts b/packages/web/src/lib/config.ts
@@ -7,7 +7,7 @@ import type { WorldConfig } from '@/lib/config-world';
 
 // Default configuration
 const DEFAULT_CONFIG: WorldConfig = {
-  backend: 'embedded',
+  backend: 'local',
   dataDir: './.next/workflow-data',
   port: '3000',
   env: 'production',
@@ -139,6 +139,6 @@ export const worldConfigToEnvMap = (config: WorldConfig): EnvMap => {
     WORKFLOW_VERCEL_PROJECT: config.project,
     WORKFLOW_VERCEL_TEAM: config.team,
     PORT: config.port,
-    WORKFLOW_EMBEDDED_DATA_DIR: config.dataDir,
+    WORKFLOW_LOCAL_DATA_DIR: config.dataDir,
   };
 };
diff --git a/packages/world-local/CHANGELOG.md b/packages/world-local/CHANGELOG.md
@@ -32,15 +32,15 @@
 
 ### Major Changes
 
-- aa015af: BREAKING: Change `createEmbeddedWorld` API signature from positional parameters to config object. Add baseUrl configuration support.
+- aa015af: BREAKING: Change `createLocalWorld` API signature from positional parameters to config object. Add baseUrl configuration support.
 
   **Breaking change:**
 
-  - `createEmbeddedWorld(dataDir?, port?)` → `createEmbeddedWorld(args?: Partial<Config>)`
+  - `createLocalWorld(dataDir?, port?)` → `createLocalWorld(args?: Partial<Config>)`
 
   **New features:**
 
-  - Add `baseUrl` config option for HTTPS and custom hostnames (via config or `WORKFLOW_EMBEDDED_BASE_URL` env var)
+  - Add `baseUrl` config option for HTTPS and custom hostnames (via config or `WORKFLOW_LOCAL_BASE_URL` env var)
   - Support for port 0 (OS-assigned port)
 
 ### Patch Changes

diff --git a/packages/world-local/src/config.ts b/packages/world-local/src/config.ts
@@ -2,13 +2,13 @@ import { getPort } from '@workflow/utils/get-port';
 import { once } from './util.js';
 
 const getDataDirFromEnv = () => {
-  return process.env.WORKFLOW_EMBEDDED_DATA_DIR || '.workflow-data';
+  return process.env.WORKFLOW_LOCAL_DATA_DIR || '.workflow-data';
 };
 
 export const DEFAULT_RESOLVE_DATA_OPTION = 'all';
 
 const getBaseUrlFromEnv = () => {
-  return process.env.WORKFLOW_EMBEDDED_BASE_URL;
+  return process.env.WORKFLOW_LOCAL_BASE_URL;
 };
 
 export type Config = {
@@ -26,7 +26,7 @@ export const config = once<Config>(() => {
 
 /**
  * Resolves the base URL for queue requests following the priority order:
- * 1. config.baseUrl (highest priority - full override from args or WORKFLOW_EMBEDDED_BASE_URL env var)
+ * 1. config.baseUrl (highest priority - full override from args or WORKFLOW_LOCAL_BASE_URL env var)
  * 2. config.port (explicit port override from args)
  * 3. PORT env var (explicit configuration)
  * 4. Auto-detected port via getPort (detect actual listening port)

diff --git a/packages/world-local/src/index.ts b/packages/world-local/src/index.ts
@@ -6,14 +6,14 @@ import { createStorage } from './storage.js';
 import { createStreamer } from './streamer.js';
 
 /**
- * Creates an embedded world instance that combines queue, storage, and streamer functionalities.
+ * Creates a local world instance that combines queue, storage, and streamer functionalities.
  *
  * @param args - Optional configuration object
  * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
  * @param args.port - Port override for queue transport (default: auto-detected)
  * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
  */
-export function createEmbeddedWorld(args?: Partial<Config>): World {
+export function createLocalWorld(args?: Partial<Config>): World {
   const definedArgs = args
     ? Object.fromEntries(
         Object.entries(args).filter(([, value]) => value !== undefined)