Ekamyth Agent OS docs
Standard OS / Services and devices

hero setup

Connects Claude Code and Codex to Ekamyth Agent OS, after showing you its plan.

What hero setup does

It points your agents' model calls at the model gateway, adds Agent OS hooks to each agent and installs the /hero: slash commands. It answers one question: are my agents connected to Agent OS?

On a machine that isn't active, hero setup exits 1. See Activation. 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. You can enter the Install id from your invitation instead, to redeem it.

Synopsis for hero setup

hero setup [--proxy <url>] [--yes] [--json]
hero setup --check [--proxy <url>] [--json]
hero setup --undo [--json]
hero setup commands
hero setup access [--json]
hero setup redeem <install-id> [--no-connect] [--json]
hero setup revoke-codex [--json]
hero setup --help

Subcommands of hero setup

SubcommandWhat it doesReads or changes
(none)Shows its plan, asks, then connects the agents it finds and installs the slash commands.Changes
--checkReports, for each agent, whether its model calls route through Agent OS, whether its hooks are in place and whether the model gateway answers.Reads
--undoTakes back what setup wrote to your agents, so they work without Agent OS.Changes
commandsInstalls the slash commands and Codex skills only.Changes
accessSays whether this machine is active.Reads
redeemActivates this machine with an install id and secret code, then connects your agents.Changes
revoke-codexRemoves the Codex hook approvals setup made, without undoing the rest. --undo already includes it.Changes

Arguments for hero setup

Arguments for bare hero setup

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
--proxy <url>URLNohttp://127.0.0.1:8081, on the port from HERO_PROXY_PORT or the one saved at installThe URL of a model gateway, with a host and port and no user name or passwordThe model gateway to point your agents at.
--yes, -yFlagNoOff: it asksApplies the plan without asking.
--jsonFlagNoOffMachine-readable output.

Arguments for --check

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
--proxy <url>URLNoThe address setup last pointed your agents atThe URL of a model gatewayThe model gateway to check against.
--jsonFlagNoOffOne JSON document. See Example 7.

Arguments for redeem

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
<install-id>StringYesThe Install id from your invitationNames the activation. The secret code is asked for at a prompt, or read from standard input. It's never an argument.
--no-connectFlagNoOffActivates only, without connecting your agents.
--jsonFlagNoOffOne JSON document. Activates only.

--undo, access and revoke-codex take --json only. commands takes no arguments.

How hero setup connects your agents

  1. It finds Claude Code and Codex on this machine, and checks that the machine is active.
  2. It checks that the model gateway answers and belongs to this install. If not, it won't write that agent's model route: the route stays as it is. It still installs the hooks and slash commands, and exits 1.
  3. It prints its plan for each agent and asks. With no terminal to ask on, it changes nothing unless you pass --yes.
  4. It applies the plan in this order, keeping a copy of each settings file beside it before changing it:
    • your agent's identity across Claude Code and Codex. If it already has one, it's kept;
    • the default governance posture, then rule enforcement, armed;
    • each agent's model route to the model gateway, where step 2 allowed it, and the gateway's address for later checks;
    • the hooks: 5 in Claude Code, and 6 in Codex 0.114.0 or later (5 in earlier versions). It asks Codex to approve exactly those hooks, through Codex's own approval. Codex's PreToolUse hook runs inside a guard: if Agent OS can't answer for a tool call within 120 seconds, or its answer isn't a valid decision, the guard refuses that tool call;
    • a one-time read of the rules in this project's CLAUDE.md, AGENTS.md and memory files and your user-level rule files, and a daily background job that reads them again. When sent to Ekamyth, a rule-compilation request carries a tokenized rule template, tenant and rule identifiers, placeholder types and any compilation constraints; automatic sending is paused by default. See What Agent OS may send, and when.
  5. It checks each agent's route, then installs 12 slash commands in Claude Code and 12 skills in Codex.
  6. If everything worked, it ends with a short health summary from hero health. That summary doesn't change setup's exit code.

