workflow-studio

Overview

workflow-studio is the user-facing package for remote compute configuration and tooling.

It provides:

• config helpers (defineWorkflowStudioConfig, defineWorkflowConfig),
• framework adapter helpers,
• proxy-trigger helper functions,
• ownership diagnostics handler,
• worker and compute deployment CLI commands.

Config API

defineWorkflowStudioConfig(config)

Defines typed configuration loaded from workflow.config.*.

import { defineWorkflowStudioConfig } from 'workflow-studio';

export default defineWorkflowStudioConfig({
  execution: {
    mode: 'remote',
    remoteWorkerUrl: process.env.WORKFLOW_COMPUTE_BASE_URL,
    apiKeyEnv: 'WORKFLOW_COMPUTE_API_KEY',
    failPolicy: 'error',
  },
  worker: {
    world: ({ env }) => createWorld({ connectionString: env.WORKFLOW_POSTGRES_URL! }),
    server: { host: '0.0.0.0', port: 3001 },
    security: { requireHttps: true },
    auth: { seedApiKeys: [/* ... */] },
    storage: { sqlitePath: './data/worker.db' },
  },
});

execution config fields

Controls how workflow-studio routes execution traffic.

worker config fields

Configures the remote compute worker process.

worker.server

worker.security

worker.auth

worker.storage

Worker world forms

worker.world accepts:

• a function returning a complete World, or
• a composed object with base and optional queue/streams factories.

See World Composition for details.

Framework adapters

Next.js

• withWorkflowStudioNext(nextConfig, options) — see Next.js guide
• proxyTriggerFromNext(request, options)
• proxyWebhookFromNext(request, options)

Nitro

• withWorkflowStudioNitro(nitroConfig, options) — see Nitro guide
• proxyTriggerFromNitro(request, options)
• proxyWebhookFromNitro(request, options)

SvelteKit

• withWorkflowStudioSvelteKit(config, options) — see SvelteKit guide
• proxyTriggerFromSvelteKit(request, options)
• proxyWebhookFromSvelteKit(request, options)

Execution and routing behavior

world-remote reroute

When WORKFLOW_TARGET_WORLD=workflow-studio/world-remote is set on the application service, existing start(...) calls are intercepted and routed to the remote compute worker. No application code changes are required.

The remote adapter creates a ComputeClient using execution.remoteWorkerUrl and the API key from the env var named by execution.apiKeyEnv. All world operations (queue publish, event creation, stream writes) are proxied through the worker's /v1/world/* routes.

Mode behavior

• execution.mode='local' — local/default execution. Workflow runs execute in-process.
• execution.mode='remote' — remote execution when worker settings and deployment env are configured.

Ownership diagnostics

Handler

createRemoteOwnershipDiagnosticsHandler() returns a route handler for:

• GET /api/workflow-studio/diagnostics/remote-ownership

Authentication

Method restriction: GET only. Returns 405 for other methods.

Response shape

{
  "remoteModeEnabled": true,
  "strictMode": true,
  "targetWorld": "workflow-studio/world-remote",
  "expectedTargetWorld": "workflow-studio/world-remote",
  "status": "pass",
  "lifetimeUnexpectedHits": 0,
  "unexpectedHitsLast15m": 0,
  "lastUnexpectedHitAt": null,
  "lastEvent": null,
  "hardChecks": {},
  "softChecks": {},
  "generatedAt": "2025-01-15T12:00:00.000Z",
  "correlationId": "abc-123-def"
}

Response fields

See Security Model — Ownership detection for how unexpected hits are classified.

CLI command groups

• workflow-studio worker ...
  • check-config
  • start
• workflow-studio compute ...
  • build
  • deploy
  • activate
  • rollback
  • validate-ownership

See CLI Commands for full reference.