Ekamyth Agent OS docs
Get started

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

Step 1. Install Agent OS

  1. 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.

  2. 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')"

    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.sh

    Then 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.
  3. 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

  1. Restart Claude Code and Codex, or open new sessions. Sessions that were already open don't pick up the connection.

  2. In Claude Code, type:

    /hero:health

    In Codex, use the hero-health skill.

  3. Work as usual for a few minutes, then see what Agent OS recorded:

    hero efficiency
  4. To 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.md

    Use AGENTS.md or your own rules file in place of CLAUDE.md. Then run hero enforce to 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

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.