Skip to content

The Proxy ​

Checked against the source on 2026-11-09: the SDK's theprotocol/proxy/ (the spec, the runtime, the outbox, the built-in sources, actions and sinks, the command line) and its eight recipes in proxy/recipes/. Every command below was run as printed against the SDK source, and each recipe was driven end to end on the sandbox with its own fake of the system it connects (2026-11-08). The proxy ships in the SDK from 0.8.0 on PyPI (pip install "theprotocol-sdk[proxy]", checked in a clean environment on 2026-11-14).

Replacing a system rather than bridging it?

The proxy also moves the data of an old system into its replacement: read the old system, map each field, write the new one, check both sides match and get a certificate. That is a migration, and it has its own chapter: Migrate a system.

The proxy console

The console has a page for the proxy: the connectors with their fields, the eight recipes with their commands, and a spec builder that checks a spec in your browser as tp-proxy validate would and hands you proxy.yaml, nothing sent anywhere (the proxy console). Signed in, My proxies there shows the proxies of your agents that report their status.

Why It Matters ​

Most of what a business would prove or settle on TheProtocol already happens in a system that knows nothing about it: an order system that releases orders, a terminal that gates containers out, a meter that reads every quarter hour, a mediation system that rates calls. Rewriting those systems is not an option. The proxy sits beside one: it gives the system an agent identity on TheProtocol, reads what the system already writes (a file, a webhook, a database table, an MQTT topic, an SFTP folder) and turns each record into a call on TheProtocol: a signed attestation, a contract milestone's evidence, a payment under a mandate. In the other direction it hands TheProtocol's own events (a payment received, a payment settled) to the legacy system: a signed webhook, an accounting journal, an evidence export.

You write no code. You write one file, proxy.yaml, and the proxy keeps three promises about it: each record is sent once (a crash, a restart or a repeat delivery does not send it twice), a secret is never written in it, and the agent holds only the authority its mappings need.

Install ​

From PyPI (the proxy extra; proxy-mqtt, proxy-sftp, proxy-sql and its per-database variants add the sources that need a client library):

bash
pip install "theprotocol-sdk[proxy]"
tp-proxy --help

