# Install and run the current draft-3 reference This guide runs the **unpublished `1.2.0-draft.3` reference**, using package version `0.0.0.dev3`. It does not change the public draft-2 release. `odexa-current` is the current operator command; `odexa-reference` remains the legacy draft-2 command. Do not run one command against the other's state directory. The Python operator client and HTTPS adapter are packaged in `odexa_runtime`. They import no test modules. This is a bounded reference deployment for one configured article and ordinary free or fixed-quote paid agreements. It is not a general website proxy or an agent SDK. The independent Node implementations have separate conformance evidence; using the Python client below is not independent interoperability evidence. ## Install Use Python **3.12 or later** with `venv` and `pip`. The checked environment uses Python 3.12.14 and cryptography 50.0.1; exact installed dependencies and wheel contents are recorded in the verification inventory. From this source directory: ```sh python3 -m venv .venv . .venv/bin/activate python -m pip install --no-user . odexa-current --help ``` To build an installable wheel, use `python -m pip wheel --no-deps . --wheel-dir dist` and install the resulting `odexa_reference-0.0.0.dev3-py3-none-any.whl` into a new virtual environment. Normal dependency installation may use the package index. No Foundation, third-party service, payment-provider or cloud account is required. Neither the initializer nor the server changes system certificate trust, DNS or your existing website. ## Direct free operation Run these commands from a private working directory. `init` creates an empty target with owner-only permissions and refuses to replace existing data. Its generated declarations expire after 24 hours; its local TLS certificate expires after two days. ```sh odexa-current init --directory ./direct odexa-current serve --directory ./direct ``` Leave that process running. In a second terminal, activate the same environment and return to the same working directory: ```sh odexa-current pin --directory ./direct --trust-directory ./direct-trust \ --registry ./direct/registry-pins.json odexa-current agree --directory ./direct --out ./direct-exchange.json odexa-current retrieve --directory ./direct --exchange ./direct-exchange.json \ --out ./article.txt odexa-current status --directory ./direct --exchange ./direct-exchange.json odexa-current reports --directory ./direct ``` The origin and agreement service run at `https://127.0.0.1:8443`. The generated policy requires an agreement for `retrieve` / `public_retrieval` at `/about`, with attribution. Other resources and uses receive no grant. The client checks exact policy, authority and pre-approved human terms before assent, checks the signed receipt using the origin's public key declaration, and prints the attribution with the retrieved-byte digest. It never needs the service's private key to verify a receipt. This client implements the demonstrated retrieval; it does not claim continuing-storage or training duties. Successful delivery writes an origin-observed event to a durable gateway outbox. `reports` explicitly drains up to 100 queued records and verifies the collector's acknowledgement. Run it again to retry failed deliveries; acknowledged records are retained rather than sent again. Receipt by the HTTP client can precede the gateway's local completion commit, so a just-started drain may find nothing yet. An empty drain is not proof that every request was reported. The gateway journal separately retains admitted, in-flight, completed and partial outcomes; inspect unresolved entries when operating the service. ## Restart, revoke and verify an archive Stop `serve` with Ctrl-C. It closes its listeners and waits for active handlers to finish. Start the same command against the **same directory**; it reopens existing agreements, credentials, authority history, gateway admissions, outbox and exact retry state. Do not run `init` again, delete journals to clear an error or copy another provider's database over this one. ```sh odexa-current serve --directory ./direct ``` In the second terminal: ```sh odexa-current reports --directory ./direct odexa-current revoke --directory ./direct --exchange ./direct-exchange.json ``` A subsequent `retrieve` must fail. Revocation stops future access; it does not erase accepted terms or earlier evidence. Copy the `agreement_id` printed by `agree` into the following command: ```sh odexa-current export --directory ./direct --agreement-id AGREEMENT_UUID \ --out ./direct-bundle.json odexa-current verify --trust-directory ./direct-trust --bundle ./direct-bundle.json \ --archive-directory ./verified-archive ``` `export` is a **local administrator operation**, not an unauthenticated HTTP export endpoint. It checks current origin export authority and reads one closed ordinary-profile snapshot. `verify` uses the separate trust directory and an inert archive database. Its output distinguishes verified signatures/snapshot closure from global capture, downstream use and access permission. Importing an archive never provisions credentials or restores access. Existing output files are not overwritten; choose another filename for a later snapshot. The `pin` command explicitly imports independently supplied reporter/payer registry public keys and fetches policy/authority over verified origin HTTPS. For this same-owner example, `registry-pins.json` was created at provisioning time, before the export. A different verifier must obtain these pins from a trusted registry/operator channel, **not from the candidate archive or an untrusted sender**. `refresh-trust --trust-directory ./direct-trust` retains later origin observations and prevents locally observed rollback. Retained documents are historical evidence; a failed fresh origin read is not replaced by cache. Keep current export authority available until required imports complete, as described in [provider handover](PROVIDER-HANDOVER.md). ## Delegated free operation Stop the direct example before reusing its ports. Select a separate HTTPS service origin explicitly: ```sh odexa-current init --directory ./delegated --origin https://127.0.0.1:8443 \ --service-origin https://127.0.0.1:8444 odexa-current serve --directory ./delegated ``` Use the same `pin`, `agree`, `retrieve`, `reports`, `revoke`, `export` and `verify` commands with the delegated directory and distinct output/trust paths. `serve` starts two HTTPS listeners. The origin retains `/odexa.json`, `/odexa-service.json` and protected delivery; the provider runs `/api/`. The origin's explicit delegation appoints that provider's endpoint, capabilities, scope, lifetime and signing key. The provider is optional and receives no payment configuration in this mode. To run the two configured roles as separate processes, use `serve --role origin` and `serve --role service`. This local demonstration uses one owner's configuration directory. Do not give a real third-party operator a copy containing the origin's, agent's or payer's private credentials. Provision separate deployments and distribute only the authority declarations, explicit public registry pins and credentials each role needs. The wire contracts and [handover procedure](PROVIDER-HANDOVER.md) govern that separation. ## Optional fixed-quote verification The generated paid mode is deliberately limited to **two loopback origins and a synthetic read-only verifier**. It is an executable payment-state example, not a processor or a real-world settlement assertion. No command debits, refunds or transfers money. ```sh odexa-current init --directory ./paid --origin https://127.0.0.1:8443 \ --service-origin https://127.0.0.1:8444 --synthetic-paid odexa-current serve --directory ./paid ``` In the second terminal: ```sh odexa-current pin --directory ./paid --trust-directory ./paid-trust \ --registry ./paid/registry-pins.json odexa-current agree --directory ./paid --out ./paid-exchange.json ``` The output shows the exact quote digest and quote terms: synthetic USD 1.00 resource licence plus USD 0.25 provider fee. The signed receipt is pending payment and is not an access credential. Review the quote before explicitly using the separate payer credential: ```sh odexa-current mandate --directory ./paid --exchange ./paid-exchange.json odexa-current verifier-state --directory ./paid --state confirmed odexa-current retrieve --directory ./paid --exchange ./paid-exchange.json \ --out ./paid-article.txt odexa-current reports --directory ./paid odexa-current verifier-state --directory ./paid --state reversed ``` Retrieval fails before a mandate, after a mandate alone while the verifier remains pending, and after a verified reversal. The synthetic verifier retains exact check identities/responses and a monotonic sequence across restart. Old responses do not become fresh by replay. `pending`, `failed`, `confirmed` and `reversed` are operator-controlled test assertions. The existing paid protocol retains its 256-distinct-checks-per-agreement reference limit; status/token requests can consume checks. Use the same archive commands with `paid-trust`; this explicitly selects the ordinary paid archive and requires separately pinned payer keys. Changing an entirely free agreement into a paid one is not a configuration toggle: use a new setup and fresh assent. Real provider adapters must implement the existing [payment authentication](PAYMENT-AUTHENTICATION.md) and [network verification](NETWORK-PAYMENTS.md) contracts with independent payer credentials. `runtime.json` supports an explicit `payment.mode="external"` and verifier binding/quote configuration for operator adapters; this has no built-in real payment connector and the installed end-to-end example validates the synthetic mode only. ## Publication and configuration inventory For an existing website's initial policy publication, follow the [website discovery guide](DISCOVERY.md). Publish the actual policy at your canonical HTTPS origin's credential-free `/odexa.json`; optionally add an informational robots comment and a concise `/llms.txt` linking to it and the documentation. Preserve your existing crawl rules. These signposts are not generated by the commands above, and do not appoint a provider or accept agreements. Include a service-metadata link only when you have implemented that service and published its authority document. | Path | Meaning and handling | | --- | --- | | `public/odexa.json` | Origin policy; publish exact bytes at the origin root | | `public/odexa-service.json` | Origin appointment of direct/delegated services and public keys; publish at the origin root | | `public/odexa-observation.json` | Optional separately validated [coverage declaration](OBSERVATION-COVERAGE.md); not generated automatically | | `runtime.json` | Private operator configuration: binding, origins, listeners, TLS, transport and optional quote/verifier setup | | `keys/`, role JSON files, TLS key | Private keys and scoped credentials; never publish or commit | | `registry-pins.json` | Independently provisioned public reporter/payer identities; review before trusting | | `terms.txt`, `asset.txt` | Exact human terms and the one protected reference article | | `state/` | Durable service, authority, gateway and optional synthetic-verifier state | | Separate trust directory | Independently retained origin documents, key descriptors and rollback history; no bearer credentials | | Separate archive directory | Inert verified evidence; not a live service database | You may publish a native policy on an existing static HTTPS site without running any service. Static publication communicates terms; it does not block agents or measure undisclosed activity. Do not advertise generated service declarations as an available service unless that service is implemented. This generated policy's `require_agreement` rule needs its appointed service to grant new access. To publish static permission, edit and validate the native policy deliberately using the [policy core](POLICY-CORE.md); an unavailable agreement service supplies no permission. For an operator-owned public hostname, pass its canonical HTTPS `--origin`, and `--tls-cert` / `--tls-key` for a certificate covering every listener hostname. `--ca-file` selects explicit private trust when needed; otherwise outbound reads use system roots. The public-host initializer refuses to generate a misleading loopback certificate. `listeners` in private configuration select local bind addresses/ports; defaults bind only `127.0.0.1`. Direct HTTPS or TLS passthrough must preserve the declared `Host` and endpoint origin; forwarded headers are not authority. A certificate covering multiple origins or separately configured role deployments is needed for separate public hosts. The executable guide's verified deployment is loopback HTTPS, not an audited public hosting service. To renew declarations, retain old exact bytes, increment revisions monotonically, preserve policy/key identity, and publish the new validity interval deliberately. Runtime reads the public files for each origin request; it never silently renews authority or rotates keys. Current CLI clients use the configured active signing identity; historical evidence and provider/key transitions use [authority history](AUTHORITY-HISTORY.md), [portability](PORTABILITY.md), [paid portability](PAID-PORTABILITY.md) and [provider handover](PROVIDER-HANDOVER.md). Existing paid rights are not assigned to a successor by copying configuration. The installed commands currently cover ordinary retrieval/reporting/free/paid archives. Selected continuing-storage and native-asset profiles retain their separate APIs and clients; this command does not silently select them. The [independent Node paid flow](INDEPENDENT-PAID-CLIENT.md) is now separately evidenced. The [native asset graph client](INDEPENDENT-ASSET-CLIENT.md) now completes the independent M5 implementation evidence. The M6 consolidated review edition and full current-source validation are now prepared. Integrated review, verified private security intake, the final frozen artifact and candidate publication remain M6. See [security and operation](../SECURITY.md) before exposing an operator deployment.