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?
- Use it when you connect an agent for the first time, add Codex or Claude Code later, or want to check or undo the connection. The install line runs it for you.
- Use something else when you want to check the whole install (
hero status) or start the model gateway (hero proxy). - Reads or changes: bare
hero setup,redeem,commands,--undoandrevoke-codexchange your agents' settings.--checkandaccessonly read.
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
| Subcommand | What it does | Reads or changes |
|---|---|---|
| (none) | Shows its plan, asks, then connects the agents it finds and installs the slash commands. | Changes |
--check | Reports, for each agent, whether its model calls route through Agent OS, whether its hooks are in place and whether the model gateway answers. | Reads |
--undo | Takes back what setup wrote to your agents, so they work without Agent OS. | Changes |
commands | Installs the slash commands and Codex skills only. | Changes |
access | Says whether this machine is active. | Reads |
redeem | Activates this machine with an install id and secret code, then connects your agents. | Changes |
revoke-codex | Removes the Codex hook approvals setup made, without undoing the rest. --undo already includes it. | Changes |
Arguments for hero setup
Arguments for bare hero setup
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--proxy <url> | URL | No | http://127.0.0.1:8081, on the port from HERO_PROXY_PORT or the one saved at install | The URL of a model gateway, with a host and port and no user name or password | The model gateway to point your agents at. |
--yes, -y | Flag | No | Off: it asks | Applies the plan without asking. | |
--json | Flag | No | Off | Machine-readable output. |
Arguments for --check
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--proxy <url> | URL | No | The address setup last pointed your agents at | The URL of a model gateway | The model gateway to check against. |
--json | Flag | No | Off | One JSON document. See Example 7. |
Arguments for redeem
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
<install-id> | String | Yes | The Install id from your invitation | Names the activation. The secret code is asked for at a prompt, or read from standard input. It's never an argument. | |
--no-connect | Flag | No | Off | Activates only, without connecting your agents. | |
--json | Flag | No | Off | One JSON document. Activates only. |
--undo, access and revoke-codex take --json only. commands takes no arguments.
How hero setup connects your agents
- It finds Claude Code and Codex on this machine, and checks that the machine is active.
- 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. - It prints its plan for each agent and asks. With no terminal to ask on, it changes nothing unless you pass
--yes. - 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.mdand 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.
- It checks each agent's route, then installs 12 slash commands in Claude Code and 12 skills in Codex.
- 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.
See which agents are connected now. This only reads.
hero setup --checkYou should see one line per agent. It exits
1if any agent isn't connected.Connect your agents.
hero setupThis 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.Restart Claude Code and Codex, or open new sessions, so they pick up the change.
Check again.
hero setup --checkYou 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
| Line | What it means | What to do |
|---|---|---|
| 1. Header | The model gateway address setup points your agents at. | If it's not the one you run, pass --proxy <url>. |
| 2. Plan | What 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 posture | The default posture, what runs, and the command shapes that are always refused. | See How governance works. |
| 4. What was set | Each change, the file it went into, and the copy kept of each file as it was. | To go back, use hero setup --undo. |
| 5. Verify | A ✓ 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 lines | Cut 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. Done | Every detected agent routes through Agent OS. | Nothing. |
| 8. Slash commands | The /hero: commands in Claude Code and the skills in Codex. | Type /hero:health in Claude Code to try one. |
| 9. Restart | Running 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 setupdoes.
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 setupneeds 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.
| Field | Meaning |
|---|---|
schema | hero.setup.composite-result.v1. |
status | ok or error. |
reason_code | Why it isn't ok, such as coverage_gap, no_agents_detected or adapter_not_installed. Empty when ok. |
exit_code | The exit code: 0 or 1. |
coverage | state (covered, gap or no_agents), covered, and one entry per agent in agents. |
session_memory | wired, and a detail line. |
adapters | Whether the slash command files match what setup installed: state is clean or not_installed, for example. |
setup, monitor_local_read | setup 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
| Code | Meaning | What to do |
|---|---|---|
0 | Done. For --check, every agent is connected. For access, the machine is active. | Nothing. |
1 | A 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, refused | Refused, 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 applied | Partly 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. |
3 | Setup 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. |
| Error | Cause | Fix |
|---|---|---|
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 reachable | The 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 --check | In 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 rules | You 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
| Name | Kind | Purpose |
|---|---|---|
~/.claude/settings.json | Your Claude Code settings, changed | Setup sets ANTHROPIC_BASE_URL and adds 5 hook entries. |
~/.codex/config.toml | Your Codex settings, changed | Setup adds a model provider, OPENAI_BASE_URL for shells Codex starts, and Codex's approval of the hooks. |
~/.codex/hooks.json | Your Codex hooks, changed | Setup adds 6 hook entries, or 5 before Codex 0.114.0. |
<file>.hero-backup-<time> | Copy, written | Each file as it was before setup or undo changed it, beside the file. |
~/.claude/commands/hero/ | Folder, written | The 12 slash commands. |
~/.agents/skills, ~/.codex/skills | Folders, written | The 12 Codex skills. |
HERO_PROXY_PORT | Environment variable | The port in the default --proxy address. |
EKAMYTH_INSTALL_NO_SERVICE=1 | Environment variable | Skips the daily job that keeps your rules in sync. |
HERO_BRAIN_SESSION_MEMORY=off | Environment variable | Stops adding your saved memory at session start. |
HERO_CODIFY_ENFORCE=off | Environment variable, in the agent's environment | Stops 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
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Agents | Setup connects Claude Code and Codex. Gemini CLI isn't connected. | No | None. |
| Agent versions | Codex's end-of-turn hook needs Codex 0.114.0 or later. | No | Update Codex. |
| Earlier Codex conversations | Setup can't always tell whether conversations started before setup still go straight to OpenAI. | No | Setup says so in its output when it can't tell. |
| Undo and activation | --undo also drops this machine's activation. | No | Get 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. | No | Run them yourself. |
| Model gateway down during setup | Setup never points an agent at a model gateway that isn't answering. It installs the hooks and slash commands, and exits 1. | No | Start the model gateway, then run hero setup again. |
| Setup before activation | On a machine that isn't active yet, hero setup can exit with an error that tells you to run hero setup again. | No | Run hero setup redeem <Install id> instead. |
| Rules read by setup | Rules that only hero setup picked up are listed but not enforced. | No | Run hero init CLAUDE.md (or AGENTS.md) in your project after writing a rule. |
| User-level rule files | Rules in ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md aren't enforced. | No | Put rules you need enforced in the project's CLAUDE.md or AGENTS.md. |
| Activation after your access ends | This machine's activation isn't checked again with Ekamyth after it's written. | No | None. |
| Your own edits | Undo leaves a model route you repointed, a hook you wrapped and a slash command you edited, and reports each. | No | Remove those by hand if you want them gone. |
Commands related to hero setup
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.