For what the connection carries, see How Agent OS connects to Claude Code and Codex.

Get started with hero setup

Before you start: Agent OS is installed and this machine is active (hero setup access prints active). The model gateway is running (the proxy row of hero status shows running). Claude Code or Codex is installed.

  1. See which agents are connected now. This only reads.

    hero setup --check

    You should see one line per agent. It exits 1 if any agent isn't connected.

  2. Connect your agents.

    hero setup

    This command will:

    • Print its plan and wait for your yes.
    • Point Claude Code and Codex at the model gateway, add hooks to both, and keep a copy of each file it changes.
    • Set the default governance posture, read your rule files and add a daily job that keeps them in sync.
    • Install 12 slash commands in Claude Code and 12 skills in Codex.

    You should see done, then the slash commands it installed. See Example output.

  3. Restart Claude Code and Codex, or open new sessions, so they pick up the change.

  4. Check again.

    hero setup --check

    You should see a ✓ for each agent, then all detected agents route through Ekamyth Runtime ✓.

To undo, run hero setup --undo in your own terminal. See Example 5.

Example output of hero setup

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

Excerpt, from Linux with --yes: paths shortened to ~. A … marks lines or line ends left out.

How to read hero setup output

LineWhat it meansWhat to do
1. HeaderThe model gateway address setup points your agents at.If it's not the one you run, pass --proxy <url>.
2. PlanWhat setup changes for each agent, shown before it changes anything. NOT written: proxy not reachable means that agent's model route stays as it is.Read it, then answer. For NOT written, start the model gateway and run setup again.
3. Governance postureThe default posture, what runs, and the command shapes that are always refused.See How governance works.
4. What was setEach change, the file it went into, and the copy kept of each file as it was.To go back, use hero setup --undo.
5. VerifyA ✓ per connected agent: its model route targets the model gateway, and how many of its hooks are wired. answered 401 means the route is served. A check with no key can't vouch for your agent's own credentials.A ✗: run hero setup --check and follow the line it prints.
6. Codex linesCut from this excerpt: Codex's ✓ line, and a line that can say setup couldn't read Codex's conversation list, so it can't tell whether conversations you started before setup still go straight to OpenAI.Setup says so in its output when it can't tell.
7. DoneEvery detected agent routes through Agent OS.Nothing.
8. Slash commandsThe /hero: commands in Claude Code and the skills in Codex.Type /hero:health in Claude Code to try one.
9. RestartRunning sessions don't pick up the change.Restart Claude Code and Codex, or open new sessions.

More hero setup examples

Example 1. To check your agents are connected

hero setup --check

Output from version 0.1.36rc13. Trimmed where you see …

Excerpt, from Linux. The address is the one setup last pointed your agents at, so yours can differ. A … marks lines or line ends left out.

  Local read access is ready.
hero setup --check — proxy http://127.0.0.1:28471
  checked against http://127.0.0.1:28471: the proxy hero setup pointed your agents at, recorded in …
  ✓ claude   covered — env.ANTHROPIC_BASE_URL targets Ekamyth Runtime · 5/5 hooks wired · …
  …
      · runtime: no running claude process for this HOME observed — a future session's launch environment cannot be checked now; re-run `hero setup --check` while it runs
  …
session memory: wired (claude, codex)

  all detected agents route through Ekamyth Runtime  ✓
  skill adapters match the packaged digests  ✓

It exits 0 when every agent is connected and 1 on any gap. The runtime: line means no session was open to check. Run it again while Claude Code or Codex is running to check the session too.

Example 2. To see whether this machine is active

hero setup access

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

active (redeem, since 2026-11-04)

The word in brackets says how the machine was activated: redeem means this machine was activated with an install token, or with the Install id and Secret code from your invitation; pre-gate means it qualified through the check for an existing connection from before activation was introduced. The date is in UTC. It prints not active and exits 1 when the machine isn't active. With --json it prints one object with schema (hero.setup.access.v1), state (active or not_active), source, since and exit_code.

