Ekamyth Agent OS docs
Standard OS / Services and devices

hero proxy

Starts and manages the model gateway, which your agents' model calls pass through on your machine.

What hero proxy does

It answers one question: is the model gateway running, and how do I start, stop or restart it? The install line starts the model gateway as a background service.

The model gateway carries model calls only. Your agent's tool calls reach Ekamyth Agent OS through its hooks. See What each connection covers.

Synopsis for hero proxy

hero proxy [--port <port>]
hero proxy --install-service [--port <port>]
hero proxy --uninstall-service
hero proxy --service-status [--port <port>]
hero proxy --restart-service [--config-changed]
hero proxy --restart-status <path>
hero proxy --help

With no option, it starts the model gateway in your terminal and keeps it running until you stop it.

Subcommands of hero proxy

Each form is chosen by an option.

FormWhat it doesReads or changes
(none)Starts the model gateway in this terminal. See Example 1.Changes
--install-serviceInstalls and starts the model gateway as a background service that restarts after a crash: launchd on Mac, systemd --user on Linux. Saves the port for later commands.Changes
--uninstall-serviceStops and removes the background service. See Example 4.Changes
--service-statusPrints one line: whether the background service is installed and running, and whether it answers.Reads
--restart-serviceSchedules a restart of the background service that waits for the process that asked for it to exit, so a call in progress isn't cut off. See Example 3.Changes
--restart-statusReads the receipt of a scheduled restart.Reads
--helpThis command's help. Same as -h, help and hero help proxy.Reads

Arguments for hero proxy

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
--port <port>IntegerNoHERO_PROXY_PORT, else the port saved by --install-service, else 80811 to 65535The port to start on, install the service on, or check. Applies to the start, --install-service, --service-status and --restart-service.
--config-changedFlagNoOffWith --restart-service only: the restart also reloads the service's environment, so a variable you changed takes effect.
<path>File pathYes, for --restart-statusThe request_path that --restart-service printedThe restart receipt to read.

hero proxy has no --json option. It's refused as an unknown option.

How the model gateway handles a call

Your agent sends its model call to the model gateway on your machine. The model gateway sends it on to your provider and returns the answer. On the way, Agent OS can route the call to a different model, which is on by default, and records the call with no prompt or response text. For the full picture, see How Agent OS connects to Claude Code and Codex.

Get started with hero proxy

Before you start: Agent OS is installed and this machine is active. The install line normally starts the model gateway for you.

  1. Check the model gateway with hero status, and read its proxy row.

    hero status

    You should see running on the proxy row. See How to read hero status output.

  2. Check that it answers.

    curl -s http://127.0.0.1:8081/healthz

    You should see {"ok":true}. If you use another port, put it in place of 8081.

  3. If the proxy row says not running, install and start the service.

    hero proxy --install-service

    This command will:

    • Write the service file and load it, so the model gateway starts now and restarts after a crash.
    • Save the port, so later hero commands use the same one.

    You should see the installed: line and a stop: line naming hero proxy --uninstall-service.

  4. Check again.

    hero status

    You should see running on the proxy row. If your agents aren't connected, run hero setup.

To undo step 3, run hero proxy --uninstall-service. While the model gateway is stopped, model calls from your connected agents fail. See Example 4.

Example output of hero proxy

Checking the background service

hero proxy --service-status

To check that the model gateway is healthy, use hero status instead. See Limits.

Installing the background service on Linux

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

Paths shortened to ~.

On Mac, the lines are installed:, loaded:, logs: and stop:, for ~/Library/LaunchAgents/com.ekamyth.hero-proxy.plist.

How to read hero proxy output

LineWhat it meansWhat to do
The --service-status lineWhen the service runs, the line names its process, then ready or not ready, then two checks and the address. /healthz=200 means the model gateway answers. /readyz/codex reports whether a Codex session is ready. ready needs both, so with no Codex session the line says not ready even when the model gateway works. installed (stopped) or installed (not loaded): the service file exists, but it isn't running. not installed: there's no background service.To check health, use hero status. Stopped or not installed: run hero proxy --install-service.
2. installed:, enabled: or loaded:The service file it wrote and the command it ran to start it.Nothing.
3. refreshed:On Linux, a service that was already running now runs this version of Agent OS.Nothing.
4. logs:Where to read the model gateway's log.Read it when the model gateway won't start. Each request's line holds no prompt, response, key or token.

More hero proxy examples

Example 1. To run the model gateway in a terminal

hero proxy

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

Excerpt: the lines after the start checks. A … marks lines left out.

hero proxy listening on http://127.0.0.1:8081  (GET /healthz to check · POST /v1/messages → anthropic · /v1/chat/completions + /v1/responses → openai · /openai/deployments/* → azure · /v1beta/models/* → gemini)

point your agent here:
  Claude Code:  export ANTHROPIC_BASE_URL=http://127.0.0.1:8081
  Codex/OpenAI: export OPENAI_BASE_URL=http://127.0.0.1:8081/v1

  …

It keeps running until you press Ctrl-C, which prints hero proxy stopped. The point your agent here lines are for an agent you connect by hand; hero setup does it for you. If this home's model gateway already runs on that port, it prints hero proxy: this home's Agent OS already runs on 127.0.0.1:8081 and exits 0.

Example 2. To use another port

hero proxy --install-service --port 8090
hero setup

These commands will:

  • Install the background service on port 8090 and save that port.
  • Point your agents at the model gateway on the saved port, after asking.

Check it with hero status. Its proxy row checks the address your agents use.

Example 3. To restart the model gateway after changing its environment

hero proxy --restart-service --config-changed

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

