Model gateway address
The address and port your agents send model calls to, the model gateway's HTTP endpoints, the health check that tells you it's up, and the variables it reads.
The model gateway address
http://127.0.0.1:<port>
The port is HERO_PROXY_PORT if set, else the port recorded at install, else 8081. A HERO_PROXY_PORT outside 1 to 65535 falls back to 8081. hero proxy --install-service records the port in ~/.hero/proxy.json. Every Ekamyth Agent OS command uses the same port. For starting and stopping it, see hero proxy.
The model gateway listens on 127.0.0.1 only, so nothing else on your network can reach it. hero proxy --expose binds it to every network interface instead; use it only when you mean to.
Other local ports
| Service | Address | Change it with |
|---|---|---|
| Model gateway | http://127.0.0.1:8081 | HERO_PROXY_PORT, or hero proxy --port <port> |
| Portal (Monitor) | http://127.0.0.1:7878 | hero portal --port <port>, or HERO_PORTAL_PORT |
Endpoints
Your agent calls the model-call endpoints. Agent OS checks, routes and meters each call, then sends it to your provider. Any other path answers HTTP 404 with {"error":"not found"}.
| Method and path | Used by | What it does |
|---|---|---|
POST /v1/messages | Claude Code | An Anthropic Messages model call. A query string, such as ?beta=true, is accepted. |
POST /v1/responses | Codex | An OpenAI Responses model call. /responses without /v1 is treated the same. |
POST /v1/chat/completions | OpenAI-compatible clients | An OpenAI Chat Completions model call. |
POST /v1beta/models/<model>:generateContent, :streamGenerateContent | Gemini-compatible clients | A Gemini model call. |
POST /v1/messages/count_tokens, GET /v1/models, GET /v1/responses/<id>, POST /v1/responses/<id>/cancel | Claude Code, Codex | Passed to your provider as they are. These aren't model calls, so they aren't routed or metered. |
GET /healthz | You, hero status, the installer | The health check. See below. |
GET /readyz/codex, GET /readyz/native-session, GET /quota, GET /v1/budgets/effective | Agent OS | Readiness, quota and budget reads for Agent OS's own use. Their output isn't a supported API and can change. |
A request body larger than HERO_MAX_BODY (32 MiB by default) is refused with HTTP 413 and {"error":"request body too large"}, before it's read.
The address your agents use
| Agent | Setting | Value, on the default port |
|---|---|---|
| Claude Code | ANTHROPIC_BASE_URL | http://127.0.0.1:8081 |
| Codex | OPENAI_BASE_URL, and the base_url of [model_providers.hero_runtime] | http://127.0.0.1:8081/v1 |
hero setup writes these, and hero run sets them for one launch. Claude Code takes the bare address; Codex needs /v1 on the end.
The model gateway health check
curl -si http://127.0.0.1:8081/healthz
A GET with no body or credential. It always answers HTTP 200 while the model gateway runs; the body says whether it's healthy.
Example output. The format is the command's; the numbers are examples.
{"ok":true}
How to read the health check
| Field or header | Meaning |
|---|---|
| HTTP status | Always 200 while the model gateway runs. Read ok for its health. |
ok | true when the model gateway is serving. false when a provider's recent calls all failed, or requests are arriving and none succeeds. |
providers_down | Present when ok is false because of a provider: the providers whose recent calls all failed. |
requests_stalled, reason | Present when requests are arriving and none succeeds. reason reads requests arriving, none succeeding. |
Server: hero-proxy header | The answer came from an Agent OS model gateway. |
x-hero-install header | An opaque fingerprint of this install, so Agent OS can tell your model gateway from another account's on the same machine. |
When the health check fails
| What you see | Cause | What to do |
|---|---|---|
curl can't connect | The model gateway isn't running on that port. | Run hero status and follow its proxy row. |
"ok":false | A provider is failing, or calls are stuck. | Run hero status and follow its proxy row. |
No x-hero-install header | Something other than this install's model gateway answers on the port. | Run hero status --details. |
Model gateway variables
The model gateway reads these when it starts. For the background service, set them where the service starts, then restart it.
| Variable | What it does | Values | Default |
|---|---|---|---|
HERO_PROXY_PORT | The model gateway's port, for every Agent OS command. | 1 to 65535 | The port recorded at install, else 8081 |
HERO_ROUTE | Turns routing off or on, over the choice stored on this machine. | 0, false, no or off turn it off. Any other value turns it on. | Unset: the stored choice, else on |
HERO_KILL | Refuses every model call before it reaches your provider. | 1, true or yes | Unset |
HERO_MAX_CALLS | Caps model calls. See Stop or undo Agent OS. | A whole number | Unset: no cap |
HERO_MAX_BODY | The largest request body the model gateway accepts, in bytes. | A whole number | 33554432 (32 MiB) |
HERO_PROXY_TIMEOUT | How long a call that isn't streamed waits for your provider, in seconds. | A positive number. Anything else falls back to the default. | 60 |
HERO_PROXY_STREAM_TIMEOUT | How long a streamed call waits for its first byte from your provider, in seconds. It doesn't limit how long the stream runs. | A positive number. Anything else falls back to the default. | 120 |
For the variables every Agent OS command reads, see Settings and environment variables.
Related
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.