Deploy Worker

Overview

This guide deploys the remote worker service used by Workflow Studio.

A typical production setup has:

an application service that receives user requests and calls start(...),
a remote worker service that executes workflow runs.

These are separate deployments. Your app does not embed the worker process. You deploy the worker as its own Node service and expose it over HTTP.

Hosting model

@workflow-studio/worker is a single Node HTTP service. It owns both:

the control plane: API keys, scopes, rate limiting, idempotency, audit, deployments, active pointer, operator APIs,
the execution plane: artifact verification, unpacking, active deployment loading, and callback dispatch for flow, step, and webhook handlers.

You can host it on Fly.io, Railway, Render, EC2, GCP, ECS, Sevalla, Cloudflare Containers, or any other Node-capable environment.

The worker deployment model is:

put your workflow.config.ts and app package on the worker service
start the worker with npx workflow-studio worker start
expose the worker over HTTPS
point the application at that worker with WORKFLOW_COMPUTE_BASE_URL

There is no required worker.ts file convention in Workflow Studio docs today. The standard path is a service that runs the CLI start command.

Railway deployment

Start command

npx workflow-studio worker start

Use the equivalent start command on any other platform as well. The platform changes, but the worker process is the same.

Health endpoint

GET /v1/health

Required worker environment variables

Variable	Description
`WORKFLOW_POSTGRES_URL`	World storage connection string when using Postgres world
`WORKFLOW_COMPUTE_API_KEY`	API key used in `worker.auth.seedApiKeys`
`PORT`	Worker listen port provided by platform

Recommended additional worker config:

worker.storage.sqlitePath for audit, idempotency, rate-limit, and deployment metadata.
worker.storage.artifactDir for unpacked deployment artifacts.
worker.security.requireHttps=true outside local development.

Artifact rollout procedure

Your workflow functions are compiled, packaged into a deployment archive, uploaded to the server over HTTP, and activated. Use the Operator Guide for the full operator flow:

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

See Operator Guide for lower-level compute build|deploy|activate commands, rollback, and API workflows.

Application-side production reroute

Set this environment variable on the application deployment:

WORKFLOW_TARGET_WORLD=workflow-studio/world-remote

Set worker connectivity variables on the application as well:

WORKFLOW_COMPUTE_BASE_URL
WORKFLOW_COMPUTE_API_KEY

Health checks and diagnostics

Use these checks during rollout and incident response:

GET /v1/health verifies the worker process is reachable.
GET /v1/deployments/active verifies the active deployment pointer.
npx workflow-studio compute validate-ownership --strict ... verifies worker reachability, active deployment state, and app-side reroute diagnostics.
App-side remote ownership diagnostics confirm WORKFLOW_TARGET_WORLD=workflow-studio/world-remote and detect unexpected local callback hits.

Expected outcome

After activation and reroute configuration:

application routes can keep the existing start(...) pattern,
workflow execution traffic is processed by the remote worker,
worker health and ownership validation checks pass.

Failure handling runbook

Symptom	Likely cause	Action
`401 unauthorized`	Missing or invalid API key	Verify the bearer key and compare it with the worker's seeded keys.
`403 missing_scope`	Key lacks required scope	Grant the missing scope or use an `admin` key. See API Keys and Scopes.
`409 no_active_deployment`	Deployment exists but nothing is active	Activate a deployment with `workflow-studio rollback --deployment-id <id> ...` or `POST /v1/deployments/:id/activate`.
`409 idempotency_required`	Trigger request omitted `Idempotency-Key`	Retry `POST /v1/runs` with a stable idempotency key.
`409 idempotency_conflict`	Reused key with different trigger payload	Reuse the original payload or send a new idempotency key.
`429 rate_limited`	Per-key rate limit exceeded	Retry after the limit window or provision a separate operator key.
`400 invalid_manifest`	Artifact metadata and manifest do not match	Rebuild and redeploy so manifest file metadata matches the uploaded tarball.
`404 not_found` or `400 invalid_deployment_id`	Wrong deployment ID	Read `/v1/deployments/active` or `GET /v1/deployments/:id` and retry with a valid ID.
`403 https_required`	Non-local HTTP request blocked by HTTPS policy	Use HTTPS in production or disable the requirement only in trusted local development.

Troubleshooting

Symptom	Likely cause	Action
`no_active_deployment`	Active deployment pointer not set	Run `workflow-studio rollback --deployment-id <id> ...` or activate via the API
Strict remote guard startup failure	`WORKFLOW_TARGET_WORLD` missing or mismatched	Set `WORKFLOW_TARGET_WORLD=workflow-studio/world-remote`
Ownership status `fail`	Queue callback traffic reaches app-host routes	Route queue callbacks to worker and run validation again
`401` or `403` from worker	API key missing, invalid, or missing a scope	Verify key and required scopes

Post-deploy validation

Run ownership validation to confirm remote routing:

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"

On this page