@workflow/web

Observability Web UI Package bundled in the Workflow SDK.

Self-hosting

Security notice: The @workflow/web package does not include authentication or authorization. All users who can reach the deployment share the same backend credentials configured via environment variables. If you self-host this UI, you must place it behind your own authentication layer (e.g. VPN, reverse proxy with auth, OAuth). Exposing it to untrusted users without authentication is at your own risk and may allow unauthorized access to your workflow data.

While this UI is bundled with the Workflow CLI, you can also self-host it.

There are multiple approaches:

1. Run npx workflow web --noBrowser on a server
2. Clone this repo and deploy as a normal Next.js app
3. Deploy the published @workflow/web package

All options require the environment to be configured with the right environment variables for the World you're using.

Option 1: Run with the CLI

npx workflow web --noBrowser

This will start the web UI on the default port 3456.

Option 2: Clone and deploy

• Build and deploy like any Next.js app.
• Configure the backend via environment variables (same variables the CLI writes).

Option 3: Deploy the published @workflow/web package

The published @workflow/web package contains a prebuilt .next directory and package.json. You can install it and run next start from the package directory.

Example (Node server / container):

mkdir workflow-observability-ui
cd workflow-observability-ui

npm init -y
# You must provide React runtime dependencies in your host project.
npm i @workflow/web react react-dom

# Run Next.js from the installed package (it contains the .next output)
cd node_modules/@workflow/web
npx --yes next start -p "${PORT:-3456}"

If you prefer, you can set a start script in your host package.json like:

{
  "scripts": {
    "start": "cd node_modules/@workflow/web && next start -p $PORT"
  }
}

Configuration (environment variables)

The UI reads configuration on the server via environment variables.

• Vercel (remote observability):

  • WORKFLOW_TARGET_WORLD=vercel
  • WORKFLOW_VERCEL_TEAM
  • WORKFLOW_VERCEL_PROJECT
  • WORKFLOW_VERCEL_ENV (optional; defaults to production)

• Local (filesystem-backed observability):

  • WORKFLOW_TARGET_WORLD=local
  • WORKFLOW_LOCAL_DATA_DIR (absolute path to the workflow data dir, e.g. /path/to/project/.workflow-data)
  • WORKFLOW_MANIFEST_PATH (optional; enables the Graph tab)

• Postgres:

  • WORKFLOW_TARGET_WORLD=postgres
  • WORKFLOW_POSTGRES_URL

For a complete list and CLI flags, see npx workflow inspect --help and npx workflow web --help.

If you're deploying this to Vercel, setting WORKFLOW_TARGET_WORLD to vercel is enough for the server to infer your other project details at runtime. Note that observability will be scoped to the project and environment you're deploying to.