Ekamyth Agent OS docs
Standard OS / Processes

hero run

Launches your agent with its model calls going through the model gateway on your machine. hero claude and hero codex are the same command for Claude Code and Codex.

What hero run does

It starts the agent command you give it, with that agent's model address set to the model gateway on your machine. If the model gateway isn't running on its port, hero run starts one for as long as the agent runs. hero claude runs Claude Code this way and hero codex runs Codex.

When to use hero run

After hero setup, a plain claude or codex uses the model gateway through the settings setup wrote. Use hero claude or hero codex when an agent's model calls don't reach Ekamyth Agent OS that way:

To see which agents reach the model gateway, run hero route census.

Use something else when you want every new session connected without a special command (hero setup), or the model gateway running all the time (hero proxy --install-service).

Synopsis for hero run

hero claude [--port <port>] [--host <host>] [<claude-argument> ...]
hero codex [--port <port>] [--host <host>] [<codex-argument> ...]
hero run [--port <port>] [--host <host>] <agent-command> [<agent-argument> ...]
hero run --help

Only --port and --host placed first belong to hero run. Everything from the first other word on is passed to the agent unchanged, so hero claude --port 9000 -p "hi" moves the model gateway and passes -p "hi" to Claude Code.

Subcommands of hero run

None. The word after hero run is the command it launches.

Arguments for hero run

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
<agent-command>CommandYes, for hero runclaude for hero claude, codex for hero codexAny command on your PATHThe agent to launch.
<agent-argument> ...TextNoNoneAnything the agent acceptsPassed to the agent as typed.
--port <port>NumberNoHERO_PROXY_PORT, else the port recorded at install, else 8081A whole numberThe model gateway port to use or start. Must come before the agent command.
--host <host>Host name or addressNo127.0.0.1Host name or addressThe address the model gateway listens on. Must come before the agent command.
--help, -hFlagNoOffWith hero run alone, prints the help. After an agent command, as in hero run claude --help, it goes to the agent and you see the agent's own help.

How hero run launches your agent

  1. Finds the model gateway port, the same way every Agent OS command does: --port, then HERO_PROXY_PORT, then the port recorded at install, then 8081.
  2. Starts or joins the model gateway. If nothing is listening on that port, it starts the model gateway inside this command. If this install's model gateway already answers there, it uses that one. If something else holds the port, such as another install's model gateway, it refuses and names a free port to try.
  3. Launches the agent with ANTHROPIC_BASE_URL set to the model gateway, and OPENAI_BASE_URL set to the model gateway with /v1. For Codex it also passes the settings that point Codex's own model client at the model gateway, for this launch only.
  4. Leaves your own Codex provider alone. If your Codex configuration, profile or command line already names a model provider of its own, or you pass --oss, hero codex keeps your setting, says this session isn't routed, and still launches Codex.
  5. Opens a session (hero claude and hero codex). Before the agent starts, the session gets its own short-lived session key, passed in the agent's own header setting: ANTHROPIC_CUSTOM_HEADERS for Claude Code, env_http_headers for Codex. It expires within 24 hours, and Agent OS revokes it when the session closes. When Codex keeps its own provider, no key is made and the session is recorded as not covered.
  6. Stops when the agent exits. A model gateway that hero run started stops with it, and hero run exits with the agent's exit code. A model gateway that was already running keeps running.

Only the Anthropic and OpenAI model addresses are set. Another provider called from the same agent keeps its own address, and the launch line says so. Tool calls are checked by the hooks that hero setup installs in your agent's settings; hero run doesn't change them. See How Agent OS connects.

Get started with hero run

Before you start: Agent OS is installed and this machine is active. hero run changes no settings file, so there's nothing to undo afterwards.

  1. Start Claude Code through the model gateway.

    hero claude

    You should see one launch line naming the model gateway's address, then Claude Code starts as usual.

  2. Or start Codex.

    hero codex

    You should see the launch line, then Codex starts. If your Codex configuration names its own provider, a line says that this session isn't routed.

  3. In another terminal, check which agents reach the model gateway.

    hero route census

