Ekamyth Agent OS docs
Agent OS documentation / FAQ

Ekamyth Agent OS FAQ

Answers to common questions: what Agent OS is, what each area does, and how it compares.

What Agent OS is

What is Agent OS?

Agent OS is the operating system layer for AI agents. It works with the agents you already use, Claude Code and Codex, on Mac and Linux, and it runs on your machine. It gives them rules checked as code, a Brain, model routing, efficiency across the whole of the work, a record you can read, and MCP. See How Agent OS works.

Do I need to replace my agent?

No. Agent OS works inside Claude Code and Codex. hero setup connects the agents it finds on your machine after showing you its plan, and hero setup --undo takes Agent OS back out. See How Agent OS connects.

Does Agent OS replace my model provider?

No. Your agent's model calls go to the provider you already use, with your own key or your agent's own sign-in. The model gateway passes each call through on your machine and returns the answer to your agent.

Which agents does it work with?

Claude Code and Codex. hero setup connects both. Gemini CLI isn't connected. Codex's end-of-turn hook needs Codex 0.114.0 or later.

Is Agent OS a sandbox?

No. Agent OS checks the tool calls that reach its hooks. It sees the command that starts a script or program, not what the program does after it starts, so a script can call a service directly. The always-refused list catches the plain forms of dangerous commands; indirect forms, such as a script written and then run, or a dangerous command on its own line after a harmless one, aren't caught yet. It isn't a sandbox. Agent OS doesn't block other network traffic on your machine. See What each connection covers.

Is Agent OS a governance tool or an observability tool?

Both are areas of Agent OS, and neither is the whole of it. Agent OS also keeps a Brain, routes model calls, looks for waste across the work, and works with your MCP servers. This documentation is organized by those areas; see Documentation by area.

Does Agent OS work offline?

Rules that run as code, routing choices and the local record work offline. The model call itself needs the network, unless you route to a local model (Ollama).

Get started

Which operating systems does it run on?

Mac and Linux. You need curl and Python 3.10 or newer, and you don't need sudo; if you don't have Python, the installer offers to add a private copy. On Linux, start the install line with bash -c. On Linux, the background services can stop when you log out; see Limits. See Get started.

How do I upgrade?

Get a new install command from your account page and run it, as you did to install. It installs the new version beside the one you have, checks that it answers before switching to it, keeps your previous version for one rollback, and runs hero setup again. Then check with hero version and hero status. Your rules and records are kept. See To upgrade to a new version, and Troubleshooting if it fails.

How do I remove Agent OS?

Run the uninstall command in your own terminal:

curl -fsSL https://install.ekamyth.ai/uninstall.sh | sh

It runs hero setup --undo before it removes anything, so your agents aren't left pointing at a model gateway that's gone, then removes the background services and the package, and checks the result. Undo also drops this machine's activation, so a later install needs a new install command. Your data in ~/.hero stays until you delete it. See To remove Agent OS.

Where do I see my plan?

No hero command names your plan. Your account page, ekamyth.ai/account, shows it. Where a plan matters to a feature, that feature's page says so.

Where do I get the install command, and what are the install id and secret code?

Sign in at ekamyth.ai/account and choose Get an install command. The command carries your install token, and works once, for 60 minutes. The install token is an install id and a secret code joined by a dot: the part before the dot is the install id. If activation didn't happen during the install, run hero setup redeem <install-id>; it asks for the secret code at a prompt, and never takes it as an argument. Or get a new install command and run it. See Step 1. Install Agent OS, and activating with an install id.

What happens if I run hero setup before this machine is active?

On a machine that isn't active, hero setup exits 1. In a terminal, it asks for your email address when its activation service is configured, sends it only if you enter one, and leaves your agents unchanged until activation. To activate, run hero setup redeem <install-id> with the install id from your install command, or run a new install command from your account page. See What hero setup does.

What does hero setup change in my agents, and does it ask first?

