Ekamyth Agent OS docs
Agent OS documentation / Troubleshooting

Troubleshoot Ekamyth Agent OS

Find what you're seeing, read its cause, and apply the fix. Start with hero status: it checks the install and names one next step. If your agent's call was refused or held, go to Rules and holds.

Start with hero status

When something isn't working, run these in your own terminal, in this order:

# Is Agent OS installed, active and connected? Names one next step.
hero status

# Is each agent connected?
hero setup --check

# Is the Brain healthy?
hero brain doctor

hero status runs eight checks, prints a ✓ or ✗ for each, and ends with a next: line naming the step for the first ✗ check. Run that step, then run hero status again. It only reads: it never runs the step it prints. For each line, see How to read hero status output.

To ask for help, run hero support and tell support the code it prints, with the output you saw. Email it to support@ekamyth.com.

Installing

What you seeCauseFix
On Linux, run the install command with bash instead of sh: replace the leading 'sh -c' with 'bash -c'.The install line was started with sh -c on Linux.Replace sh -c with bash -c and run it again. Your install command still works within its 60 minutes.
Ekamyth runs on macOS and Linux. It does not run on this system yet.The system isn't Mac or Linux.Use a Mac or Linux machine. To ask for another system, write to support@ekamyth.com.
could not fetch the Ekamyth install scriptThe download failed or the link expired.Check your network, then copy a new command from your account page.
sha256 MISMATCH ... nothing installedThe package doesn't match its digest.Don't install it, and don't retry it. Email support@ekamyth.com with the file name and the sha256 you got.
no compatible Python 3.10+ was installed ...No Python 3.10 or newer, and none was installed.Install Python 3.10 or newer, then run the line it prints.
declined ... nothing installed.You declined the dependency question.Review the list it names, then run the install line again.
NOT activated — the install token was not redeemed (the reason is above); install commands work once, for 60 minutes: get a new one at ekamyth.ai/accountThe install command was already used, expired or was refused. It works once, for 60 minutes.Get a new install command from your account page.

To confirm the fix: the installer's closing report shows yes on configured, services and reachable, and hero status shows 8 checks · all ok. See Exit codes and errors for the install line.

Connecting your agents

What you seeCauseFix
hero setup: not applied — there is no terminal to confirm the plan above, so nothing was changed.Setup ran with no terminal to ask on.Run hero setup in a terminal, or with --yes.
NOT written: proxy not reachable, for that agentThe model gateway didn't answer, so setup left that agent's model route alone. The agent keeps reaching its provider directly.Start the model gateway with hero proxy --install-service, then run hero setup again.
Ekamyth is installed but not active on this machine yet. Your agents are unchanged.This machine isn't active. Until it is, nothing is connected. Running hero setup again doesn't activate it.Run a new install command from your account page, or hero setup redeem <install-id>.
An agent's model calls don't show in Agent OS, and hero route census shows it isn't routed.Claude Code was started with its own model address, so its model calls go straight to the provider. Agent OS still sees its tool calls, but doesn't route or meter its model calls. Or your Codex settings name your own provider, so Codex's model calls aren't routed through Agent OS; Agent OS still watches its tool calls.Claude Code: start it with hero claude (or hero run claude). Codex: set the active Responses provider's base_url to your model gateway address plus /v1, and remove conflicting profile or command-line routing overrides. hero codex preserves your own provider settings.
A refusal that says "a governed agent cannot switch off its own rules"Your agent ran hero setup --undo, revoke-codex, or a setup that re-points the hooks. Only you can run them.Run it yourself, in your own terminal.
hero setup exits 2 after connecting your agentsPartly applied: your agents are connected, but a later step failed, such as your agent's identity, or Agent OS's data folder isn't writable.Read the line it names. hero setup --undo takes back what was wired.
hero setup exits 3Setup failed with an unexpected error.Run hero support and email the code it prints, with the output you saw, to support@ekamyth.com.

To confirm the fix, run hero setup --check. See Exit codes and errors for hero setup.

The model gateway

The proxy row of hero status is the health check for the model gateway.

