hero contract
Prints the data contract that ships with Ekamyth Agent OS: every flow Agent OS may send off your machine, where it goes, what it carries, and how it's switched on or off.
What hero contract does
It answers one question: what is Agent OS allowed to send, and to where? It prints the contract file installed with this version, flow by flow. It shows what the contract declares, not what your install sent or has switched on. For that, run hero privacy, which reads the same declared list and adds what is on in your environment and what its egress guard recorded as sent.
- Use it when a security reviewer asks for the full list of outbound flows, or you want the contract as JSON for a review tool.
- Use something else when you want what is switched on and what left (
hero privacy), or the product-level picture (How Privacy works). - In help:
hero helpdoesn't listhero contract. See Limits. - Reads or changes: reads the installed contract file and changes none of your settings. Like other
herocommands, it can send the daily usage beacon unlessHERO_BEACON=offis set.
Synopsis for hero contract
hero contract [--json]
hero contract --help
A word after contract is refused as an unknown subcommand. Flags other than --json and --help have no effect.
Subcommands of hero contract
None.
Arguments for hero contract
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--json | Flag | No | Off | None | Prints the whole contract as JSON. |
How hero contract gets its answer
The contract is a file installed with Agent OS. hero contract finds it in the installed package, reads it, and prints it. Nothing on your machine changes the contract, and what hero contract prints doesn't depend on your environment, so the same version prints the same contract everywhere. Whether each flow is on for you depends on your environment and your actions; hero privacy shows that.
Get started with hero contract
Before you start: Agent OS is installed. These commands work the same on Mac and Linux.
Print the contract.
hero contractYou should see
hero data contract v<version>, thenoutbound flows (<n>):with each flow, thennever sent:, a retention section, andfull path:with where the file is installed.Save it as JSON for a review.
This command will:
- write
contract.jsonin the current folder, or replace it if it exists.
hero contract --json > contract.jsonThis prints nothing. The file holds the contract's keys:
contract_version,plugin,summary,egress,neverandretention. To undo, delete the file:rm contract.json.- write
Compare with what's on in your environment.
hero privacy
How to read hero contract output
One flow
Each flow takes three lines: its id, whether it is required or opt-out, and its destination; then how it's switched on or off; then what it carries.
| Second line | What it means |
|---|---|
user-triggered — <when it sends> | The flow sends when you take the step the line names. The rest of the line is the contract's own wording for that flow. |
required — no opt-out (content-free metadata only) | The contract marks the flow as required. |
opt-in — disabled by default | Off unless you configure it. The line names the setting. |
opt-out: <how> | On unless you switch it off as the line says, or on only in the condition it names. |
The flows this version declares
Version 1.5 of the contract, as installed with this version, declares 11 flows. All of them go to Ekamyth. They're the same 11 flows hero privacy lists.
| Flow | What the contract says it carries | How the contract says it's switched |
|---|---|---|
usage-beacon | An anonymous install heartbeat: a random install id, version, platform and event, only when Agent OS runs. | Usage reporting is on by default. It sends metadata only — never content, prompts or responses — at most once a day. Turn it off with HERO_BEACON=off. |
learned-routing-plan-check | This install's random installation id, to ask whether your plan includes learned routing. No content. | HERO_LEARNED_ROUTING=off turns it off. |
learned-routing-pull | This install's random installation id, to download the learned routing policy your plan includes. No content. | HERO_LEARNED_ROUTING=off turns it off. |
preview-enrolment | The email address you type at hero setup's access request, sent once. | Only when you type an address. |
preview-redeem | The handoff id, the one-time code you were given, and this install's random installation id. | Only when you redeem a code. |
rule-compile | A rule template, with its literal values kept on your machine. | Sent when you run hero compile, hero promote or hero analyze --llm. Sending in the background is off by default; hero codify-policy auto on turns it on. Never sent without an Ekamyth key. See Limits. |
attest-anchor | A batch's hash and counts, which prove decisions existed without revealing any. | Off by default on this build. See Limits. |
decision-metadata, usage-metrics, d6_aggregates | Anonymized decision metadata, aggregate token counts, and hourly token and verdict rollups. | Off unless configured. The printed line names the setting. |
policy-pull | Downloads the current policy version: enforcement rules, not runtime data. | Off unless configured. The printed line names the setting. |
The other sections
| Section | What it holds |
|---|---|
never sent: | What the contract says Agent OS never sends. |
retention: | Not covered by this documentation. It names a backup command this build doesn't include. See Limits. |
full path: | Where the contract file is installed. |
More hero contract examples
Example 1. To list just the flow ids and destinations
hero contract --json | python3 -c 'import json,sys; [print(f["id"], f["destination"]) for f in json.load(sys.stdin)["egress"]]'
This prints one line per flow: its id and its destination address.
Example 2. To check which contract version is installed
hero contract | head -1
This prints hero data contract v<version>.
Exit codes and errors for hero contract
| Code | Meaning for this command | Cause | What to do |
|---|---|---|---|
0 | The contract printed | The file was found and read. | Nothing. |
1 | The contract file is missing | The installed package has no contract file. | Reinstall Agent OS. See Install, upgrade and remove. |
2 | Refused | A word after contract. | Run hero contract with no subcommand. |
| Error | Cause | Fix |
|---|---|---|
hero.contract.json not found — is this a complete install? | The contract file isn't in the installed package. Exit 1. | Reinstall Agent OS. |
contract has no verb '<word>', with the rule hero contract declares no verbs — it takes flags only | A word after contract. Exit 2. | Run hero contract, as the remedy line says: hero contract --help. |
Files and environment for hero contract
| Name | Kind | Purpose |
|---|---|---|
| The contract file | File in the installed package, read only | The declared flows. hero contract prints its path on the last line. |
What hero contract prints doesn't depend on any environment variable. HERO_BEACON=off stops the usage beacon it can send, as for other hero commands. The variables the contract names are described in What you can change in Privacy.
Limits of hero contract
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Declared, not actual | It prints what the contract declares. It doesn't show which flows are on in your environment, or what was sent. | No | Run hero privacy. |
| Not in help | hero help doesn't list hero contract. | No | Use this page. |
| Retention section | It points to a backup command that this build doesn't include. | No | This page makes no statement about how long anything is kept. |
| Witness flow | The contract names attest-anchor, which its help calls the attest witness: a flow to an independent witness, with an off switch. That flow is off by default on this build. | No | hero privacy shows it as off. See hero attest limits. |
| Rule compile flow | rule-compile sends when you run hero compile, hero promote or hero analyze --llm. After a person runs hero codify-policy auto on, it also sends in the background, when a rule is added or changed and at the daily rule check. | Yes: hero codify-policy auto paused | See hero codify-policy auto. |
| Agent OS's own sends only | The contract covers what Agent OS sends. Your agent's model calls go to your own provider, and other traffic on your machine isn't covered. | No | See What stays on your machine. |
Commands related to hero contract
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.