How to read hero run output

LineWhat it meansWhat to do
Launch line, starting hero: proxy on http://127.0.0.1:<port> → launchinghero run started the model gateway on that address and launched the agent. The words in brackets name the agents whose model calls go through it, such as claude, codex governed in-path (other providers keep their own endpoints).Nothing.
Launch line, starting hero run: attaching to the hero proxy already running onThis install's model gateway was already running on that port, and the agent uses it.Nothing.
NOT governed in-path — no provider base URL was injected in the bracketsNo model address was set for this agent, so its model calls don't go through the model gateway.Use hero claude or hero codex, or point the agent at the address on Model gateway address.
hero codex: your Codex config uses <setting> "<value>" — left as it is, so this Codex session is not routed through Ekamyth RuntimeIf 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.

More hero run examples

Example 1. To pass arguments to Claude Code

hero claude -p "summarize this folder"

Everything after hero claude goes to Claude Code.

Example 2. To use a model gateway on another port

hero claude --port 8082

--port comes first. It uses or starts the model gateway on 8082 for this launch.

Example 3. To launch another agent command

hero run <agent-command> <agent-argument>

The command gets ANTHROPIC_BASE_URL and OPENAI_BASE_URL pointing at the model gateway. It gets no session key.

Example 4. To see the agent's own help

hero run claude --help

hero claude --help prints this command's help instead.

Exit codes and errors for hero run

CodeMeaningWhat to do
The agent's codeThe agent ran. hero run returns whatever the agent returned.Read the agent's own output.
1No agent command was given, or the port is held by something that isn't this install's model gateway.Name an agent, or use the port the message suggests.
2--port wasn't a number, or hero run --json was refused.Fix the argument.
69hero claude or hero codex refused before the agent started.Read the reason in the message.
127The agent command wasn't found.Install the agent, or check its name.

The messages, as the build prints them:

usage: hero run [--port N] [--host H] <agent-command...>   |   hero claude [claude-args...]   |   hero codex [codex-args...]
hero run: --port must be a number, got 'abc'
hero: command not found: <agent-command>
hero claude: launch refused — <code>: <detail>; no agent was started.

When the port is taken, the message names why, then two next steps:

hero run: <why> — free it, or run on your own port:
  pick a port: hero run --port <port+1> <agent-command…>
  check:       curl -si localhost:<port>/healthz

The reason is one of: a model gateway belonging to another install is on the port; something answers there but doesn't identify as your model gateway; your own model gateway holds the port but reports itself unhealthy; or the port is in use by something else.

Files and environment for hero run

NameKindPurpose
HERO_PROXY_PORTEnvironment variable, readThe model gateway port, when --port isn't given.
ANTHROPIC_BASE_URL, OPENAI_BASE_URLEnvironment variables, set for the agentThe model address the launched agent uses. Your shell keeps its own values.
ANTHROPIC_CUSTOM_HEADERS (Claude Code), env_http_headers (Codex)Agent header setting, set for the agentCarries the session key for hero claude and hero codex. Any program running as your user can read it while it's valid, as with your provider keys.
~/.codex/config.tomlYour Codex settings, readWhether Codex already names a provider of its own.

Limits of hero run

LimitBehaviourCan you change it?What to do
ProvidersOnly the Anthropic and OpenAI model addresses are set. Other providers called by the same agent keep their own addresses.NoNone.
Codex with your own providerIf your Codex settings name your own provider, Codex's model calls aren't routed through Agent OS. Agent OS still watches its tool calls.YesTo 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.
A model gateway started by hero runIt stops when the agent exits.NoKeep one running with hero proxy --install-service.
Two sessions at onceTwo hero run sessions can share one model gateway, with no warning.NoRun one at a time, or keep one model gateway running with hero proxy --install-service.
Plain claude or codexA session started without hero claude or hero codex gets no session key.NoLaunch with hero claude or hero codex.
Helphero claude --help shows this command's help, not Claude Code's.NoUse hero run claude --help.

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