It points your agents' model calls at the model gateway (only where the gateway answers), gives your agent one identity across Claude Code and Codex, sets the default governance posture with rule enforcement armed, adds Agent OS hooks to each agent (5 in Claude Code, and 6 in Codex 0.114.0 or later; 5 in earlier versions), reads the rules in this project's CLAUDE.md, AGENTS.md and memory files and your user-level rule files, and lists them in hero enforce, sets up a daily background job that reads them again, and installs 12 slash commands in Claude Code and 12 skills in Codex. It prints its plan for each agent and asks. With no terminal to ask on, it changes nothing unless you pass --yes. It keeps a copy of each settings file beside it before changing it. See How hero setup connects your agents.

Do I restart my open sessions after setup?

Yes. Restart Claude Code and Codex, or open new sessions. Sessions that were already open don't pick up the connection. See Step 5. Try it in a new session.

Can I connect only one agent?

Setup connects the agents it finds on your machine, prints its plan for each agent and asks before it changes anything. hero setup is also the command to use when you add Codex or Claude Code later. To see which agents are connected now, run hero setup --check. See What hero setup does.

What if hero setup fails?

Run hero status; it names one next step. If the model gateway didn't answer, setup leaves that agent's model route alone, still installs the hooks and slash commands, and exits 1. Start the model gateway with hero proxy --install-service, then run hero setup again. See Connecting your agents.

Connect

How does Agent OS connect to my agent?

In two places, both on your machine. The model gateway is where your agent's model calls go on the way to your provider. The hooks are a feature of Claude Code and Codex: at set moments, such as before a tool call, the agent calls Agent OS and waits for its answer. hero setup makes both connections. See How Agent OS connects.

What does the model gateway carry?

Model calls only. Your agent's tools, such as shell commands and file edits, reach Agent OS through the hooks. A web search your provider runs on its own side reaches neither. See What each connection covers.

How do I check that my agents are connected?

Run hero status. It runs eight checks, prints a ✓ or ✗ for each, and names the one step to take next. To see each agent's connection in detail, run hero setup --check. See hero status.

What commands can I run inside my agent?

hero setup installs 12 commands: slash commands in Claude Code, and skills of the same names in Codex, such as /hero:health and hero-health. They are health, enforce, codify, govern, attest, trace, efficiency, route, memory, eval, brain and identity. Each matches a hero command you can also run in a terminal, and /hero:codify is the older name for /hero:enforce. See The 12 commands.

What is the difference between hero status and hero health?

hero status asks whether Agent OS is set up and healthy on this machine. It runs eight checks and names the one step to take. hero health asks how your agents are doing overall, across Govern, Optimize, Assure and Ledger, with a fix for each finding. See hero status and hero health.

Why don't my agent's model calls show in Agent OS?

If Claude Code was started with its own model address, its model calls go straight to the provider. Agent OS still sees its tool calls, but doesn't route or meter its model calls. Start it with hero claude (or hero run claude). If your Codex settings name your own provider, Codex's model calls aren't routed through Agent OS. To see which agents reach the model gateway, run hero route census. See If your agent's calls don't reach Agent OS.

Security and enforcement

What does Agent OS stop on a new install?

From the first session:

Everything else runs and is recorded, except actions on your policy's dangerous list, which are still stopped. In a test that fed a recursive forced delete to the hooks of Claude Code and of Codex, the call was refused, and the refusal read reason unauthorized, governing_rule builder@v0 and remedy nothing approves this; the human runs it in their own terminal. This is the builder posture, which every install starts on. For what isn't caught, see Limits. See How Governance works.

Which of my rules are checked as code?

A rule in your rules file is checked as code at the tool call when it's written in one of seven shapes: a command, a push to a branch, a force push, committing file types, editing under a folder, running outside a folder, or a path. It blocks once enforcement is on. A rule in any other wording, such as "Keep replies short.", reaches the agent in context, as guidance, and isn't checked before a call. Start each standing rule with Never or Always: a rule worded "Under no circumstances ..." or "You must never ..." isn't saved. For a folder rule, leave out the period after the folder name, as in - Never change files under docs/legal; with the period, the rule is bound to the wrong folder and blocks nothing. hero enforce lists every rule and whether it's enforced on Claude Code and on Codex.