What you seeCauseFix
hero status, proxy row: not runningThe model gateway isn't running.hero proxy --install-service && hero setup
proxy row: your agents' proxy is not answeringNothing answers at the address your agents use.hero proxy --port <port>
proxy row: another Ekamyth install answers on its port, or something that is not the proxy answers on its portSomething other than this install's model gateway holds the port.Run hero status --details to see what answers.
proxy row: running · upstream failing for <model>Your provider is failing for that model.Email support@ekamyth.com with the output you saw.
proxy row: not checked, with your agents' model gateway on another machinehero status doesn't check a model gateway on another machine.Check that model gateway where it runs.
hero proxy --service-status says not readyThe line can say not ready when no Codex session is open, even when the model gateway works.Use hero status and its proxy row as the health check.
hero proxy --service-status says not installed while the model gateway runs in a terminal--service-status reports the background service only.Check the model gateway with hero status.
Your prompt isn't sent, and the message names a command that starts the model gatewayThe model gateway is down. A connected agent's model calls fail until it's back.Run the command the message names.
hero route prints routing enabled, but this install's Runtime is not answeringThe model gateway isn't answering.Read the proxy row of hero status, and run its step.
hero proxy: port 8081 is already in use ... is another hero proxy running?Something that isn't this install's model gateway holds the port.Run the check: command it prints, or pick another port with hero proxy --port <port>.
hero proxy: hero proxy refusing to start without a provider API key; ...The machine isn't active, and no provider key is set.Activate this machine, so the model gateway uses your agent's own sign-in, or set a provider key.
hero proxy: install-service failed ... Ekamyth is not active on this machine yetThis machine isn't active.Activate it with hero setup redeem <install-id>, or run the install command from your account page.
... refusing to touch the per-user service 'hero-proxy.service' from a foreign HOME.HOME isn't your account's real home. The service is registered per user.Run it with your normal HOME.
hero health exits 1 with a finding that the model gateway isn't answeringIt's a high finding when Claude Code or Codex is installed, or after hero setup.Start the model gateway with the command in the finding's fix column.

To confirm the fix: hero status shows the proxy row as ✓. See Exit codes and errors for hero proxy.

Agents, hooks and enforcement

What you see in hero statusCauseFix
agents: <names> not routed through the proxyThat agent's settings don't point at the model gateway.hero setup
agents: no Claude Code or Codex foundNeither agent is installed.Install one, then run hero setup.
hooks: not installedThe agent doesn't have the Agent OS hooks.hero setup
hooks: Codex hooks not approved yetCodex runs a hook only once it's approved.Approve them in Codex's hook review, or run hero setup again once Codex runs.
hooks: the step codex features enable hooksCodex's hooks feature is off, so Codex runs no hook at all.codex features enable hooks
Every Codex tool call is refused with Ekamyth could not check this action, so it refused it: <reason> [<code>]. Run: hero setup --checkCodex's tool-call hook couldn't get an answer from Agent OS: the hero program is missing or failed, gave no decision, or didn't answer within 120 seconds. Codex refuses the call rather than run it unchecked.Run hero setup --check and follow it. If you removed Agent OS without the uninstall command, run the uninstall command, which takes this hook out.
enforcement: not armed ... no rule can block a tool callEnforcement of your rules isn't on: your rules are checked at the tool call but don't block.hero codify enforce on
enforcement: turned off by <VAR>=<value>An environment setting turned enforcement off.Unset that variable. The next: line names it.
stores: names what can't be readAgent OS can't read its own data.Run the step it names, such as a chmod command.
disk: less than 5 GB freeLess than 5 GB is free where Agent OS keeps its data.Free at least 5 GB on that disk.

To confirm the fix, run hero status again. After a change to an agent's settings, restart Claude Code and Codex, or open new sessions.

Rules and holds

What you seeCauseFix
Your agent's call was refused, and you don't know whyA rule from your rules file (once enforcement is on), an always-refused shape, a credential read, or Agent OS's self-protection stopped it.Read the refusal your agent got: a rule's refusal starts hero: tool call denied (user_rule: <id>) and names the rule. Then run hero enforce show <id>. hero govern lists recent refusals and why.
hero init shows a rule as BROKENStates depend on the folder you run it from. Run from outside a project, that project's rules read BROKEN. Broken — no seam is different: it marks a judgment rule. See the next row.Run hero init from the project's folder.
A rule reads Not enforced yet, and a matching call runsThe rule isn't written in one of the seven shapes Agent OS checks as code at the tool call, so it's a judgment rule. Not enforced yet means no code check, which is how judgment rules work: Agent OS's memory puts the ones that apply in your agent's context, as guidance.Reword it into one of the shapes, such as "Never push to main.", then run hero init. See Rules checked as code.
A rule is refused on Claude Code but not on CodexOn Codex, rules are checked as code for shell commands only, and refused there once enforcement is on.Treat Codex rule checks as covering shell commands only.
A dangerous command is refused, whatever your rules sayIt matches one of the eleven always-refused shapes. Nothing in Agent OS approves them.To run it, type it yourself in your own terminal. See Always refused.
An ordinary shell command is refused, and the refusal says Agent OS couldn't read itAgent OS couldn't fully read the command, and refuses what it can't read.Run that command yourself in your own terminal.
A harmless command is held or refused, such as a search for the text rm -rfThe command mentions a dangerous one, and Agent OS reads the mention as the command.Approve it in hero inbox, or rephrase it.
A simple read-only command, such as ls or pwd, is held for your approvalA known issue in this version.Approve it in hero inbox.
A rule you wrote doesn't appear in hero enforceIt's worded "Under no circumstances ..." or "You must never ...", or it was found by hero setup and not registered. Rules in your user-level ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md aren't enforced yet.Start the rule with Never or Always, put it in the project's rules file, and run hero init CLAUDE.md (or the file you use).
A "Never change files under <folder>" rule shows as enforced as code, but blocks nothingThe rule ends with a period after the folder name, which binds it to the wrong folder.Remove the period, as in - Never change files under docs/legal, then run hero init.
Every tool call is refused, with a message that every tool call is denied until the rules can be readAgent OS can't read your registered rules, so it refuses tool calls until it can, whether or not enforcement is on.Follow the fix the message names.
YOUR POLICY FILE IS BROKENYour policy file is damaged. Ordinary calls run; only the always-refused shapes are still refused.Run hero govern, which names the repair.
Your agent says its call was refused, with a hold's idA send, post or delete through a connected tool is held for your decision.Approve or deny it with hero inbox, from your own terminal. After you approve, your agent has to make the same call again within 15 minutes.
A hold is no longer in hero inboxHolds you don't decide are denied 24 hours after the hold.Decide holds within 24 hours.
Your agent's attempt to approve a hold is refusedApproving is human-only.Approve it yourself, in your own terminal.
hero inbox approve or deny is refused in a scriptThey're refused with no terminal.Decide holds yourself, in a terminal.

