diff --git a/pkgs/edge-worker/README.md b/pkgs/edge-worker/README.md
index b093082f2..08cd07ce1 100644
--- a/pkgs/edge-worker/README.md
+++ b/pkgs/edge-worker/README.md
@@ -21,8 +21,14 @@ Edge Worker processes messages from a PostgreSQL queue and executes handler func
import { EdgeWorker } from 'jsr:@pgflow/edge-worker';
```
-> [!WARNING]
-> Always import from JSR.io using the `jsr:` prefix. Never install from npm.
+## Package Registries
+
+`@pgflow/edge-worker` is published to both registries:
+
+- Use JSR for Supabase Edge Functions and Deno deployments.
+- Use npm for Node and Bun long-running process deployments.
+
+Supabase Edge Functions remain the primary deployment path. Node and Bun process hosting is intended for Railway, Docker, and similar hosts that run workers as normal long-running processes.
For database setup, see [pgflow installation docs](https://pgflow.dev/getting-started/install-pgflow/).
diff --git a/pkgs/website/astro.config.mjs b/pkgs/website/astro.config.mjs
index d6f7dd8c6..8698cf921 100644
--- a/pkgs/website/astro.config.mjs
+++ b/pkgs/website/astro.config.mjs
@@ -303,6 +303,10 @@ export default defineConfig({
label: 'Supabase',
autogenerate: { directory: 'deploy/supabase/' },
},
+ {
+ label: 'Node/Bun Process Workers',
+ link: '/deploy/node-bun-process-workers/',
+ },
{
label: 'Workers',
items: [
diff --git a/pkgs/website/src/content/docs/deploy/index.mdx b/pkgs/website/src/content/docs/deploy/index.mdx
index 96a4f26a6..5da2c70c9 100644
--- a/pkgs/website/src/content/docs/deploy/index.mdx
+++ b/pkgs/website/src/content/docs/deploy/index.mdx
@@ -15,6 +15,11 @@ Learn how to deploy pgflow to production, monitor workflow execution, and mainta
href="/deploy/supabase/"
description="Step-by-step guide to deploying pgflow workers to Supabase.com production"
/>
+
+ Process workers are for hosts that supervise normal processes. If you deploy
+ to Supabase Edge Functions, keep using JSR imports and the [Supabase deployment
+ guide](/deploy/supabase/).
+
+
+## Install
+
+Install the npm package in the application that owns your worker process:
+
+```sh frame="none"
+pnpm add @pgflow/edge-worker
+```
+
+## Worker Script
+
+Create a user-owned worker script that imports `EdgeWorker` and calls `EdgeWorker.start(...)`.
+
+```ts title="worker.ts"
+import { EdgeWorker } from '@pgflow/edge-worker';
+
+await EdgeWorker.start('process-orders', async (payload, context) => {
+ context.logger.info('Processing order', { payload });
+
+ return {
+ processedAt: new Date().toISOString(),
+ };
+});
+```
+
+Flow workers use the same process runtime. Import your flow definition from your app code and pass it to `EdgeWorker.start(...)`:
+
+```ts title="worker.ts"
+import { EdgeWorker } from '@pgflow/edge-worker';
+import { ProcessOrders } from './flows/process-orders.js';
+
+await EdgeWorker.start(ProcessOrders);
+```
+
+## Required Environment Variables
+
+Set these variables in your process host:
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `SUPABASE_URL` | Yes | Your Supabase project URL. |
+| `SUPABASE_SERVICE_ROLE_KEY` | Yes | Service role key used by the worker runtime. |
+| `DATABASE_URL` | Yes, unless `EDGE_WORKER_DB_URL` is set | PostgreSQL connection string for the pgflow database. |
+| `EDGE_WORKER_DB_URL` | Yes, unless `DATABASE_URL` is set | Alternative PostgreSQL connection string name shared with Supabase Edge Functions. |
+| `WORKER_NAME` | No | Worker function name recorded in pgflow. Defaults to `pgflow-worker`. |
+
+Use `DATABASE_URL` for process hosts when possible. `EDGE_WORKER_DB_URL` remains supported for deployments that share configuration with Supabase Edge Functions.
+
+## Run The Worker
+
+
+
+ Compile your app worker script to JavaScript for production, then run the compiled file:
+
+ ```sh frame="none"
+ node dist/worker.js
+ ```
+
+
+ Bun can run the app worker script directly:
+
+ ```sh frame="none"
+ bun run worker.ts
+ ```
+
+
+
+Your process manager should keep this command running. On Railway, Fly, Docker, or a VM, configure it as the service start command.
+
+## Shutdown
+
+Process workers drain on `SIGTERM`, `SIGINT`, and `SIGQUIT`.
+
+On the first signal, the worker stops accepting new work, lets in-flight tasks finish, marks the worker stopped in pgflow, and exits with code `0`. A second signal exits immediately with code `1`.
+
+## Health
+
+There is no built-in HTTP health endpoint for process workers. Use your host's process liveness checks and pgflow worker heartbeat data in the database.
+
+```sql frame="none"
+SELECT worker_id, function_name, last_heartbeat_at
+FROM pgflow.workers
+WHERE stopped_at IS NULL
+ORDER BY last_heartbeat_at DESC;
+```
+
+For more heartbeat queries, see [Monitor workers health](/deploy/monitor-workers-health/).
+
+## Supervision
+
+Process workers are tracked with `start_mode = 'process'`. `ensure_workers()` only pings HTTP-started workers and never invokes process workers.
+
+That means your process host is responsible for restarting crashed Node or Bun workers. pgflow still tracks worker rows, heartbeats, deprecation, and task recovery.
+
+## Related
+
+
+
+
+
+
diff --git a/pkgs/website/src/content/docs/deploy/supabase/index.mdx b/pkgs/website/src/content/docs/deploy/supabase/index.mdx
index 525860dea..be061ce26 100644
--- a/pkgs/website/src/content/docs/deploy/supabase/index.mdx
+++ b/pkgs/website/src/content/docs/deploy/supabase/index.mdx
@@ -24,6 +24,13 @@ Before starting, ensure you have completed [Getting Started](/get-started/instal
including Postgres image upgrades and database connection configuration.
+
+
## Deployment Overview