# For host implementers

> Source: https://openwop.dev/for/host-implementers/ · OpenWOP, the open-source protocol for multi-agent workflow orchestration.

You're implementing OpenWOP against a runtime — your own engine, a customer's stack, a managed service you're building. This page tells you what the conformance suite expects, what the advertise-honestly principle costs you, and which reference implementation to mine first.

## The contract in one sentence

A host advertises a set of capabilities at `GET /.well-known/openwop`, implements the REST endpoints + SSE streams + signed webhooks for the capabilities it claims, and passes the conformance scenarios gated on those capabilities. Anything you don't claim, you don't have to implement.

## Read these first

- [Capabilities](https://openwop.dev/spec/v2/core/capabilities.html) — the advertisement shape. A host that supports a feature advertises a record for it; a host that doesn't, omits it.
- [Profiles](https://openwop.dev/profiles/) — the named capability bundles a host can claim. Each profile is a predicate over `/.well-known/openwop` plus a set of conformance scenarios.
- [REST endpoints](https://openwop.dev/spec/v2/core/runs.html) — every endpoint with request/response shapes and the canonical error codes.

## The advertise-honestly principle

If you advertise a capability, the conformance scenarios for it run against your host, and you must pass them. If you omit it, those scenarios are skipped and you owe nothing.

Do **not** advertise a capability your host doesn't handle correctly. Leaving out something you can't do yet is the right posture, not a weakness. The same goes for [`production`](https://openwop.dev/spec/v2/core/capabilities.html#production): claim it only once backpressure, retention, claim acquisition and orphan recovery all hold under test.

The leaderboard at [/conformance/](https://openwop.dev/conformance/) is the public record. A host that overclaims will fail in someone else's CI before it fails for an end user.

## Start from a reference host

Mine [`examples/hosts/v2-reference/`](https://github.com/openwop/openwop-examples/tree/main/examples/hosts/v2-reference) in `openwop/openwop-examples`. It was written directly from the [v2 spec](https://openwop.dev/spec/v2/) and certifies all three v2 profiles. Its `conformance.md` records which profiles it claims and its latest results.

For a step-by-step path, start from [`docs/IMPLEMENT-CORE.md`](https://github.com/openwop/openwop/blob/main/docs/IMPLEMENT-CORE.md).

## Run the conformance suite

The conformance suite is published as `@openwop/openwop-conformance` on npm, with its exact-pinned contract peer `@openwop/spec-artifacts` at the same version — install both together. Point it at your host:

```bash
npm install --legacy-peer-deps @openwop/openwop-conformance@<version> @openwop/spec-artifacts@<version>
npx @openwop/openwop-conformance --base-url https://my-host.example.com --api-key … \
  --target-major 2 --require-behavior
```

`--target-major 2` runs the v2 scenarios. `--require-behavior` is strict mode: an advertised behaviour that can't be observed fails instead of being skipped. Scenarios only run for the capabilities your host advertises. The leaderboard wants a signed bundle (`--certify bundle-v3.json`) plus a `conformance.md` recording the run.

## Common implementation surfaces

- Event log + suspend/resume: see [Storage adapters](https://openwop.dev/spec/v2/core/persistence.html).
- BYOK secret resolution: see [Auth](https://openwop.dev/spec/v2/core/identity.html) and the [secret-leakage threat model](https://github.com/openwop/openwop/blob/main/SECURITY/threat-model-secret-leakage.md).
- Signed webhooks: see [Webhooks](https://openwop.dev/spec/v2/core/webhooks.html); the HMAC recipe is `HMAC-SHA256({timestamp}.{rawBody})`.
- Interrupts: see [Interrupts](https://openwop.dev/spec/v2/core/interrupt.html) for the nine v2 kinds and the shared resolve contract.
- OAuth-granted credentials for connector nodes: see [OAuth](https://openwop.dev/spec/v2/core/oauth.html) — the host as an OAuth client, and the `credentials` family.

## What you owe the matrix

When you ship an OpenWOP host (your own or for a customer), open a PR that:

1. Adds a row to [`INTEROP-MATRIX.md`](https://github.com/openwop/openwop/blob/main/INTEROP-MATRIX.md).
2. Adds your signed bundle under `evidence/v2-host-bundles/`, with a `conformance.md` beside it recording the suite version, command line, target URL class, and pass / fail / blocked / inapplicable / skipped counts.
3. Lists the profiles you claim and the ones you explicitly don't (`OPENWOP_OPTED_OUT_PROFILES`, so the bundle records the opt-out).

The leaderboard rebuilds automatically. A claim counts as certified only when the bundle shows every required check for that profile passing, and CI re-verifies the bundle. Describing it honestly in your row is still on you.

## Next steps

| Action | Where |
|---|---|
| Read the host capabilities spec | [/spec/v2/core/capabilities.html](https://openwop.dev/spec/v2/core/capabilities.html) |
| Browse profile predicates | [/profiles/](https://openwop.dev/profiles/) |
| Check the leaderboard | [/conformance/](https://openwop.dev/conformance/) |
| Clone the reference host | [examples/hosts/v2-reference](https://github.com/openwop/openwop-examples/tree/main/examples/hosts/v2-reference) |
| Run the conformance suite | `npx @openwop/openwop-conformance` |