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.
- Use it when the model gateway isn't running, you want another port, or you changed its environment and need a restart.
- Use something else when you want to check the whole install (
hero status), connect your agents to the model gateway (hero setup), or see which model served each call (hero route). - Reads or changes:
--service-statusand--restart-statusonly read. The other forms start, install, restart or remove the model gateway.
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.
| Form | What it does | Reads or changes |
|---|---|---|
| (none) | Starts the model gateway in this terminal. See Example 1. | Changes |
--install-service | Installs 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-service | Stops and removes the background service. See Example 4. | Changes |
--service-status | Prints one line: whether the background service is installed and running, and whether it answers. | Reads |
--restart-service | Schedules 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-status | Reads the receipt of a scheduled restart. | Reads |
--help | This command's help. Same as -h, help and hero help proxy. | Reads |
Arguments for hero proxy
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--port <port> | Integer | No | HERO_PROXY_PORT, else the port saved by --install-service, else 8081 | 1 to 65535 | The port to start on, install the service on, or check. Applies to the start, --install-service, --service-status and --restart-service. |
--config-changed | Flag | No | Off | With --restart-service only: the restart also reloads the service's environment, so a variable you changed takes effect. | |
<path> | File path | Yes, for --restart-status | The request_path that --restart-service printed | The 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.
- It listens only on your machine, on
127.0.0.1. - It refuses requests from web pages. A request with a browser origin gets
403, so a web page can't spend your keys through it. - It takes Anthropic, OpenAI, Azure OpenAI and Gemini calls, as its start line lists.
- It uses your own credentials. On an active machine it starts without a key, and calls use your agent's own sign-in. A provider key in its environment, such as
ANTHROPIC_API_KEY, also works. - One per home. If this home's model gateway already runs on that port, a second start says so and exits.
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.
Check the model gateway with
hero status, and read itsproxyrow.hero statusYou should see
runningon theproxyrow. See How to readhero statusoutput.Check that it answers.
curl -s http://127.0.0.1:8081/healthzYou should see
{"ok":true}. If you use another port, put it in place of8081.If the
proxyrow saysnot running, install and start the service.hero proxy --install-serviceThis 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
herocommands use the same one.
You should see the
installed:line and astop:line naminghero proxy --uninstall-service.Check again.
hero statusYou should see
runningon theproxyrow. If your agents aren't connected, runhero 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
| Line | What it means | What to do |
|---|---|---|
The --service-status line | When 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
| Code | Meaning | What to do |
|---|---|---|
0 | Done: help, a start that ran and was stopped, a start that found the model gateway already running, --service-status, or a restart scheduled. | Nothing. |
1 | The start was refused or failed, or installing, removing or restarting the service was refused. | Read the message. See the errors below. |
2 | The command line was wrong, or a restart receipt isn't valid. | Check the synopsis. |
| Error | Cause | Fix |
|---|---|---|
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 --help | An 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 status | The 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
| Name | Kind | Purpose |
|---|---|---|
~/Library/LaunchAgents/com.ekamyth.hero-proxy.plist | Service file, Mac | Written by --install-service, removed by --uninstall-service. |
~/.config/systemd/user/hero-proxy.service | Service file, Linux | Written by --install-service, removed by --uninstall-service. |
The logs: line | Log | --install-service prints where the log is. On Linux, journalctl --user -u hero-proxy.service -f. |
HERO_PROXY_PORT | Environment variable | The 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_KEY | Environment variables | Provider keys. Not needed on an active machine that uses your agent's own sign-in. |
HERO_ROUTE=0 | Environment variable | Keeps 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=off | Environment variable | Usage 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
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| What it carries | Model calls only. hero proxy --help says every agent tool call goes through it; tool calls reach Agent OS through hooks. | No | See What each connection covers. |
--service-status | It 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. | Yes | Check the model gateway with hero status, or with curl as in Example 5. |
--service-status without a Codex session | The line can say not ready when no Codex session is open, even when the model gateway works. | No | Use hero status and its proxy row as the health check. |
--restart-service | The restart waits for the process that asked for it to exit. | No | To restart at once, run hero proxy --install-service. |
| After a rollback | Switching your hero command back doesn't move a running model gateway. | No | Run hero proxy --install-service. See Roll back. |
| Your home folder | Installing, removing and restarting the service work only from your account's real home. | No | Run them with your normal HOME. |
| While the service restarts | The service restarts itself after a crash. | No | Run hero status; its proxy row shows whether the model gateway answers. |
| Refused connections | A connection the model gateway refused can be labelled as a 502 upstream error. | No | Check hero status and its proxy row before treating it as a provider error. |
| Linux, at logout | The background service can stop when you log out. | No | Run hero proxy --service-status to see whether it is running. |
Commands related to hero proxy
proxy row checks the model gateway.
hero routeWhich model served each call.
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.