Getting Started

Overview

This guide configures remote execution for an existing Workflow application.

The setup uses:

one application service that calls start(...),
one remote compute worker that executes workflow runs.

1. Install

npm install workflow-studio

2. Configure `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!,
      }),
    server: {
      host: '0.0.0.0',
      port: Number(process.env.PORT ?? 3001),
    },
    auth: {
      seedApiKeys: [
        {
          keyId: 'wk_live_worker',
          secret: process.env.WORKFLOW_COMPUTE_API_KEY!,
          projectId: 'proj_1',
          environment: 'prod',
          scopes: [
            'trigger:write',
            'runs:read',
            'runs:write',
            'deploy:read',
            'deploy:write',
            'world:proxy',
          ],
        },
      ],
    },
  },
});

3. Start the remote compute worker

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

Expected result:

worker process starts,
GET /v1/health returns healthy: true.

4. Build and deploy a deployment artifact

Build the workflow bundles and deployment artifact:

npx workflow build
npx workflow-studio compute build

compute build prints the generated deployment ID and manifest path to stdout. Use these values in the deploy and activate commands.

Deploy and activate (see CLI Commands for full flag reference):

npx workflow-studio compute deploy \
  --artifact .workflow-studio/dist/artifact.tgz \
  --manifest .workflow-studio/tmp/<deploymentId>/manifest.json \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"
npx workflow-studio compute activate \
  --deployment-id <deploymentId> \
  --url "$WORKFLOW_COMPUTE_BASE_URL" \
  --api-key "$WORKFLOW_COMPUTE_API_KEY"

Replace <deploymentId> with the value printed by compute build.

5. Set production reroute on the application service

WORKFLOW_TARGET_WORLD=workflow-studio/world-remote

This variable is required for production reroute of unchanged start(...) paths.

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

Validate ownership and diagnostics — strict validation, CI usage, troubleshooting
CLI Commands — full command reference and rollout sequence
Framework Guides — Next.js, Nitro, and SvelteKit integration

A Node.js HTTP server started by workflow-studio worker start. It loads your deployed workflow code from artifact bundles and executes them when triggered. You deploy this server to any host that runs Node.js (Railway, Fly.io, EC2, etc). Your web app sends requests to it over HTTP.

How do my workflow functions get to the server?

workflow build compiles your workflow functions into JavaScript bundles. workflow-studio compute build packages them into a deployment archive. workflow-studio compute deploy uploads the archive over HTTP to the server. workflow-studio compute activate tells the server to use that deployment for new runs.

Your function source code is uploaded once per deployment, not sent with every request.

Variable	Description	Required
`WORKFLOW_COMPUTE_BASE_URL`	Remote compute worker base URL	Yes
`WORKFLOW_COMPUTE_API_KEY`	API key for worker authentication	Yes
`WORKFLOW_TARGET_WORLD`	Production reroute target (`workflow-studio/world-remote`)	Yes

Worker service

Variable	Description	Required
`WORKFLOW_POSTGRES_URL`	World storage connection string when using Postgres world	Yes (for Postgres world)
`PORT`	Worker listen port	No

Safety and diagnostics

Variable	Description	Required
`WORKFLOW_STUDIO_DIAGNOSTICS_TOKEN`	Diagnostics endpoint bearer token in production	Required in production if diagnostics route is enabled