workflow-studio

Overview

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

It provides:

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

Shared protocol, client, and config types live in @workflow-studio/core. The deployable runtime lives in @workflow-studio/worker.

Config API

defineWorkflowStudioConfig(config)

Defines typed configuration loaded from workflow.config.*.

import { defineWorkflowStudioConfig } from 'workflow-studio';
import { createWorld } from '@workflow/world-postgres';

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 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 and 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 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. World operations are proxied through the worker's restricted /v1/world/* routes.

Mode behavior

• execution.mode='local' - local or 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.

CLI command groups

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

See Operator Guide for full reference.