Validation and Ownership

Overview

The validate-ownership command checks that your deployment is correctly configured for remote execution. It verifies the worker is reachable, an active deployment exists, and the app runtime is properly configured.

Basic Check

pnpm exec workflow-studio compute validate-ownership \
  --url https://worker.example.com \
  --app-url https://app.example.com

This checks:

• Worker health endpoint is reachable
• Active deployment exists on the worker
• App URL is reachable (optional)

Strict Mode

Use --strict for production validation that hard-fails on ownership issues:

pnpm exec workflow-studio compute validate-ownership \
  --url https://worker.example.com \
  --app-url https://app.example.com \
  --strict

Strict mode additionally checks:

• App runtime WORKFLOW_TARGET_WORLD matches expected target
• Diagnostics endpoint confirms ownership status is pass

Exit Codes

With Diagnostics Token (Production)

In production, the diagnostics endpoint requires authentication:

pnpm exec workflow-studio compute validate-ownership \
  --url https://worker.example.com \
  --app-url https://app.example.com \
  --strict \
  --diagnostics-token "$WORKFLOW_STUDIO_DIAGNOSTICS_TOKEN"

Set WORKFLOW_STUDIO_DIAGNOSTICS_TOKEN in your deployment environment to enable diagnostics access.

What Gets Checked

Worker Checks (Always)

• Health endpoint: GET /v1/health responds with healthy: true
• Active deployment: GET /v1/deployments/active returns a deployment ID

App Runtime Checks (Strict Mode)

• Diagnostics endpoint: GET /api/workflow-studio/diagnostics/remote-ownership responds
• Target world match: App's WORKFLOW_TARGET_WORLD matches workflow-studio/world-remote
• Ownership status: Diagnostics reports status: "pass" (no unexpected app-host traffic)

Expected Errors

If no active deployment is set:

[FAIL] active_deployment: No active deployment found on worker.

Run workflow-studio compute activate to set an active deployment.

CI/CD Integration

Add validation to your deployment pipeline:

## .github/workflows/deploy.yml
- name: Validate Ownership
  run: |
    pnpm exec workflow-studio compute validate-ownership \
      --url "$WORKFLOW_COMPUTE_BASE_URL" \
      --app-url "$APP_URL" \
      --strict
  env:
    WORKFLOW_COMPUTE_BASE_URL: ${{ secrets.WORKFLOW_COMPUTE_BASE_URL }}
    APP_URL: ${{ vars.APP_URL }}

Debugging Failures

"Diagnostics endpoint unavailable"

The app diagnostics endpoint is not reachable. Check:

• App is deployed and running
• Route handler is registered at /api/workflow-studio/diagnostics/remote-ownership
• No middleware blocking the route

"Target world mismatch"

The app runtime has the wrong WORKFLOW_TARGET_WORLD. Check:

• Environment variable is set in deployment platform (Vercel, etc.)
• Variable name is exactly WORKFLOW_TARGET_WORLD
• Value is exactly workflow-studio/world-remote

"Unexpected hits detected"

The diagnostics endpoint reports unexpectedHitsLast15m > 0. This means the app host is receiving queue callbacks that should go to the remote worker. Check:

• Queue provider routing is configured for the worker
• Webhook URLs point to the worker, not the app host