Standalone quickstart

This guide runs the current 1.2.0-draft.3 reference, packaged as Python distribution 0.0.0.dev3. Use odexa-current for the current operator path; odexa-reference is the separate legacy draft-2 command. Do not run either 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. Download the source ZIP, save it as odexa-reference.zip, then run the commands below from its download directory. The archive extracts to odexa-v1.2-rc.1-staging.4/; enter its source/ folder before installing. The checked environment uses Python 3.12.14 and cryptography 50.0.1; exact dependencies and wheel contents are recorded in current validation.

unzip odexa-reference.zip
cd odexa-v1.2-rc.1-staging.4/source
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.

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:

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.

odexa-current serve --directory ./direct

In the second terminal:

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:

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.

Delegated free operation

Stop the direct example before reusing its ports. Select a separate HTTPS service origin explicitly:

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 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.

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:

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:

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 and network verification 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. 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; 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; 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, portability, paid portability and provider handover. Existing paid rights are not assigned to a successor by copying configuration.

The installed commands 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 and native asset graph client have separate evidence in current validation. The integrated technical review and corrections are complete; the owner has confirmed private security intake and the reviewed package is frozen for RC1. See security and operation before exposing a deployment, and release status for this implementation candidate.