The proxy runs as its own agent. Create the agent in the console (or with Agent Forge's starter) and keep its client_id and client_secret where the spec can name them: an environment variable or a file.

The Spec ​

A spec names the registry, the agent, where the proxy keeps its state, and four kinds of parts: sources (where records come from), actions (calls on TheProtocol), sinks (deliveries to a legacy system) and mappings (which records go where, and how their fields are built). This one attests each released order a file drop holds:

yaml
version: 1
name: orders-to-attestations
registry: https://api.theprotocol.cloud
identity:
  agent_did: env:AGENT_DID
  client_id: env:CLIENT_ID
  client_secret: env:CLIENT_SECRET
state: ./orders-state.db
sources:
  oms:
    type: filedrop
    config: {path: ./oms-out, format: json, suffix: .json, id_field: intent_id, poll_seconds: 30}
actions:
  attest:
    type: attestation
    config: {attestation_type: example.order_released}
    limits: {per_minute: 60}
sinks: {}
mappings:
  - name: released
    version: 1
    from: oms
    to: attest
    when: {path: $.payload.data.status, equals: RELEASED}
    fields:
      order: $.payload.data.order_id
      sku: $.payload.data.sku
      quantity: $.payload.data.quantity
      plant: PLANT-NORTH
bash
tp-proxy validate proxy.yaml

validate checks the spec against the core's schema and every part's configuration against its own, and names the first thing it refuses by its path in the file.

References, never secrets. A credential is written as env:NAME (an environment variable), file:/path (a file's content) or file:/path#KEY (one KEY=value line of a dotenv file, such as the starter's .env.secret). A literal value where a secret belongs is refused when the spec loads.

Mappings. from names a source; to names an action (inbound) or a sink (outbound). when takes one condition on the record: {path, equals}, {path, in} or {path, exists}. Each field is a JSONPath into the record ($.payload...), a literal, or {path, default} for a field a record may lack. A mapping's version is part of every record's key: raise it when a mapping changes what it sends, and a record read again (a run --replay of a source from an earlier point) is sent under the new meaning instead of being taken for the one already sent.

What a source hands a mapping. A file drop and an SFTP folder: {file, row, data} (SFTP adds the file's sha256), the row under data, every CSV value a string. A webhook: the posted body. MQTT: {topic, levels, data, encoding}. An SQL poll: the row itself. TheProtocol's own events: the event's data.

Exactly Once ​

Every record a mapping takes becomes one row in the proxy's outbox (SQLite, in state) under a key built from the source, the record's id, the mapping and its version. The row is written before anything is sent, and it is sent with its key as the Idempotency-Key. A record read twice (a file read again after a restart, a webhook retried by its sender, an MQTT message delivered again) finds its key already there and is not sent twice. A crash between the send and the outbox's "done" sends the row again on the next start; the registry answers a repeated key with its first answer, so it is still once. Measured on the sandbox: a proxy stopped between sending an attestation and marking it done sent it again on restart, and the registry held the same eight attestations, not nine.

What could not be sent stays in the outbox and is retried with backoff (retry); what the other side refuses outright, or what is still failing after the last attempt, becomes a dead letter:

bash
tp-proxy status proxy.yaml          # the outbox, the switches, each mapping's breaker
tp-proxy dead proxy.yaml            # the dead letters, each with its reason
tp-proxy replay proxy.yaml --key <key>   # send one dead letter again (or --mapping NAME, or --all)
tp-proxy pause proxy.yaml released  # stop sending one mapping's rows (resume undoes it); without a name: all

A mapping whose calls keep failing is stopped by its breaker (breaker: {refusals, failures, cooldown_s}) and says why in status, instead of turning a whole backlog into dead letters.

Running It ​

bash
tp-proxy run proxy.yaml --dry-run --once   # map and print what it would send, send nothing
tp-proxy run proxy.yaml                    # for real, as a service (/health and /metrics on service.listen)

--once stops when every source has finished and nothing is due. A file drop, an SFTP folder and an SQL table finish only with poll_seconds: 0 (read what is there once); with a positive poll_seconds they keep listing, so a file dropped while the proxy runs is read too (the example above lists its folder every 30 seconds, so give a --once try poll_seconds: 0; a file drop takes poll_seconds from SDK 0.9.0, and 0.8.0 refuses it and reads the folder once); a receiver (a webhook, MQTT, TheProtocol's events) never finishes, so a spec with one runs until stopped, dry or not. A file is read once it has not changed for settle_seconds (2 by default) or once its marker file exists (require_marker): a --once run started while an export is still being written passes over it, and the next run reads it.

Least Authority ​

The proxy's agent holds only the permissions its mappings need. tp-proxy init writes a spec from the agent's starter folder and asks the registry about the agent: that it issues the agent its access credential, the agent's card and bond, and the permissions each action needs, which the owner grants in the console (the agent's access panel). An attestation needs reputation.signal (the attestor role carries it and nothing else); a call the agent may not make is refused by the registry and becomes a dead letter that names the refusal. A milestone's evidence is delivered as the contract's provider.

A payment needs three things the owner sets in the console, and the proxy refuses to start without them: a Cockpit mandate for a2a.pay named in the action's mandate:, the agent's spend cap at or under that mandate's limits, and the action's own max_amount (and optionally per_day). A record over max_amount is never paid: it becomes a dead letter. Each payment is authorized under the mandate (X-Liability-Mandate) and settled with the record's key as its task id, so the registry's payment.settled notice names the record it paid.

Evidence You Can Check Without Us ​

The evidence sink writes each record it receives as a line of a hash chain (each line names the hash of the one before) and signs a manifest of the files with an Ed25519 key you hold. Anyone with the folder and your public key checks it offline:

bash
tp-proxy keygen ./evidence.pem      # prints the public key
tp-proxy verify ./erp-in --key <public key>

verify answers holds: true with the line count and the chain's head, or holds: false naming each problem, with exit code 1: a line that was changed (its own hash no longer matches, nor the manifest's hash of its file), an evidence file (evidence-*.jsonl) missing or one the manifest does not name, a file with more or fewer lines than the manifest says, or a manifest signed by a key other than the one you named.

The Built-In Parts ​

kindtypewhat it does
sourcefiledroprows of CSV, JSON, JSON Lines or XML files in a folder
sourcesftpthe same from an SFTP server: key login, the host key pinned in known_hosts, each file moved or marked once read
sourcesqlpollnew rows of a table past a cursor column (SQLite; PostgreSQL, MySQL and SQL Server with the proxy-sql extras)
sourcemqttmessages on topic filters (QoS 1, a kept session)
sourcewebhookJSON posted to a path, checked against an HMAC-SHA256 signature
sourcelogtailnew lines of a log file, across rotation
sourcetheprotocol_eventsthe registry's own webhooks (payment.received, payment.settled and the rest), checked against the webhook's secret
actionattestationa signed fact, its data hashed onto the ledger
actionmilestone_evidencea contract milestone's delivery, as its provider
actionpaymenta payment under a mandate, never above max_amount
actiona2a_taskan A2A call to another agent
actionchat_messagea message in a chat room
sinkwebhooka signed POST to the legacy system (X-Signature-256, the record's key as Idempotency-Key)
sinkjournalaccounting lines as CSV, or camt.053 for accounting systems that import account statements
sinkevidencethe signed hash chain above
sinkcalendar, email_digestan ICS calendar file, one event per delivery; a digest of the deliveries by mail at an interval

Eight Recipes ​

The SDK's proxy/recipes/ holds a ready spec for each of the eight blueprints, a fake of the legacy system it connects and a README. Each was driven on the sandbox with its fake; the two that move units kept the ledgers' supply delta at 0.

recipethe legacy systemon TheProtocol
MERIDIANan order system's nightly JSON exportreleased orders attested; each exported as signed evidence for the ERP
HANSAa terminal's gate events (webhook)gate-outs attested and sent, signed, to the ERP; gate-ins left
DYNAMOsmart meters over MQTTevery reading attested, its meter taken from the topic
BAZAARa shop's inventory events, and TheProtocol's payment.receivedinventory attested; the warehouse told to fulfil only once the shop agent's payment has arrived
SCRIVENERa practice-management system's matter eventsa matter's life attested (a filing with its document's SHA-256) and exported as evidence
LYCEUMa student-record system's CSV of awardseach awarded credential attested; a revoked one left for the console
KEYSTONEa site test logger's runs on SFTPa passed acceptance test delivered as a contract milestone's evidence; a failed run delivers nothing
TRUNKa mediation system's settlement tableeach rated event paid to the partner's agent under a mandate; the journal booked from payment.settled, so only what settled

Try one without a registry: LYCEUM's fake writes an export and the dry run shows what would be sent.

bash
cd theprotocol-sdk/proxy/recipes/lyceum
python fake/fake_sis.py ./sis-out --count 5 --run T1
sleep 3     # the export settles (settle_seconds is 2): a fresh file is passed over
sed -e 's#/data/sis-out#./sis-out#' -e 's#/data/lyceum-state.db#./lyceum-state.db#' proxy.yaml > local.yaml
AGENT_DID=did:theprotocol:example CLIENT_ID=example CLIENT_SECRET=example-secret-of-32-characters-x \
  tp-proxy run local.yaml --dry-run --once --no-service

Four of the five rows are awarded and four attestations would be sent; the revoked row is left out.

Two things the recipes taught. TheProtocol's webhooks are the owner's, not the agent's: an owner with several agents receives every agent's payments, so a mapping that acts on payment.received or payment.settled names its own agent in its when (BAZAAR, TRUNK). And a journal books what settled, never what was only asked for: TRUNK's first version booked every rated row, and the sandbox drive showed a payment the proxy had refused (over max_amount) booked as a debit all the same. It now books from payment.settled.

Server components AGPL-3.0-or-later · SDKs and the auditor Apache-2.0 · this documentation CC BY 4.0. If a doc and the running stack disagree, trust the stack. Legal notice (Impressum) · Privacy · Terms