Can my agent switch off its own rules?

No. A governed agent can't turn rules off, approve its own holds, undo setup, or edit the files that hold its rules. You can, from your own terminal.

What happens when an action is held?

Your agent's call is refused with the hold's id, and the hold appears in hero inbox. You approve or deny it from your own terminal. After you approve, the agent has to make the same call again within 15 minutes. See hero inbox.

Does a tool I declare with hero govern add block a call?

No. hero govern add declares a tool's scope and stakes in your policy file; it isn't a deny rule. On the default posture, a matching ordinary call is observed and recorded, not stopped. To add a rule that's checked as code, write it in your rules file and run hero init; it blocks once enforcement is on. See hero govern.

Does my data come to Ekamyth?

Your prompts and your agent's responses go to your own model provider. What Agent OS itself is built to send to Ekamyth is a declared list, and none of the declared flows carries your prompts or your agent's responses. Some sends happen outside the declared list; see Limits. Run hero privacy to see the list, which flows are on, and the sends its egress guard recorded; four flows send without the guard, so they're never in that record. See How Privacy works.

Does Agent OS store my prompts and responses?

Agent OS's own record of each model call holds no prompt or response text. Your Brain holds the facts you ask it to remember.

Where are my provider credentials?

The model gateway passes each call to your provider with your own key or your agent's own sign-in. Agent OS doesn't pool sign-ins: each call goes out on the key or sign-in your agent sent. A provider key you add for Agent OS yourself is read from your machine's environment or from a keys file in your Agent OS folder.

How do I see why a call was refused?

Read the refusal your agent got. A rule's refusal starts hero: tool call denied (user_rule: <id>) and names the rule; run hero enforce show <id> for it. hero govern lists recent refusals and why. See Rules and holds.

What do I do when Agent OS refuses something I meant to do?

If the command matches one of the always-refused shapes, type it yourself in your own terminal. If Agent OS couldn't fully read an ordinary shell command, or held a harmless command that only mentions a dangerous one (such as a search for the text rm -rf), approve it in hero inbox, rephrase it, or run it yourself in your own terminal. If the call was held, approve or deny it with hero inbox, from your own terminal. See Rules and holds.

How do I see what Agent OS allowed, refused and held?

Run hero govern. It names your posture, then lists recent decisions with refusals and holds first. hero govern test tells you what the hook would do with one tool call, without making it. See hero govern.

Can I turn a rule off?

Yes, from your own terminal. hero codify off <rule> turns one rule off, and hero codify on <rule> turns it back on; find the rule's name with hero enforce. hero codify enforce on arms them so they block, and hero codify enforce off stops all your rules from refusing. The always-refused list stays on whichever you use. See Turn your rules off.

How do I stop every model call in a hurry?

Set HERO_KILL to 1, true or yes for the model gateway, and restart it. The model gateway then refuses every model call before it reaches your provider, and your agent gets HTTP 403 with an empty body. Unset it and restart to undo it. Tool calls your agent makes through its own tools are still checked by the hooks; this switch covers model calls. See Stop every model call.

How do I retire a rule?

An agent can add a rule. It can't change or retire one: hero init run inside an agent session keeps the old rule in place until you confirm the change yourself, from your own terminal. A known issue: a deleted rule line can stay active until you run hero codify off <rule>. See Limits of hero init.

How do I set a variable or a setting?

For one command, put the variable before the command, such as HERO_BEACON=off hero status. The model gateway, the scheduler and the Portal run as background services, and read their variables when they start. For your rules, edit your rules file and run hero init. See How to set a variable.

How do I see what Agent OS sends off my machine?

Run hero privacy. It lists every declared flow, where it goes, what it carries and whether it's on, then the sends its egress guard recorded. Four flows send without the guard and never appear there. hero privacy egress lists each recorded send, and hero privacy compliance shows how your latest agent session did against your rules. Your agent's model calls to your own provider aren't on the list. See hero privacy.

