OpenWOP in 10 Minutes

Status: v2. Every call below uses unversioned paths (/runs) and sends an OpenWOP-Version: 2 header. The responses were captured from the v2 reference host and abbreviated. The capture ran on port 3990; your host listens on 3838, so its URLs will say 3838.

This is the fastest path from "what is OpenWOP?" to "I have a v2 workflow running on my laptop". You need Node 20+ and a clone of openwop/openwop-examples, which holds the reference hosts and runnable samples. You don't need a vendor SDK, a managed service, or a framework.

1. Minute 0–2: start the v2 reference host.
2. Minute 2–5: run a workflow with curl.
3. Minute 5–8: run the same workflow with the TypeScript SDK.
4. Minute 8–10: stream events live over SSE, resume a stream, and cancel a run.

QUICKSTART.md covers more (webhooks, fork and replay, configurable, node packs, conformance) and works against any v2 host. This guide assumes you have nothing yet.

Prerequisites

node --version  # must be >= 20
git --version

That's all. You don't need Docker, a cloud account, or provider API keys.

Minute 0–2: start the v2 reference host

git clone https://github.com/openwop/openwop-examples.git
cd openwop-examples/examples/hosts/v2-reference
npm install --legacy-peer-deps
npm start

You should see a line like this one (captured with OPENWOP_PORT=3990; yours names port 3838 and db data/v2-reference.sqlite):

openwop-host-v2-reference listening on http://127.0.0.1:3990 (protocolVersions 1.11, 2.0; preferredVersion 1.11; db …; fixtures 16; seams mounted; spec-artifacts 2.42.2)

Leave it running. --legacy-peer-deps is required: the host's README explains the exact-pinned conformance peers it works around. The host stores runs in one SQLite file (data/v2-reference.sqlite). Set OPENWOP_DB_PATH=:memory: if you want nothing written to disk.

The boot line says protocolVersions 1.11, 2.0; preferredVersion 1.11: this host still serves the frozen v1 wire next to v2. An unversioned path such as /runs is always the v2 surface. Only /.well-known/openwop follows the header, and without one it returns the preferredVersion (v1) document (spec/v2/core/versioning.md §1.3). Every call below sends OpenWOP-Version: 2 so discovery returns the v2 document too.

In a separate terminal:

export OPENWOP_URL=http://127.0.0.1:3838
export TOKEN=openwop-v2-dev-key   # the host's default dev key (OPENWOP_API_KEY overrides it)

Minute 2–5: run a workflow with curl

Discover

curl -s -H 'OpenWOP-Version: 2' $OPENWOP_URL/.well-known/openwop \
  | jq '{protocolVersions, preferredVersion, implementation, replay}'

{
  "protocolVersions": ["1.11", "2.0"],
  "preferredVersion": "1.11",
  "implementation": {
    "name": "openwop-host-v2-reference",
    "version": "2.0.0-rc.1",
    "vendor": "openwop (reference example)"
  },
  "replay": {
    "status": "experimental",
    "since": "2.0",
    "until": "2.1",
    "witness": "witnessable-gated",
    "modes": ["replay", "branch"],
    "retention": { "days": 30 },
    "effectSeamsManifest": "/host/effect-seams"
  }
}

This is the closed v2 discovery root. Each family (replay here) is a record with status, since, witness, and its facets. A family that is present is supported. v2 has no supported: true flags. jq '.fixtures' lists the 16 test workflows the host can run.

Create a run

curl -s -X POST $OPENWOP_URL/runs \
  -H 'OpenWOP-Version: 2' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"workflowId":"conformance-multi-node"}'

{
  "runId": "openwop-reference-tenant/9fasFA1XO6OIVVrEDg6S_Msv",
  "status": "pending",
  "eventsUrl": "http://127.0.0.1:3990/runs/openwop-reference-tenant~2F9fasFA1XO6OIVVrEDg6S_Msv/events",
  "statusUrl": "http://127.0.0.1:3990/runs/openwop-reference-tenant~2F9fasFA1XO6OIVVrEDg6S_Msv"
}

A v2 runId is tenant-bound (<tenant>/<opaque>). In a URL, the / travels as ~2F. Use the last path segment of statusUrl as your run reference:

RUN=openwop-reference-tenant~2F9fasFA1XO6OIVVrEDg6S_Msv   # paste yours

Get the snapshot

curl -s -H 'OpenWOP-Version: 2' -H "Authorization: Bearer $TOKEN" \
  $OPENWOP_URL/runs/$RUN | jq '{status, owner, eventLogSchemaVersion}'

{
  "status": "completed",
  "owner": {
    "tenant": "openwop-reference-tenant",
    "subject": {
      "issuer": "urn:openwop-host-v2-reference:api-key",
      "subjectId": "default",
      "tenant": "openwop-reference-tenant",
      "lane": "api-key",
      "kind": "user"
    }
  },
  "eventLogSchemaVersion": 3
}

