Deploy Worker

Overview

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

A typical production setup has:

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

Railway deployment

Start command

npx workflow-studio worker start

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

Artifact rollout procedure

Your workflow functions are compiled, packaged into a deployment archive, uploaded to the server over HTTP, and activated. Build, deploy, and activate using the CLI Commands reference:

npx workflow build
npx workflow-studio compute build
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. See CLI Commands for full flag reference, exit codes, and rollback.

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

Expected outcome

After activation and reroute configuration:

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

Troubleshooting

Symptom	Likely cause	Action
`no_active_deployment`	Active deployment pointer not set	Run `compute activate --deployment-id <id>`
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 compute routes	Route queue callbacks to worker and run validation again
`401`/`403` from worker	API key missing/invalid or scope mismatch	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