Getting Started

Overview

This is the shortest path to run Workflow Studio with an existing Workflow app.

Your app keeps the same workflow imports and start(...) call sites. Workflow Studio adds a remote worker and a deploy step.

In production, that worker runs as a separate Node service on your remote compute platform. Typical targets include Fly.io, Railway, Render, EC2, GCP, Sevalla, and Cloudflare Containers.

You do not change your app routes to call a new local server. You deploy the worker service separately, then point your app at it with WORKFLOW_COMPUTE_BASE_URL.

1. Install

npm install workflow-studio

2. Create `workflow.config.ts`

workflow.config.ts

import { createWorld } from '@workflow/world-postgres';
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 ?? '',
      }),
    auth: {
      seedApiKeys: [
        {
          keyId: 'wk_live_admin',
          secret: process.env.WORKFLOW_COMPUTE_API_KEY ?? '',
          projectId: 'proj_1',
          environment: 'prod',
          scopes: ['admin'],
        },
      ],
    },
  },
});

Required environment variables:

application: WORKFLOW_COMPUTE_BASE_URL, WORKFLOW_COMPUTE_API_KEY
worker: WORKFLOW_POSTGRES_URL, WORKFLOW_COMPUTE_API_KEY

3. Start the worker

Deploy a separate service for the worker on your compute platform, then use this as the service start command:

npx workflow-studio worker check-config
npx workflow-studio worker start

The worker process reads workflow.config.ts, starts an HTTP server, and exposes the operator and execution APIs used by Workflow Studio.

4. Build and deploy

Once the worker service is running, upload your workflow artifact to that worker:

npx workflow build
npx workflow-studio deploy \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"

5. Set production reroute on the application service

Set this on the application service, not the worker service:

WORKFLOW_TARGET_WORLD=workflow-studio/world-remote

6. Validate ownership

npx workflow-studio compute validate-ownership \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY" \
  --strict \
  --app-url "https://your-app.example.com"

7. Keep your existing `start(...)` route pattern

your-trigger-route.ts

import { start } from 'workflow/api';
import { validatePaymentMethod } from '@/workflows/validate-payment';

export async function POST(request: Request): Promise<Response> {
  const { rideId } = await request.json();
  await start(validatePaymentMethod, [rideId]);
  return Response.json({ started: true });
}

Next steps

Operator Guide for deploy, rollback, and ownership validation details
Deploy Worker for hosting and rollout guidance
API Keys and Scopes for narrower production keys
Observability for timelines and drilldowns
Framework Guides for Next.js, Nitro, and SvelteKit integration

On this page