Skip to main content

​
1. Prove something is there

No account, no key:
You get the deployment’s capability document: protocol version, conformance level, channels, field types. Anything beyond /meta requires an authenticated caller and answers 401 authentication_required without one. Credentials on the deployed service are minted by its operator; to hold your own keys, self-host.

​
2. Run the reference implementation locally

handoffd is a Rust binary backed by Postgres. The fastest honest proof that your checkout works is the conformance run, which creates a disposable database, seeds it, starts handoffd, points the whole Level 1 suite at it, and tears everything down:
You need a Rust toolchain and a local Postgres the script may create databases in. It refuses to touch a database named omega or omega_e2e. For a durable deployment rather than a test run, core/ carries a Dockerfile and the Fly.io configuration the live service deploys from. Two operational rules from the project’s own runbook are worth repeating here:
  • Run handoffd as a Postgres role that owns its own schema and has neither SUPERUSER nor BYPASSRLS. Twenty of the twenty-one tables enforce row-level security, and a role that can bypass it leaves that defence inert while every test still passes.
  • The store is append-heavy and the audit trail is exactly as durable as your backups. A promise needs a promisor; a self-hosted deployment’s promisor is you.

​
3. Ask a person, from Python

The SDK is standard library only. It is not on PyPI yet, so install it from the checkout (this exact sequence was run while writing this page):
The redeem step is the point of the protocol: one answer mints one authorization, and redemption is idempotent per effect key, so a retried turn cannot refund the customer twice.

​
4. Survive your own crash

The wait is a durable row on the server keyed by waiter_ref, so the client holding it is disposable:
Your process can die here. Later, from anywhere:
The ordering is the point. The ack is what consumes a signal, not reading it and not returning 2xx to a callback. If the block raises, nothing is acked and the signal stays queued for the next process to find.

​
TypeScript

The TypeScript client mirrors the Python one and is consumed from source; see SDKs for the installation state of both and the full client walkthrough.