Can I turn off something Agent OS sends?

To turn off a flow that's on, use the setting in its when column in hero privacy. For example, HERO_BEACON=off turns off the anonymous usage heartbeat, which is on by default and sends metadata only, never content, prompts or responses, at most once a day. See How to read hero privacy output, and Environment variables.

Brain and context

What is the Brain?

What Agent OS keeps about you and your work, on your machine: who you are, the facts you've asked it to remember, your projects, and any threads of work saved there. You add a fact by starting a prompt with "Remember that ..." in Claude Code or Codex, or with hero brain note. When a session starts, Agent OS gives your agent the part that fits the current project, as context. See How the Brain works.

Is the Brain the same as my rules?

No. The Brain keeps facts, and your agent gets them as context, never as rules. A "Remember ..." prompt that reads as a rule, such as "Remember: never push to main", is treated as a rule and not kept in your Brain. Your rules reach a new session in their own block. In some projects the session-start rules block can be missing or incomplete. See How context loading works.

Do Claude Code and Codex share the Brain?

Yes. There's one Brain per install, and both agents use it.

Where is the Brain kept?

On your machine. Session memory is read locally. The step that gives it to your agent doesn't itself upload it to Ekamyth. Separately, compiling a rule can send a tokenized rule template to Ekamyth; hero privacy lists that flow. When Agent OS gives session memory to your agent, it becomes part of your agent's context, which your agent sends to your model provider under your own account.

How do I see what the Brain holds?

hero brain status shows each section of your Brain, its file and whether the file exists, and when session memory was last given to an agent. hero brain effective shows the Brain one agent draws from: which sections load, and which are left out and why. hero brain doctor looks for missing, unreadable and conflicting Brain files and gives the next step. See Subcommands of hero brain.

How do I add a fact to the Brain?

Start a prompt with "Remember that ..." in Claude Code or Codex, or run hero brain note --scope user --section memory --text <fact>. A fact is at most 600 characters and 3 lines. Agent OS keeps the fact and prints an undo id. It refuses secrets, rules, junk and text over the limit. See Get started with hero brain.

How do I take a fact out of the Brain?

Run hero brain undo <id> with the undo id Agent OS printed when it kept the fact. It takes back that line if the file still holds exactly what that keep wrote. You can also edit the Brain's files directly. See Subcommands of hero brain, and What you can change in the Brain.

How do I save a thread of work and resume it?

A thread is a named checkpoint of work in one workspace, with versions. With hero brain threads, create makes a thread, save saves a checkpoint as a new version, history lists its versions and resume loads one version for Claude Code or Codex. Nothing saves by itself, and resume brings back the checkpoint, not the conversation, your workspace files or your permissions. Every verb refuses with identity_not_enrolled until an agent identity is enrolled; hero setup enrolls one. See hero brain threads.

What does hero memory show?

It shows which of your registered rules Agent OS gave your agent at session start, and simulates which would fit a budget. The load audit is labelled as simulated on screen and doesn't change what your agent loads. In some projects the session-start rules block can be missing or incomplete. Run it inside your project. See hero memory.

MCP

Does Agent OS work with my MCP servers?

Yes, in two ways. By default, your agent's MCP tool calls reach Agent OS through its hooks, like its other tools: on Claude Code, and on Codex when the call reaches the hook. For a server you want checked call by call before it's reached, you set up the MCP wrapper, hero mcp wrap <server>, one server at a time. Agent OS also has its own MCP server, hero mcp. For its limits, see Limits. See How MCP works.

Is Agent OS an MCP SDK?

No. Agent OS doesn't provide an MCP SDK or a way to build MCP servers or agents. It provides an MCP wrapper that checks each call to one of your local MCP servers before it reaches that server, and a small MCP server of its own. See How MCP works.

Routing

Does Agent OS change the model my agent asked for?