{"request_id": "rst-0f3a…", "request_path": "~/.hero/proxy-restarts/rst-0f3a….json", "status": "scheduled", "wait_pid": 12345}

The restart waits for the process that asked for it to exit. Run from your own terminal, that's the shell, so the restart happens when you close that terminal window. It waits for up to 2 hours. To follow it, pass the request_path to --restart-status, which prints the receipt with a status of scheduled, executing, succeeded or failed. To restart at once instead, run hero proxy --install-service.

Example 4. To stop and remove the background service

hero proxy --uninstall-service

This command will:

  • Stop the model gateway and remove its service file.

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

Paths shortened to ~.

disabled and removed ~/.config/systemd/user/hero-proxy.service

On Mac it prints unloaded and removed with the plist path. If your agents are still connected, their model calls fail until the model gateway runs again. To take Agent OS out of your agents first, run hero setup --undo.

Example 5. To check the model gateway answers, and refuses web pages

curl -s http://127.0.0.1:8081/healthz
curl -s -H 'Origin: https://example.com' http://127.0.0.1:8081/healthz

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

{"ok":true}
{"error": "request refused: browser origins may not use this proxy", "reason": "refused_browser_origin"}

The first is the health check. The second shows a request with a browser origin refused with 403.

Exit codes and errors for hero proxy

CodeMeaningWhat to do
0Done: help, a start that ran and was stopped, a start that found the model gateway already running, --service-status, or a restart scheduled.Nothing.
1The start was refused or failed, or installing, removing or restarting the service was refused.Read the message. See the errors below.
2The command line was wrong, or a restart receipt isn't valid.Check the synopsis.
ErrorCauseFix
hero proxy: port 8081 is already in use — is another hero proxy running?
check: curl -s localhost:8081/healthz · pick another: hero proxy --port 8082
Something that isn't this home's model gateway holds the port.Run the check: command, or pick another port.
hero proxy: install-service failed — proxy service install: not done — Ekamyth is not active on this machine yet (next step: `hero setup redeem <Install id>` from your invitation)This machine isn't active.Activate it. See Activation.
hero proxy: hero proxy refusing to start without a provider API key; set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY, …The machine isn't active, and no provider key is set.Activate this machine, so the model gateway uses your agent's own sign-in, or set a provider key.
hero proxy: unknown option '--json' — see: hero proxy --helpAn option hero proxy doesn't have.Check the synopsis.
hero proxy: --port must be a number from 1 to 65535, got 'abc'The port isn't a number from 1 to 65535.Give a valid port.
hero proxy: --port needs a value — see: hero proxy --help--port or --restart-status has no value.Add the value.
hero proxy: --config-changed requires --restart-service--config-changed used on its own.Use it with --restart-service.
hero proxy: restart-status failed — invalid proxy restart receipt: expected restart schema, request_id and statusThe file isn't a restart receipt.Pass the request_path that --restart-service printed.
hero proxy: restart-status failed — [Errno 2] No such file or directory: '<path>'The receipt file isn't there.Check the path.
hero proxy: install-service failed — hero proxy: refusing to touch the per-user service 'hero-proxy.service' from a foreign HOME. …HOME isn't your account's real home. The service is registered per user.Run it with your normal HOME.

Files and environment for hero proxy

NameKindPurpose
~/Library/LaunchAgents/com.ekamyth.hero-proxy.plistService file, MacWritten by --install-service, removed by --uninstall-service.
~/.config/systemd/user/hero-proxy.serviceService file, LinuxWritten by --install-service, removed by --uninstall-service.
The logs: lineLog--install-service prints where the log is. On Linux, journalctl --user -u hero-proxy.service -f.
HERO_PROXY_PORTEnvironment variableThe port when --port isn't given. A value that isn't a valid port falls back to 8081.
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEYEnvironment variablesProvider keys. Not needed on an active machine that uses your agent's own sign-in.
HERO_ROUTE=0Environment variableKeeps every call on the model your agent asked for. Set it in the model gateway's environment, then start or restart the model gateway for it to take effect.
HERO_BEACON=offEnvironment variableUsage reporting is on by default. It sends metadata only — never content, prompts or responses — at most once a day. Turn it off with HERO_BEACON=off. The model gateway asks to send it when it starts, not on every call. Jobs run by hero schedule can trigger it too.

Limits of hero proxy

LimitBehaviourCan you change it?What to do
What it carriesModel calls only. hero proxy --help says every agent tool call goes through it; tool calls reach Agent OS through hooks.NoSee What each connection covers.
--service-statusIt reports the background service only, so it says not installed while you run the model gateway in a terminal. With no --port and no service installed, it checks port 8081, even if HERO_PROXY_PORT is set.YesCheck the model gateway with hero status, or with curl as in Example 5.
--service-status without a Codex sessionThe line can say not ready when no Codex session is open, even when the model gateway works.NoUse hero status and its proxy row as the health check.
--restart-serviceThe restart waits for the process that asked for it to exit.NoTo restart at once, run hero proxy --install-service.
After a rollbackSwitching your hero command back doesn't move a running model gateway.NoRun hero proxy --install-service. See Roll back.
Your home folderInstalling, removing and restarting the service work only from your account's real home.NoRun them with your normal HOME.
While the service restartsThe service restarts itself after a crash.NoRun hero status; its proxy row shows whether the model gateway answers.
Refused connectionsA connection the model gateway refused can be labelled as a 502 upstream error.NoCheck hero status and its proxy row before treating it as a provider error.
Linux, at logoutThe background service can stop when you log out.NoRun hero proxy --service-status to see whether it is running.

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