Example 3. To activate this machine with an install id

hero setup redeem <install-id>

This command will:

  • Ask for the secret code, without showing it.
  • Send the install id, the code and a random id for this installation to Ekamyth, and record this machine as active.
  • Connect your agents, as hero setup does.

Example 4. To reinstall the slash commands only

hero setup commands

It installs the slash commands and Codex skills for the agents it finds, and leaves model routes and hooks as they are.

Example 5. To take Agent OS out of your agents

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

hero setup --undo

This command will:

  • Remove the model route setup wrote, or put back the value that was there before. A value you've changed since is yours: it's left and reported.
  • Remove the Codex hook approvals setup made. An approval you changed since is left and reported.
  • Remove the hook entries setup wrote. A hook you wrapped is left and reported.
  • Remove the slash command files setup installed, unless you've edited them.
  • Remove the daily job that keeps your rules in sync.
  • Drop this machine's activation. A later hero setup needs a new install command.
  • Keep a copy of each file it changes, and leave the rest of your data in ~/.hero.

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

Excerpt: the opening and closing lines.

hero setup --undo — taking back what `hero setup` wrote to your agents
  …
  your data in ~/.hero was not touched (only the preview access record, if there was one)
  restart Claude Code (or open a new session) to pick up the change

Lines starting with ✗ are steps to do by hand. Do them, then restart your agent.

Example 6. To withdraw the Codex hook approvals only

Use this to withdraw Codex's approval of the hooks without undoing the rest of setup. hero setup --undo already includes it. Run it in your own terminal.

hero setup revoke-codex

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

One of the lines it can print:

  codex: hero has approved no Codex hooks here — nothing to revoke

It removes only the approvals setup made. If you approved a hook of your own since, that approval stays, and it says so.

Example 7. To use the check in a script

hero setup --check --json

It prints one JSON document on one line.

FieldMeaning
schemahero.setup.composite-result.v1.
statusok or error.
reason_codeWhy it isn't ok, such as coverage_gap, no_agents_detected or adapter_not_installed. Empty when ok.
exit_codeThe exit code: 0 or 1.
coveragestate (covered, gap or no_agents), covered, and one entry per agent in agents.
session_memorywired, and a detail line.
adaptersWhether the slash command files match what setup installed: state is clean or not_installed, for example.
setup, monitor_local_readsetup is the result of the check on your agents and the model gateway. monitor_local_read says whether this install has authorized local read access for the activity views in Ekamyth Monitor. A read check that is refused, or not reached, is not ready.

Bare hero setup --json uses the same schema value with a different set of fields, and has no coverage. Add --yes, because --json doesn't give consent.

Exit codes and errors for hero setup

CodeMeaningWhat to do
0Done. For --check, every agent is connected. For access, the machine is active.Nothing.
1A state, not a crash: no agent found, you answered no, an agent isn't connected, or the machine isn't active. For redeem, the machine wasn't activated. For --undo or revoke-codex, a step is left for you to do by hand.Read the output. It names the step.
2, refusedRefused, and nothing changed: no terminal to confirm the plan and no --yes; run from inside an agent session; a --proxy URL with a user name or password; or a word or option setup doesn't take.Read the remedy line. For no terminal, run it in a terminal or pass --yes.
2, partly appliedPartly applied: your agents are connected, but a later step failed, such as your agent's identity, or Agent OS's data folder isn't writable and setup stopped part way.Read the output: it names the step that failed. hero setup --undo takes back what was wired.
3Setup failed with an unexpected error.Run hero support and tell support the code it prints, with the output you saw. Email it to the support address in your welcome email.
ErrorCauseFix
hero setup: not applied — there is no terminal to confirm the plan above, so nothing was changed.Setup ran with no terminal to ask on.Run it in a terminal, or with --yes.
NOT written: proxy not reachableThe model gateway didn't answer, so setup left that agent's model route alone.Start the model gateway with hero proxy --install-service, then run hero setup again.
Ekamyth is installed but not active on this machine yet. Your agents are unchanged.This machine isn't active.Run the install command from your account page, or hero setup redeem <install-id>.
Ekamyth could not check this action, so it refused it: <reason> [<code>]. Run: hero setup --checkIn Codex, the hook guard refused a tool call because Agent OS couldn't give a decision, for example the check did not answer within 120 seconds [guard_timeout] or the hook program is missing or cannot run [guard_program_missing].Run hero setup --check and follow the line it prints. If Agent OS was removed, hero setup --undo takes the hook out of Codex.
refused `hero setup --undo` switches off rules, and it runs with the agent marker CLAUDECODE set. A governed agent cannot switch off its own rulesYou asked your agent to run --undo, revoke-codex or a setup that re-points the hooks.Run it yourself in your own terminal.
{"refused": true, "reason": "unknown_verb", "governing_rule": "hero setup declares verbs: commands, redeem, access, revoke-codex", "remedy": "hero setup --help"}A subcommand setup doesn't have, with --json.Use one from the synopsis.

