Ekamyth Agent OS docs
Standard OS / Processes

hero status

Checks that Ekamyth Agent OS is installed, active and connected to your agents, and names one next step when something's wrong.

What hero status does

It answers one question: is Agent OS set up and healthy on this machine, and if not, what do I do next? It runs eight checks in a fixed order, prints a ✓ or ✗ for each, and names the one step to take.

Synopsis for hero status

hero status [--details] [--json]
hero status --help

-h, hero status help and hero help status print the same help.

Subcommands of hero status

None. hero status takes no subcommand. The commands that used to sit under it are under hero codify, and a word after status is refused with a pointer there.

Arguments for hero status

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
--detailsFlagNoOffAdds an evidence: block under the table, with one line per check showing what it found: paths, ports and sizes. Ignored with --json, which always carries this detail.
--jsonFlagNoOffPrints one JSON object instead of the table. See Example 2.
--help, -hFlagNoOffPrints the help. It works only as the only argument.

How hero status checks your install

Each check reads the current state from the part of Agent OS that owns it, every time you run the command. If one check can't run, it shows could not be checked, and the other seven still run.

CheckWhat it asks
installWhich version is installed. It's always ✓.
accessIs this machine active?
proxyDoes the model gateway your agents use answer, and does it belong to this install?
agentsAre Claude Code and Codex installed, and are their settings pointed at the model gateway?
hooksAre the Agent OS hooks in each agent, and has Codex approved them?
enforcementCan one of your rules block a tool call right now?
storesCan Agent OS read its own data on this machine, and is any of it damaged?
diskIs there at least 5 GB free where Agent OS keeps its data?

Under the table, a rules line counts your registered rules and how many block. Then it prints one next step: the step of the first ✗ check, in table order. The proxy check makes one request to the model gateway on your machine. It doesn't make a model call, so a ✓ doesn't test your provider credentials. The agents check reads your agents' settings; it doesn't watch a running session.

Get started with hero status

Before you start: Agent OS is installed. Nothing here changes anything, so there's nothing to undo.

  1. Run the eight checks.

    hero status

    On a connected machine you should see 8 checks · all ok, and it exits 0. Otherwise you see which checks need attention, and a next: line.

  2. If there's a next: line, run that command, then run hero status again.

    Each fix can reveal the next ✗. Repeat until all eight are ✓.

  3. See what each check found.

    hero status --details

    You should see the same table, then an evidence: line per check.

Example output of hero status

Before setup

Output from version 0.1.36rc13. Trimmed where you see …

On a connected machine

Output from version 0.1.36rc13. Trimmed where you see …

status — Ekamyth on this machine
  8 checks · all ok
  ┌───┬───────────────┬────────────────────────────────────────────────────┐
  │   │ check         │ state                                              │
  ├───┼───────────────┼────────────────────────────────────────────────────┤
  │ ✓ │ install       │ ekamyth 0.1.36rc13 (build 1c14e25f63a7)            │
  │ ✓ │ access        │ active                                             │
  │ ✓ │ proxy         │ running                                            │
  │ ✓ │ agents        │ Claude Code, Codex route through the proxy         │
  │ ✓ │ hooks         │ installed and approved                             │
  │ ✓ │ enforcement   │ armed                                              │
  │ ✓ │ stores        │ readable                                           │
  │ ✓ │ disk          │ enough free space · stores within limits           │
  └───┴───────────────┴────────────────────────────────────────────────────┘
  rules  0 registered · 0 blocked
  paths, ports and sizes: hero status --details

How to read hero status output

LineWhat it meansWhat a ✗ can say, and the next step
1. TitleFixed text.
2. SummaryHow many checks passed, and how many need attention. 8 checks · all ok when every check passes and every registered rule blocks. 8 checks ok · <m> of <n> rules blocked when checks pass but some rules don't block.Follow the next: line.
3. installThe installed version. Same as hero version.Always ✓.
4. accessWhether this machine is active. Until it is, nothing is connected.not active on this machine: hero setup. See Activation.
5. proxyWhether the model gateway your agents use answers, and belongs to this install.not running: hero proxy --install-service && hero setup. your agents' proxy is not answering: hero proxy --port <port>. another Ekamyth install answers on its port or something that is not the proxy answers on its port: hero status --details. running · upstream failing for <model>: your provider is failing for that model. not checked — your agents' proxy is remote: check the model gateway at the address it names.
6. agentsWhich agents are installed, and whether each one's settings point at the model gateway.<names> not routed through the proxy: hero setup. no Claude Code or Codex found: install one, then run hero setup.
7. hooksWhether each agent has the Agent OS hooks, and Codex has approved them.not installed: hero setup. Codex hooks not approved yet: approve them in Codex's hook review, or run hero setup again once Codex runs. If Codex's hooks feature is off, the step is codex features enable hooks.
8. enforcementWhether your rules can block a tool call now.not armed — no rule can block a tool call: hero codify enforce on. turned off by <VAR>=<value>: an environment setting turned it off. The step unsets it.
9. storesWhether Agent OS can read its own data. nothing recorded yet is normal before your first session.The state names what can't be read, and the step says how to fix it, such as a chmod command. Status never runs it for you.
10. diskWhether at least 5 GB is free where Agent OS keeps its data.less than 5 GB free: free at least 5 GB on that disk.
11. rulesHow many rules are registered, and how many of them block. rules cannot be read when the count can't be read.When every check passes but a rule doesn't block, the next step is hero codify.
12. next:The one step to take: the first ✗ check's. It's absent when nothing is due.Run it, then run hero status again.
13. Last lineWhere to see the evidence.hero status --details.