It can. Routing is on after setup. Routing sends each kind of work to the least expensive model we expect to do it well, and it keeps learning from outcomes. Every call shows the model you asked for and the model that answered, so you can always see what happened. The call goes to your provider with your own key or sign-in, and hero route shows which model served each call and why. See How routing works.

Can I turn routing off?

Yes. Start the model gateway with HERO_ROUTE=0 (or false, no, off) to turn routing off. This works over the choice stored on this machine: each call then goes to the model your agent asked for. See Turn routing off.

How do I see why a call moved to another model?

Run hero route. A moved call shows the model that served it, the model your agent asked for, and a reason word, such as right_sized. right_sized: moved to a smaller model because measured evidence says it does this kind of work as well. A call marked (kept) was served by the model requested. To check that your agents send their calls through Agent OS at all, run hero route census. See How to read hero route output.

Can I pin a model?

A saved model pin is the model chosen under Pinned in the Portal's Control › You › Models & subscriptions. In this version that setting is read-only, so you can't save a pin here. See Turn routing off.

Does routing always choose the cheapest model?

No. Routing decides each call from that call's own signals: the model your agent asked for, the kind of work the call is, and whether a smaller model is available and fits the request. A call may move only where an approved move exists for that kind of call, and only to a lower-tier model from the same provider, unless you ask for the model auto or set a local model. Every move is listed in hero route with its reason. Routing is on after setup. See How routing works.

Efficiency

Is efficiency the same as routing?

No. Routing is one lever among many. Efficiency looks at the whole life of the work, and hero efficiency list shows each lever with what it found: retries, codify (mechanical rules still running on a model, which could run as code with no model call), caching, prefix alignment, output size, over-thinking, route, eval coverage, memory, content compression, tool duplication and agent right-sizing. The levers report; you choose what to change. See How Efficiency works.

Are the dollar figures my bill?

No. They're estimates. All savings and cost figures in Agent OS are at public list prices, unless you set your own rates with HERO_BILLING_RATES. A model with no list price is counted, not priced or guessed. See hero efficiency.

Observe

Where do I see what my agent did?

hero trace shows each session's tool calls and refusals, with sessions that had problems first. hero health gives one read of how your agents are doing, with a fix for each finding. hero schedule shows the standing jobs Agent OS runs for you on a cadence. See How observability works.

Where is the record kept?

On your machine.

How do I see what happened in one session?

Run hero trace. It reports on the sessions recorded on your machine over the last 30 days, with sessions that had problems first. hero trace show <id> replays one session step by step, and hero trace violations lists the newest policy violations. See hero trace.

How do I open the Portal and Monitor?

Run hero portal open. It opens the Portal in your browser, signed in. The Portal runs on your machine at http://127.0.0.1:7878 and has three views: Monitor, Control for your own work, and the Brain page. Monitor is the main screen, with tabs such as Overview, Health and Telemetry. To keep the Portal running after you close the terminal, run hero portal --install-service. See hero portal and The tabs on Monitor.

Troubleshooting and help

Something isn't working. Where do I start?

Run these in your own terminal, in this order: hero status, which checks the install and names one next step; hero setup --check, which checks each agent; and hero brain doctor, which checks the Brain. Run the step hero status names, then run it again. See Start with hero status.

How do I ask for help?

Run hero support and tell support the code it prints, with the output you saw. Email it to support@ekamyth.com. See Start with hero status.

What if the Brain won't load?

A problem with the Brain never stops a session from starting. If a Brain file can't be read, isn't valid text or is too large, the session starts without session memory and the block says Ekamyth Brain: memory could not be loaded. Run hero brain doctor. See The Brain and context.

Why Agent OS

I already use Claude Code. Why should I use Agent OS?

Agent OS works inside Claude Code and adds to it, on your machine: rules from your rules file checked as code at the tool call, the always-refused list, holds on sends through connected tools, a Brain given to each session as context, model routing with every choice shown, efficiency levers across the work, and a record of each session you can read. Your rules and your Brain also apply when you use Codex. See Agent OS on Claude Code and Codex for what differs.