You just ran an OpenWOP v2 workflow with three HTTP calls and no client library. owner.subject is who the host decided you are, and the host derives it from your credential, never from the request body.

Minute 5–8: run the same workflow with the TypeScript SDK

The 2.x line of @openwop/openwop sends OpenWOP-Version on every request.

mkdir -p /tmp/openwop-quickstart && cd /tmp/openwop-quickstart
npm init -y > /dev/null
npm pkg set type=module
npm install @openwop/openwop@2

cat > quickstart.mjs <<'EOF'
import { OpenwopClient } from '@openwop/openwop';

const client = new OpenwopClient({
  baseUrl: 'http://127.0.0.1:3838',
  apiKey: 'openwop-v2-dev-key',
});

const caps = await client.discovery.capabilities();
console.log('Server:', caps.implementation?.name, caps.protocolVersions);

const { runId } = await client.runs.create(
  { workflowId: 'conformance-multi-node' },
  { idempotencyKey: crypto.randomUUID() },
);
console.log('Created:', runId);

for await (const event of client.runs.events(runId)) {
  console.log(`  [${event.sequence}] ${event.type}`);
}

const snap = await client.runs.get(runId);
console.log('Final:', snap.status);
EOF

node quickstart.mjs

Output (captured with @openwop/openwop 2.3.0):

Server: openwop-host-v2-reference [ '1.11', '2.0' ]
Created: openwop-reference-tenant/G_N8_vAoLjSAzDK7a2rLAB-n
  [0] run.started
  [1] node.started
  [2] node.completed
  [3] node.started
  [4] node.completed
  [5] node.started
  [6] node.completed
  [7] run.completed
Final: completed

client.runs.events consumes the SSE stream. It ends after the terminal event, so you don't need a polling loop. The Python (openwop-client>=2) and Go (github.com/openwop/openwop-sdks/go/v2) clients have the same shape. All three live in openwop/openwop-sdks.

Note: to test an unpublished SDK checkout instead, clone openwop-sdks, run npm install && npm run build && npm link in sdk/typescript-v2/, and replace the install step with npm link @openwop/openwop.

Minute 8–10: stream events live over SSE

Start a long-running workflow. conformance-cancellable waits delayMs before it completes.

curl -s -X POST $OPENWOP_URL/runs \
  -H 'OpenWOP-Version: 2' -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"workflowId":"conformance-cancellable","inputs":{"delayMs":30000}}'
RUN=...   # the last path segment of the statusUrl it returns

Attach to its event stream:

curl -s -N -H 'OpenWOP-Version: 2' -H "Authorization: Bearer $TOKEN" \
  "$OPENWOP_URL/runs/$RUN/events"

While it waits, cancel it from a third terminal:

curl -s -X POST -H 'OpenWOP-Version: 2' -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"reason":"quickstart demo"}' \
  "$OPENWOP_URL/runs/$RUN/cancel"

{"runId":"openwop-reference-tenant/1xe1dnUaKrvDQjragfK7I05a","status":"cancelling"}

The stream shows the whole life of the run and then closes:

id: 0
event: run.started
data: {"eventId":"nujxvYrr4atcpEqbUTS0Dls6","runId":"openwop-reference-tenant/1xe1dnUaKrvDQjragfK7I05a","type":"run.started",…}

id: 1
event: node.started
data: {…,"type":"node.started","payload":{"nodeId":"wait","typeId":"core.delay",…}}

id: 2
event: node.cancelled
data: {…,"type":"node.cancelled",…}

id: 3
event: run.cancelled
data: {…,"type":"run.cancelled","payload":{"reason":"quickstart demo",…}}

Three details are worth knowing:

• id: is the event's sequence. If your connection drops, reconnect with -H 'Last-Event-ID: 1' and the host sends only events with a higher sequence.
• The host replays the backlog on connect. Attaching after a run has finished still shows every event, and the stream closes after the terminal event.
• A second cancel is refused. The run is already terminal, so you get 409 run_terminal with details.runStatus: "cancelled".

What you just learned

Where to go next

• QUICKSTART.md covers webhooks, fork and replay, configurable, node packs, conformance, and SDKs against any v2 host.
• INTEROP-MATRIX.md shows which hosts have a v2 certification bundle, including this one.
• docs/migration/v1-to-v2.md is for readers who have v1 client code.
• Build a node pack: docs/PACK-AUTHOR-QUICKSTART.md.

The tiny-workflow and streaming-client samples in openwop-examples speak v2 and run against the v2 reference host. The in-memory host there serves only the frozen v1 wire (/v1/…, port 3737), so it won't work with this walkthrough.

Troubleshooting

If something else doesn't work, file an issue at <https://github.com/openwop/openwop/issues>. The v2 reference host is supposed to "just work" for this guide.