Ekamyth Agent OS docs
Get started / Install, upgrade and remove

Install, upgrade and remove Ekamyth Agent OS

One pasted line installs Agent OS on Mac or Linux, activates this machine and connects Claude Code and Codex. The same line upgrades it.

What the install line does

The install line downloads Agent OS, checks it, installs it under your home folder with no sudo, activates this machine with your account, starts its background services and runs hero setup. It ends with a report of where the install stands.

There's no hero update command. To upgrade, you get a new install command from your account page and run it. See Example 1.

Synopsis of the install line

Copy the line from your account page at ekamyth.ai/account. It carries your install token. 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')"

Without EKAMYTH_INSTALL_TOKEN, the installer asks for the token at the prompt Install token, or Install id (blank to skip):, where nothing you type is shown. In a terminal, leave it blank and press Enter to skip. The machine then isn't active: nothing is connected and no service starts. See Activation.

Options for the install line

Set these in front of the line, as EKAMYTH_INSTALL_TOKEN is.

VariableTypeRequiredDefaultAllowed valuesWhat it does
EKAMYTH_INSTALL_TOKENStringTo activate a new machineUnset: the installer asksThe token from your account pageActivates this machine with your account. It works once, for 60 minutes. The installer removes it from the environment before running anything else, and never prints it.
EKAMYTH_ASSUME_YESFlagNoUnset: the installer asks1, 01 answers yes to each of the installer's questions up front. 0 declines them.
EKAMYTH_INSTALL_NO_SERVICEFlagNoUnset1Installs and configures, but registers no background service. You start the model gateway yourself with hero proxy. See Example 5.
EKAMYTH_WHEEL_SHA25664 hex digitsNoUnset: the package is checked against the digest published with itA sha256 digestAlso checks the package against a digest you got another way. On a mismatch, nothing is installed.
HERO_PROXY_PORTPort numberNoThe port an earlier install saved, else 80811 to 65535The port the model gateway uses.

How the install line works

  1. It checks the system. Mac and Linux go on. Anything else stops here, before anything is downloaded. On Linux, if it was started with sh -c, it stops and tells you to use bash -c.
  2. It downloads Agent OS and checks its sha256 against the digest published with it.
  3. It finds Python 3.10 or newer. If there's none, it offers to install a private Python 3.12 with uv, under your home folder only, with no sudo. Your system Python stays as it is. If that doesn't work and you have Homebrew, it offers Homebrew instead.
  4. It tells you what Agent OS brings with it, and asks. Agent OS depends on the MCP SDK, which brings 29 packages in total, or 30 on Python 3.10. They go into an environment only Agent OS uses. If you decline, nothing is installed.
  5. It installs the new version in its own folder, checks that it answers, then makes it your hero command in one step.
  6. It checks that a new terminal window finds hero. If not, it prints the line to add to your shell profile. It doesn't edit your profile itself.
  7. It activates this machine with your install token. See Activation.
  8. It starts three background services: the model gateway, the scheduler and the Portal. They run as your user (launchd on Mac, systemd --user on Linux) and restart after a crash. It waits up to 30 seconds for the model gateway to answer.
  9. It runs hero setup, which shows its plan for your agents and asks. See hero setup.
  10. It prints a closing report of where the install stands. See How to read it.

Everything goes under your home folder.

Activation

Activation links this machine to your Ekamyth account. The install token does it during install. On a machine that isn't active, the installer installs the package, connects nothing and starts no service, and hero setup leaves your agents unchanged until activation. To check, run hero setup access. See Example 2 of hero setup. If you have an Install id and Secret code instead, run hero setup redeem <install-id>. Both that command and the install-token flow send that id, the secret code and a separate random activation installation id; the heartbeat sends its own random installation id, version, platform and event. See Example 3 of hero setup.

Get started: install Agent OS

Before you start: a Mac or Linux machine with curl, your Ekamyth account, and Claude Code or Codex installed. Setup connects the agents it finds.

  1. Copy the install command from your account page, ekamyth.ai/account.

    It works once, for 60 minutes.

  2. Paste it into a terminal and run it. On Linux, the line starts with bash -c; see the Linux tab in the synopsis.

    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 asks before it changes your agents' settings.

    You should see each step as it runs, with a ✓ for each that worked.

  3. Answer its questions: the dependency question, the Python install if you need one, and setup's plan.

    Setup prints done when your agents are connected.

  4. Read the closing report.

    You should see yes on the configured, services, reachable and enrolled lines. See Example output.

  5. Open a new terminal window and check the install.

    hero status

    You should see 8 checks · all ok. See hero status output.

Then restart Claude Code and Codex, or open new sessions. To take Agent OS out of your agents, see Example 3. To remove it, see Example 4.

