Get started with Ekamyth Agent OS
Install Agent OS on Mac or Linux, connect Claude Code and Codex, and check that it works: one pasted line, then three checks.
What you'll do
You run the install line from your account page. It installs Agent OS, activates this machine, starts the model gateway and connects your agents. Then you check the install with hero status, check each agent with hero setup --check, and try a /hero: command in a new session.
Before you start
- A Mac or Linux machine, with
curl. You don't need sudo. - Your Ekamyth account. Its page,
ekamyth.ai/account, shows your install command. - Claude Code or Codex installed. Setup connects the agents it finds.
- Python 3.10 or newer. If you don't have it, the installer offers to add a private copy under your home folder.
Step 1. Install Agent OS
Sign in at
ekamyth.ai/account, choose Get an install command, and copy the command. It carries your install token, and works once, for 60 minutes.Paste it into a terminal and run it. Use the line for your system:
EKAMYTH_INSTALL_TOKEN='<install-token>' sh -c "$(curl -fsSL 'https://install.ekamyth.ai/install.sh' || echo 'echo could not fetch the Ekamyth install script; exit 1')"EKAMYTH_INSTALL_TOKEN='<install-token>' bash -c "$(curl -fsSL 'https://install.ekamyth.ai/install.sh' || echo 'echo could not fetch the Ekamyth install script; exit 1')"This line downloads the install script and runs it in one step. Agent OS refuses that shape, a downloaded script piped straight into a shell, when an agent tries it on its own (see Always refused). Here the difference is that you choose to run it, yourself, in your own terminal. To read the script before you run anything, download it and read it first:
curl -fsSL 'https://install.ekamyth.ai/install.sh' -o ekamyth-install.sh less ekamyth-install.shThen run the install command from your account page as above. As it installs, the installer says whether it checked the package's sha256.
The install line will:
- Install Agent OS under your home folder, and Python if you need it, after asking.
- Activate this machine with your account.
- Start the model gateway, the scheduler and the Portal as background services.
- Run
hero setup, which shows its plan for Claude Code and Codex and asks before it changes their settings.
Answer its questions: the dependency question (the MCP SDK and the packages it brings), the Python install if you need one, and setup's plan.
If activation didn't happen during the install, get a new install command from your account page and run it, or run
hero setup redeem <install-id>. See install id and secret code.
For each option and error, see Install, upgrade and remove.
Step 2. Read the closing report
The install ends with a closing report, one line per part.
See How to read the closing report.
Step 3. Check the install
Open a new terminal window, then run:
hero status
Example output. The format is the command's; the numbers are examples.
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
When all eight checks pass, hero status shows 8 checks · all ok, or 8 checks ok · <m> of <n> rules blocked if some registered rules do not block, and exits 0. If a check is ✗, run the command named after next: and then run hero status again. See How to read hero status output.
Step 4. Check each agent
hero setup --check
Output from version 0.1.36rc13 (build cd08bd39c026), on Linux. Trimmed where you see …
Local read access is ready.
hero setup --check — proxy http://127.0.0.1:50217
checked against http://127.0.0.1:50217: the proxy hero setup pointed your agents at, recorded in …
✓ claude covered — env.ANTHROPIC_BASE_URL targets Ekamyth Runtime · 5/5 hooks wired · …
…
✓ codex covered — model_providers.hero_runtime.base_url targets Ekamyth Runtime · 6/6 hooks wired · …
…
session memory: wired (claude, codex)
all detected agents route through Ekamyth Runtime ✓
skill adapters match the packaged digests ✓
The address is the one setup pointed your agents at, so yours can differ. It exits 0 when every agent is connected and 1 if an agent isn't. See Example 1 of hero setup.
Check coverage
Once each agent is connected, check what reaches Agent OS. Your agent's model calls reach the model gateway, and its tool calls reach the hooks; what a script does after your agent starts it reaches neither. For the full table, see What each connection covers.
# Which of your agents send their model calls through Agent OS
hero route census
# Which of your rules are enforced, on Claude Code and on Codex
hero enforce
# Whether an MCP server in your agent's config goes through the MCP wrapper
hero mcp status <server>
Each command's page shows its output: hero route census, hero enforce and hero mcp status.
Step 5. Try it in a new session
Restart Claude Code and Codex, or open new sessions. Sessions that were already open don't pick up the connection.
In Claude Code, type:
/hero:healthIn Codex, use the
hero-healthskill.Work as usual for a few minutes, then see what Agent OS recorded:
hero efficiencyTo have Agent OS enforce the rules in your project, register the file once you've written them, and again after each change:
hero init CLAUDE.mdUse
AGENTS.mdor your own rules file in place ofCLAUDE.md. Then runhero enforceto see each rule's state on Claude Code and on Codex.
If your agent's calls don't reach 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. Agent OS still watches its tool calls. To route Codex through Agent OS, 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. See Codex with your own provider.
To see which agents reach the model gateway, run hero route census.
What success looks like
hero statusshows8 checks · all okand exits0.hero setup --checkexits0.- A new Claude Code session runs
/hero:health.
Undo
To take Agent OS out of your agents, run this in your own terminal:
hero setup --undo
It puts your agents' settings back, removes the Codex hook approvals setup made, and drops this machine's activation, so a later setup needs a new install command from your account page. The rest of your Agent OS data stays. To remove Agent OS completely, see Remove Agent OS.
Next steps
To see Agent OS make a real decision, and to read what it recorded, work through Things to try. If something isn't working, see Troubleshooting.
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.