Files and environment for hero setup

NameKindPurpose
~/.claude/settings.jsonYour Claude Code settings, changedSetup sets ANTHROPIC_BASE_URL and adds 5 hook entries.
~/.codex/config.tomlYour Codex settings, changedSetup adds a model provider, OPENAI_BASE_URL for shells Codex starts, and Codex's approval of the hooks.
~/.codex/hooks.jsonYour Codex hooks, changedSetup adds 6 hook entries, or 5 before Codex 0.114.0.
<file>.hero-backup-<time>Copy, writtenEach file as it was before setup or undo changed it, beside the file.
~/.claude/commands/hero/Folder, writtenThe 12 slash commands.
~/.agents/skills, ~/.codex/skillsFolders, writtenThe 12 Codex skills.
HERO_PROXY_PORTEnvironment variableThe port in the default --proxy address.
EKAMYTH_INSTALL_NO_SERVICE=1Environment variableSkips the daily job that keeps your rules in sync.
HERO_BRAIN_SESSION_MEMORY=offEnvironment variableStops adding your saved memory at session start.
HERO_CODIFY_ENFORCE=offEnvironment variable, in the agent's environmentStops your rules from blocking tool calls once enforcement is on. hero codify enforce off does the same. Set it yourself: a value your agent sets inside a tool call doesn't affect the hooks. See What your agent can't change.

Limits of hero setup

LimitBehaviourCan you change it?What to do
AgentsSetup connects Claude Code and Codex. Gemini CLI isn't connected.NoNone.
Agent versionsCodex's end-of-turn hook needs Codex 0.114.0 or later.NoUpdate Codex.
Earlier Codex conversationsSetup can't always tell whether conversations started before setup still go straight to OpenAI.NoSetup says so in its output when it can't tell.
Undo and activation--undo also drops this machine's activation.NoGet a new install command from your account page before you run setup again.
Who can undo--undo and revoke-codex run only from your own terminal. An agent is refused.NoRun them yourself.
Model gateway down during setupSetup never points an agent at a model gateway that isn't answering. It installs the hooks and slash commands, and exits 1.NoStart the model gateway, then run hero setup again.
Setup before activationOn a machine that isn't active yet, hero setup can exit with an error that tells you to run hero setup again.NoRun hero setup redeem <Install id> instead.
Rules read by setupRules that only hero setup picked up are listed but not enforced.NoRun hero init CLAUDE.md (or AGENTS.md) in your project after writing a rule.
User-level rule filesRules in ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md aren't enforced.NoPut rules you need enforced in the project's CLAUDE.md or AGENTS.md.
Activation after your access endsThis machine's activation isn't checked again with Ekamyth after it's written.NoNone.
Your own editsUndo leaves a model route you repointed, a hook you wrapped and a slash command you edited, and reports each.NoRemove those by hand if you want them gone.

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