More hero status examples

Example 1. To see the evidence behind each check

hero status --details

It prints the same table, then one evidence: line per check: the version's location, the model gateway's address and what answered there, each agent's settings file and value, the hook counts such as wired 5/5, the enforcement switches and the free space. The evidence holds full paths and ports, so remove them before you paste it anywhere public.

Example 2. To use the checks in a script

hero status --json

Example output. The format is the command's; the numbers are examples.

Excerpt: detail values and later checks cut with ….

{"schema": "hero.status.v1", "checks": [{"id": "install", "ok": true, "state": "ekamyth 0.1.36rc13", "detail": "…"}, {"id": "access", "ok": false, "state": "not active on this machine", "detail": "…"}, …], "rules": {"registered": 0, "blocked": 0}, "next_step": "hero setup", "exit_code": 1}
FieldMeaning
schemaAlways hero.status.v1.
checksEight objects, in table order.
checks[].idinstall, access, proxy, agents, hooks, enforcement, stores or disk.
checks[].oktrue for a pass, and also for a store that wasn't checked. Read state to tell them apart.
checks[].stateThe text in the table.
checks[].detailThe --details evidence line. It holds full paths and ports.
rules.registered, rules.blockedThe rule counts, or null when they can't be read.
next_stepThe one next step, or null.
exit_codeThe exit code: 0 or 1.

In a script, read exit_code or checks. Exit code 1 means something needs attention, not that the command failed.

Example 3. To see why enforcement reads off

HERO_CODIFY_ENFORCE=0 hero status | grep enforcement

Example output. The format is the command's; the numbers are examples.

  │ ✗ │ enforcement   │ turned off by HERO_CODIFY_ENFORCE=0                │

The state names the setting that turned enforcement off. The next step is unset HERO_CODIFY_ENFORCE.

Exit codes and errors for hero status

CodeMeaningWhat to do
0Every check passed, and the rule counts could be read. Also help.Nothing.
1A check needs attention, or the rule counts can't be read. The full report is still printed.Run the next: step.
2Refused: a word or option hero status doesn't take.Use only --details and --json.

A refused word, for example hero status list:

refused        status has no verb 'list'
reason         unknown_verb
governing_rule hero status takes no verb — the rule dashboard's verbs belong to hero codify
remedy         hero codify list

A refused option, for example hero status --bogus:

refused        status has no flag '--bogus'
reason         unknown_flag
governing_rule hero status takes no verb and only the flags --details, --json
remedy         hero status --help

With --json, a refusal is one object with refused, reason, governing_rule and remedy.

Files and environment for hero status

Status changes none of your settings. It can send the anonymous usage beacon: a random installation id, the version, the platform and the event. 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.

NameKindPurpose
~/.claude/settings.jsonYour Claude Code settings, readThe agents and hooks checks.
~/.codex/config.toml, ~/.codex/hooks.jsonYour Codex settings, readThe agents and hooks checks.
HERO_HOMEEnvironment variableWhere Agent OS keeps its data. Default ~/.hero.
HERO_PROXY_PORTEnvironment variableThe model gateway port checked when setup recorded none.
HERO_CODIFY_ENFORCEEnvironment variable0, off, false or no turns enforcement off, and the enforcement row says so.
HERO_BEACON=offEnvironment variableTurns off the anonymous usage beacon, which hero status can send.

Limits of hero status

LimitBehaviourCan you change it?What to do
Exit code before setupUntil hero setup and the model gateway have run, several checks are ✗ and the exit code is 1.NoIn scripts, read exit_code and checks from --json.
One step at a timenext: names only the first ✗ check's step.NoRun it and check again, or read --details.
CredentialsThe proxy check doesn't make a model call, so it doesn't test your key or sign-in.NoUse your agent, then check hero efficiency for recorded calls.
A model gateway on another machineIt isn't checked. The proxy row reads not checked, and the exit code is 1.NoCheck that model gateway where it runs.
AgentsOnly Claude Code and Codex are checked.NoNone.
Helphero status --help prints a one-line summary, and works only as the only argument.NoUse this page.
Paths in the output--details and --json include full paths and ports.NoRemove them before you share the output.
Table widthThe state something that is not the proxy answers on its port is one character wider than its column, so that row's border shifts.NoNone.

Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.