Example output of the install line

The closing report on an active machine

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

The closing report on a machine that isn't active

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

Excerpt: the closing report on Linux with no install token, paths shortened to ~.

  where this install stands:
    installed      ekamyth 0.1.36rc13 (build 94941456cd4b) -> ~/.local/bin/hero (Python 3.12.3)
    available      NOT YET — a new terminal window does not find hero; add to ~/.profile: export PATH="~/.local/bin:$PATH"  (then open a new window)
    configured     not active — Ekamyth is installed but not active on this machine yet; nothing was wired and your agents are unchanged (have an Install id? ~/.local/bin/hero setup redeem <Install id>)
    services       not started — Ekamyth is not active on this machine yet (nothing was registered with your OS)
    reachable      not checked — Ekamyth is not active on this machine yet, so no proxy was started (probed http://127.0.0.1:8081)
    enrolled       skipped — no terminal to ask on (run it any time: ~/.local/bin/hero setup redeem <Install id>)

How to read the closing report

LineWhat it meansWhat to do when it isn't yes
1. installedThe version installed, where the hero command is, and the Python it runs on.Nothing. This line always names what was installed.
2. availableWhether a new terminal window finds hero.Add the export PATH=... line it prints to ~/.zprofile on Mac or ~/.profile on Linux, then open a new window.
3. configuredWhether hero setup finished connecting your agents.not active: activate this machine (see Activation). NOT VERIFIED or FAILED: run the re-run: command it prints, and read setup's output above the report.
4. servicesHow many of the background services were registered, and whether your OS is running them.Run the start manually: command it names.
5. reachableWhether the model gateway this install started answered on your machine, and the address it checked.Run hero status and read its proxy row. See hero status.
6. enrolledWhether this machine was activated during this install.Get a new install command from your account page and run it again, or run hero setup redeem <Install id>.
7. authenticatedWhich provider keys are set in this terminal. It never confirms that a key or sign-in works, because only a real model call can show that.Nothing, if your agent uses its own sign-in or key.
8. first-valueA real governance decision, made on this machine as the install finished. An allow or a deny both mean the gate is answering.NOT VERIFIED: run the hero govern check command it names to see why.
9. Start hereTwo commands to try first. Neither needs a provider key.See hero govern and hero health.
10. Removal lineThe installer ends with a removal line, cut from this excerpt.To remove Agent OS, see Example 4.

More install examples

Example 1. To upgrade to a new version

Run a new install command from your account page. Agent OS doesn't tell you when a new version exists.

  1. Note the version you have.

    hero version

    You should see a line like ekamyth 0.1.36rc13 (build 1c14e25f63a7).

  2. Get a new install command from your account page, and run it as you did to install. On Linux, use bash -c.

    The install line will:

    • Install the new version in its own folder, beside the one you have.
    • Check that the new version answers before switching to it. If it doesn't, it removes it and changes nothing.
    • Switch your hero command to the new version in one step. A check already running finishes on the version it started on.
    • Reinstall the background services, so they run the new version.
    • Run hero setup again, which shows its plan and asks.
    • Keep your previous version for one rollback, and print the command to switch back.
    • Remove versions older than that, once setup completes.

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

      ✓ verified ekamyth 0.1.37 (build 0123456789ab) in /Users/example/.local/share/ekamyth/envs/20261110T170000Z-4242
      ✓ switched /Users/example/.local/bin/hero to it
      the previous version is kept for one rollback: /Users/example/.local/share/ekamyth/envs/20261104T053713Z-3570
        roll back: ln -sfn '/Users/example/.local/share/ekamyth/envs/20261104T053713Z-3570/bin/hero' '/Users/example/.local/bin/hero'
  3. Copy the roll back: line somewhere safe. You need it only to go back.

To check the upgrade worked:

If the upgrade fails:

What you seeWhat it meansWhat to do
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 send the code it prints, with the installer's output, to support at the address in your welcome email.
install NOT complete — hero setup exited <n>: setup not fully complete; see component results above; 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 that isn't yesA background service didn't start.Run the start manually: command it names.

If your agents misbehave after the upgrade, roll back, then tell support.

Example 2. To go back to the previous version

  1. Run the roll back: line the upgrade printed. For example:

    ln -sfn '/Users/example/.local/share/ekamyth/envs/20261104T053713Z-3570/bin/hero' '/Users/example/.local/bin/hero'

    This switches your hero command back. It doesn't restart a model gateway that's already running.

  2. Restart the model gateway on that version.

    hero proxy --install-service

    This command will:

    • Reinstall and reload the model gateway service, so it runs the version you switched to.

    On Linux you should see refreshed: ... (if it was already running, it now runs this build).

  3. Check it.

    hero version
    hero status

    You should see the previous version, and 8 checks · all ok.

Only one previous version is kept. If you installed from a folder copy of the installer, the upgrade prints '<folder>/install.sh' --switch '<version folder>' instead: run that.

Example 3. To take Agent OS out of your agents

Run this in your own terminal. Agent OS refuses it when an agent runs it.

hero setup --undo

It takes back what setup wrote, including the Codex hook approvals, and drops this machine's activation. Agent OS stays installed. See Example 5 of hero setup for what it changes.

Example 4. To remove Agent OS

Removing Agent OS takes it out of your agents, removes its background services and the package, and keeps your data in ~/.hero.

  1. Run the uninstaller in your own terminal.

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

    This command will:

    • Ask before it removes anything. To answer yes up front, run it as curl -fsSL https://install.ekamyth.ai/uninstall.sh | sh -s -- --yes.
    • Take Agent OS out of your agents first, by running hero setup --undo: the model address, the hook entries and the /hero:* commands in Claude Code, Agent OS's entries in ~/.codex/config.toml, and the Codex hook approvals.
    • Remove the background services: the model gateway, the scheduler, the Portal, the workflow runner and the daily rule sync.
    • Remove the ekamyth package and the hero command.
    • Keep your data in ~/.hero. Delete it yourself for a clean slate.
  2. Check nothing is left running.

    # Mac: prints nothing
    launchctl list | grep com.ekamyth
    
    # Linux: lists no units
    systemctl --user list-units 'hero-*'

A later install needs a new install command, because undo also drops this machine's activation.

Example 5. To install with no background services

EKAMYTH_INSTALL_NO_SERVICE=1 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')"

The closing report's services line reads skipped — EKAMYTH_INSTALL_NO_SERVICE=1. Start the model gateway yourself and keep it running:

hero proxy

Exit codes and errors for the install line

CodeMeaningWhat to do
0The install ran to its closing report. A line in the report can still say NOT VERIFIED or not active.Read the closing report.
1The install stopped. Either nothing was installed, or setup failed (install NOT complete).Read the last line, and see the errors below.
ErrorCauseFix
On Linux, run the install command with bash instead of sh: replace the leading 'sh -c' with 'bash -c'.The line was started with sh -c on Linux.Replace sh -c with bash -c and run it again. Your token still works if it's 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.
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 at the address in your welcome email, with the file name and the sha256 you got.
no compatible Python 3.10+ was installed — install it from https://python.org (or Homebrew from https://brew.sh), then re-run: <line>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. The MCP SDK is a base dependency, so there is no smaller install to offer.You declined the dependency question.Review the list it names, then run the 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 token was used, expired or refused.Get a new install command from your account page.
The upgrade errorsSee Example 1.

Files and environment for the install line

NameKindPurpose
~/.local/bin/heroCommandThe hero command. It points at the active version.
~/.local/share/ekamyth/envs/FolderInstalled versions: the active one and one previous.
~/.claude/settings.json, ~/.codex/config.toml, ~/.codex/hooks.jsonYour agents' files, changed by setupSetup keeps a copy of each beside it before changing it. See hero setup.
~/.heroFolderYour Agent OS data. Removal keeps it.
~/Library/LaunchAgents/com.ekamyth.* on Mac, ~/.config/systemd/user/hero-* on LinuxService filesThe background services, registered as your user.
~/.zprofile on Mac, ~/.profile on LinuxYour shell profileWhere to add the PATH line if a new terminal doesn't find hero. The installer doesn't edit it.
ANTHROPIC_API_KEY, OPENAI_API_KEYEnvironment variables, readNamed on the authenticated line when set.
Install optionsEnvironment variablesSee Options.

Limits of install, upgrade and remove

LimitBehaviourCan you change it?What to do
UpgradesThere's no hero update command, and nothing tells you a new version exists.NoRun a new install command from your account page.
RollbackOne previous version is kept.NoKeep the roll back: line from each upgrade.
Install commandWorks once, for 60 minutes, for one account.NoGet a new one from your account page.
Linux shellThe line must start with bash -c.NoReplace sh -c with bash -c.
PythonNeeds Python 3.10 or newer.NoLet the installer add a private Python, or install one yourself.
Linux services at logoutThe background services can stop when you log out.Not knownAfter you log in again, run hero status; its proxy row shows whether the model gateway answers.
The installer's removal lineThe removal line the installer prints names the services and the package, but not hero setup --undo.NoUse the uninstaller, which runs hero setup --undo first. See Example 4.
hero setup before activationOn a machine that isn't active, hero setup exits with an error and tells you to run hero setup again.NoRun hero setup redeem <Install id>, or run a new install command from your account page.

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