I already use Codex. Why should I use Agent OS?

Agent OS works inside Codex too: rules from your rules file are checked as code at the tool call for shell commands, the always-refused list applies, a Brain is given to each session as context, and its model calls pass through the model gateway. Routing applies to Codex too, by the same rules (see hero route). Your rules and your Brain also apply when you use Claude Code. For what differs between the two agents, see Agent OS on Claude Code and Codex.

How is Agent OS different from other "agent OS" products?

What Agent OS is. Ekamyth Agent OS is an operating system for AI agents. It runs on your own machine, underneath the agents you already use, starting with Claude Code and Codex.

Why an operating system. Every computer runs on one. The operating system starts programs and stops them, gives them memory, controls what they're allowed to touch, and keeps a log of what happened. Programs don't have to be trusted to behave, because the operating system makes sure they do. That's what made computers dependable enough to put on every desk.

What we're building. Agent OS does those same jobs for agents, and adds what a new kind of worker needs. Programs are deterministic: the same input gives the same result. Agents are probabilistic: capable, but they can guess, drift, forget, or say they're done when they aren't. So Agent OS is:

What else is called an "agent OS." Many products now use the name. Most are one of these:

Each of these covers part of the job. Agent OS brings it all together, underneath the agents you already use and across vendors, as one operating system on your own machine.

I already use a tracing tool. Why should I use Agent OS?

Agent OS runs on your machine in the path of your agents' work: their model calls pass through the model gateway, and their tool calls reach Agent OS at the hooks. So besides showing what the work cost, it can act on it. Routing can move a model call to another model. A rule is checked as code at the tool call, and once enforcement is on it stops a matching call before it runs. Efficiency looks for waste across the whole of the work, with levers such as retries, caching, output size, over-thinking and mechanical rules that could run as code with no model call.

How does Agent OS lower what my agents' work costs?

Efficiency in Agent OS covers the whole life of the work, not only which model answers a call. hero efficiency shows what the work cost, what Agent OS has already saved, and the levers that would lower it, ranked by estimated savings. All savings and cost figures in Agent OS are at public list prices, unless you set your own rates. Known issue in this build: when a call that was moved to another model fails, the savings figure can overstate. See How Efficiency works.

Why shouldn't I use a model router instead?

Routing in Agent OS runs in the model gateway on your machine, next to your rules, your Brain and the record of your agents' work, and every choice it makes is shown in hero route. It decides each call from that call's own shape and Claude Code's markers, not from a view of your whole task, and a moved call stays with the provider your agent asked for, unless you ask for the model auto or set a local model. It's one efficiency lever among many, not the whole of efficiency.

Why should I use Agent OS rather than another agent platform?

Agent OS works inside the agents you already use, Claude Code and Codex, on your own machine, and you keep your own model provider. It gives them rules checked as code, a Brain, routing, efficiency across the work, a record you can read, and MCP.

What does Agent OS support?

Each row links to the area page that covers it.

CapabilityAgent OS
Works inside Claude Code and CodexYes. Connect
Runs on your machineYes
Checks a tool call against your rules as code, before it runsYes, on Claude Code, and for shell commands on Codex. A call that breaks a rule is refused once enforcement is on. Governance
Holds a send for your approvalYes, for sends, posts and deletes through connected tools. On Codex, only when the call reaches the hook. hero inbox
Gives each session context about you and your workYes, from your Brain. Brain
Routes model callsYes, with every choice shown. Routing
Looks for waste beyond model choiceYes. Efficiency
A record of each session you can readYes. Observe

Could I build this myself?

Agent OS is a set of parts that work together across Claude Code and Codex: hooks registered in each agent's own settings, rules read from your rules files and checked as code at the tool call, a list of always-refused command shapes, holds that only a person can approve from their own terminal, a Brain given to each session, a model gateway with routing and a cost record, efficiency levers across the work, standing checks on a cadence, and a declared list of what Agent OS is built to send off your machine.

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