> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omegas.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Handoff quickstart

> Probe the live service, run the reference server and its conformance suite locally, and make your first request from Python or TypeScript.

## 1. Prove something is there

No account, no key:

```sh theme={null}
curl https://handoff.omegas.dev/v1/meta
```

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:

```sh theme={null}
git clone https://github.com/OmegaAgent/handoff
cd handoff/core
dev/run-conformance.sh              # every Level 1 case
dev/run-conformance.sh --case C-8   # one case
KEEP=1 dev/run-conformance.sh       # leave the database up for inspection
```

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):

```sh theme={null}
pip install ./handoff/sdk/python
```

```python theme={null}
import handoff

handoff.configure(base_url="https://your-handoffd.example/v1", api_key=...)

# Ask a person. Blocks until they answer.
address = handoff.ask("Which shipping address should I use?")

# Ask for a decision, then spend it on exactly one effect.
outcome = handoff.approve("Refund $2,400 to Acme Corp?", mode="gated")
if outcome and outcome.redeem("stripe:refund:ch_1B").first_redemption:
    stripe.refund("ch_1B")
```

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:

```python theme={null}
pending = handoff.raise_request(
    waiter_ref="run:0198f2a1",
    prompt=handoff.prompt("Refund $2,400 to Acme Corp?",
                          "Invoice INV-8821 was double-charged."),
    requires=handoff.requires(
        [handoff.fields.choice("decision", "Decision", ["approve", "reject"])],
        authority=handoff.authority("editor", "session"),
    ),
)
```

Your process can die here. Later, from anywhere:

```python theme={null}
waiter = handoff.resume("run:0198f2a1")   # the only thing that had to survive
with waiter.receive() as received:
    apply(received.values)                # your work
# the ack is sent here, after the block completed
```

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](/handoff/sdks) for the installation state of both and the full client
walkthrough.