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.
- Use it when you install Agent OS for the first time, or upgrade to a new version.
- Use something else when you only want to reconnect your agents (
hero setup) or check the install (hero status). - Reads or changes: it installs software and changes your agents' settings, after asking. See step by step.
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')"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')"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.
| Variable | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
EKAMYTH_INSTALL_TOKEN | String | To activate a new machine | Unset: the installer asks | The token from your account page | Activates 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_YES | Flag | No | Unset: the installer asks | 1, 0 | 1 answers yes to each of the installer's questions up front. 0 declines them. |
EKAMYTH_INSTALL_NO_SERVICE | Flag | No | Unset | 1 | Installs and configures, but registers no background service. You start the model gateway yourself with hero proxy. See Example 5. |
EKAMYTH_WHEEL_SHA256 | 64 hex digits | No | Unset: the package is checked against the digest published with it | A sha256 digest | Also checks the package against a digest you got another way. On a mismatch, nothing is installed. |
HERO_PROXY_PORT | Port number | No | The port an earlier install saved, else 8081 | 1 to 65535 | The port the model gateway uses. |
How the install line works
- 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 usebash -c. - It downloads Agent OS and checks its sha256 against the digest published with it.
- 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.
- 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.
- It installs the new version in its own folder, checks that it answers, then makes it your
herocommand in one step. - 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. - It activates this machine with your install token. See Activation.
- It starts three background services: the model gateway, the scheduler and the Portal. They run as your user (launchd on Mac,
systemd --useron Linux) and restart after a crash. It waits up to 30 seconds for the model gateway to answer. - It runs
hero setup, which shows its plan for your agents and asks. Seehero setup. - 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.
Copy the install command from your account page,
ekamyth.ai/account.It works once, for 60 minutes.
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.
Answer its questions: the dependency question, the Python install if you need one, and setup's plan.
Setup prints
donewhen your agents are connected.Read the closing report.
You should see
yeson theconfigured,services,reachableandenrolledlines. See Example output.Open a new terminal window and check the install.
hero statusYou should see
8 checks · all ok. Seehero statusoutput.
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
| Line | What it means | What to do when it isn't yes |
|---|---|---|
| 1. installed | The version installed, where the hero command is, and the Python it runs on. | Nothing. This line always names what was installed. |
| 2. available | Whether 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. configured | Whether 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. services | How many of the background services were registered, and whether your OS is running them. | Run the start manually: command it names. |
| 5. reachable | Whether 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. enrolled | Whether 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. authenticated | Which 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-value | A 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 here | Two commands to try first. Neither needs a provider key. | See hero govern and hero health. |
| 10. Removal line | The 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.
Note the version you have.
hero versionYou should see a line like
ekamyth 0.1.36rc13 (build 1c14e25f63a7).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
herocommand 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 setupagain, 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'Copy the
roll back:line somewhere safe. You need it only to go back.
To check the upgrade worked:
hero versionprints the new version.- The closing report shows
yesonconfigured,servicesandreachable. hero statusshows8 checks · all ok.- Restart Claude Code and Codex, or open new sessions, so they pick up the new slash commands.
If the upgrade fails:
| What you see | What it means | What to do |
|---|---|---|
the new install was removed and the active install was NOT switched; nothing changed | The 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 30s | The 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 yes | A 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
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
herocommand back. It doesn't restart a model gateway that's already running.Restart the model gateway on that version.
hero proxy --install-serviceThis 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).Check it.
hero version hero statusYou 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.
Run the uninstaller in your own terminal.
curl -fsSL https://install.ekamyth.ai/uninstall.sh | shThis 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
ekamythpackage and theherocommand. - Keep your data in
~/.hero. Delete it yourself for a clean slate.
- Ask before it removes anything. To answer yes up front, run it as
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')"EKAMYTH_INSTALL_NO_SERVICE=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')"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
| Code | Meaning | What to do |
|---|---|---|
0 | The install ran to its closing report. A line in the report can still say NOT VERIFIED or not active. | Read the closing report. |
1 | The install stopped. Either nothing was installed, or setup failed (install NOT complete). | Read the last line, and see the errors below. |
| Error | Cause | Fix |
|---|---|---|
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 script | The download failed or the link expired. | Check your network, then copy a new command from your account page. |
sha256 MISMATCH — ... — nothing installed | The 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/account | The token was used, expired or refused. | Get a new install command from your account page. |
| The upgrade errors | See Example 1. | |
Files and environment for the install line
| Name | Kind | Purpose |
|---|---|---|
~/.local/bin/hero | Command | The hero command. It points at the active version. |
~/.local/share/ekamyth/envs/ | Folder | Installed versions: the active one and one previous. |
~/.claude/settings.json, ~/.codex/config.toml, ~/.codex/hooks.json | Your agents' files, changed by setup | Setup keeps a copy of each beside it before changing it. See hero setup. |
~/.hero | Folder | Your Agent OS data. Removal keeps it. |
~/Library/LaunchAgents/com.ekamyth.* on Mac, ~/.config/systemd/user/hero-* on Linux | Service files | The background services, registered as your user. |
~/.zprofile on Mac, ~/.profile on Linux | Your shell profile | Where to add the PATH line if a new terminal doesn't find hero. The installer doesn't edit it. |
ANTHROPIC_API_KEY, OPENAI_API_KEY | Environment variables, read | Named on the authenticated line when set. |
| Install options | Environment variables | See Options. |
Limits of install, upgrade and remove
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Upgrades | There's no hero update command, and nothing tells you a new version exists. | No | Run a new install command from your account page. |
| Rollback | One previous version is kept. | No | Keep the roll back: line from each upgrade. |
| Install command | Works once, for 60 minutes, for one account. | No | Get a new one from your account page. |
| Linux shell | The line must start with bash -c. | No | Replace sh -c with bash -c. |
| Python | Needs Python 3.10 or newer. | No | Let the installer add a private Python, or install one yourself. |
| Linux services at logout | The background services can stop when you log out. | Not known | After you log in again, run hero status; its proxy row shows whether the model gateway answers. |
| The installer's removal line | The removal line the installer prints names the services and the package, but not hero setup --undo. | No | Use the uninstaller, which runs hero setup --undo first. See Example 4. |
hero setup before activation | On a machine that isn't active, hero setup exits with an error and tells you to run hero setup again. | No | Run hero setup redeem <Install id>, or run a new install command from your account page. |
Pages related to install, upgrade and remove
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.