To see a rule's state, run hero enforce and read its agent columns.

The Brain and context

A problem here never stops a session from starting. The block that failed says so in place of its content.

What you seeCauseFix
Ekamyth Brain: memory could not be loaded (<reason>).A Brain file can't be read, isn't valid text, or is too large. The session starts without session memory.Run hero brain doctor.
No memory yet:The Brain is empty.Add a line to the file it names, or add a fact with hero brain note.
Brain: not kept (too_long)A fact is at most 600 characters and 3 lines.Split it into shorter facts.
hero brain doctor lists a missing pinned fileA pinned file is missing. Session memory loads what exists.Follow the next step hero brain doctor prints.
Thread commands refuse with identity_not_enrolledNo agent identity is enrolled. Session memory still loads.Run hero setup. It gives your agent one identity across Claude Code and Codex. To check, run hero identity status, which shows Enrolled — agent id ….
Ekamyth rules: registered rules could not be loaded (registry_unreadable).Your registered rules can't be read. The session starts without your rules in context.Email support@ekamyth.com with the output you saw.
Ekamyth rules: injection receipt could not be written (receipt_write_failed).The session starts with your rules and without session memory.Email support@ekamyth.com with the output you saw.

For the MCP wrapper, see When something goes wrong with MCP.

Routing, efficiency and observe

What you seeCauseFix
hero efficiency refuses with exit code 2, about your rates fileThe file HERO_BILLING_RATES names isn't valid JSON.Fix the file, or unset the variable. Check a file first with hero efficiency billing <path>.
hero trace refuses with exit code 3, saying the history is larger than it can read at onceYour trace history passed 64 MB. New sessions are still recorded.New sessions are still recorded. There is no supported fix for the size on this build. See Limits of hero trace.
hero trace says the record is present but cannot be read, exit code 3The session record is damaged.Email support@ekamyth.com with the output you saw.
A failed session points you to hero trace violations, which finds nothingviolations lists policy violations only, not failed steps.Replay the session with hero trace show <id>.
hero schedule run marks a job ✗ and exits 1That standing job failed. The other jobs still run.Read its first line of output, and run the job's own command, such as hero health.

Upgrading

What you seeCauseFix
the new install was removed and the active install was NOT switched; nothing changedThe new version didn't answer its check. Your previous version is still the active one, so your agents keep working.Run hero support and email the code it prints, with the installer's output, to support@ekamyth.com.
install NOT complete ... re-run: hero setup --proxy <url>The new version is active, but setup didn't finish. Older versions are kept until it does.Run the re-run: command. If it fails again, roll back.
the proxy service was installed but did not answer <url>/healthz within 30sThe model gateway didn't answer in time, so setup doesn't point your agents at it.Run hero status and read its proxy row. When it shows running, run the hero setup --proxy <url> command the warning prints.
A services line in the closing report that isn't yesA background service didn't start.Run the start manually: command it names.
After a rollback, the model gateway runs the newer versionSwitching your hero command back doesn't move a running model gateway.Run hero proxy --install-service.

To confirm an upgrade worked: hero version prints the new version, and hero status shows 8 checks · all ok. See To upgrade to a new version. If your agents misbehave after an upgrade, roll back, then tell support.

Undoing and removing

What you seeCauseFix
hero setup --undo is refused when your agent runs itOnly you can undo setup, from your own terminal.Run it yourself.
After hero setup --undo, setup says this machine isn't activeUndo also drops this machine's activation.Get a new install command from your account page.
Undo reports a model route, hook or slash command it left in placeUndo leaves a model route you repointed, a hook you wrapped and a slash command you edited.Remove those by hand if you want them gone.
Your agents can't reach their provider after you removed Agent OSAgent OS was removed some other way than the uninstall command, so hero setup --undo didn't run, and your agents still point at a model gateway that's gone.Remove Agent OS with curl -fsSL https://install.ekamyth.ai/uninstall.sh | sh, which runs hero setup --undo before it removes anything. If the hero command is already gone, email support@ekamyth.com with the output you saw.

See To remove Agent OS.

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