Ekamyth Agent OS docs
Reference / Model gateway

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

ServiceAddressChange it with
Model gatewayhttp://127.0.0.1:8081HERO_PROXY_PORT, or hero proxy --port <port>
Portal (Monitor)http://127.0.0.1:7878hero 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 pathUsed byWhat it does
POST /v1/messagesClaude CodeAn Anthropic Messages model call. A query string, such as ?beta=true, is accepted.
POST /v1/responsesCodexAn OpenAI Responses model call. /responses without /v1 is treated the same.
POST /v1/chat/completionsOpenAI-compatible clientsAn OpenAI Chat Completions model call.
POST /v1beta/models/<model>:generateContent, :streamGenerateContentGemini-compatible clientsA Gemini model call.
POST /v1/messages/count_tokens, GET /v1/models, GET /v1/responses/<id>, POST /v1/responses/<id>/cancelClaude Code, CodexPassed to your provider as they are. These aren't model calls, so they aren't routed or metered.
GET /healthzYou, hero status, the installerThe health check. See below.
GET /readyz/codex, GET /readyz/native-session, GET /quota, GET /v1/budgets/effectiveAgent OSReadiness, 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

AgentSettingValue, on the default port
Claude CodeANTHROPIC_BASE_URLhttp://127.0.0.1:8081
CodexOPENAI_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 headerMeaning
HTTP statusAlways 200 while the model gateway runs. Read ok for its health.
oktrue when the model gateway is serving. false when a provider's recent calls all failed, or requests are arriving and none succeeds.
providers_downPresent when ok is false because of a provider: the providers whose recent calls all failed.
requests_stalled, reasonPresent when requests are arriving and none succeeds. reason reads requests arriving, none succeeding.
Server: hero-proxy headerThe answer came from an Agent OS model gateway.
x-hero-install headerAn 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 seeCauseWhat to do
curl can't connectThe model gateway isn't running on that port.Run hero status and follow its proxy row.
"ok":falseA provider is failing, or calls are stuck.Run hero status and follow its proxy row.
No x-hero-install headerSomething 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.

VariableWhat it doesValuesDefault
HERO_PROXY_PORTThe model gateway's port, for every Agent OS command.1 to 65535The port recorded at install, else 8081
HERO_ROUTETurns 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_KILLRefuses every model call before it reaches your provider.1, true or yesUnset
HERO_MAX_CALLSCaps model calls. See Stop or undo Agent OS.A whole numberUnset: no cap
HERO_MAX_BODYThe largest request body the model gateway accepts, in bytes.A whole number33554432 (32 MiB)
HERO_PROXY_TIMEOUTHow 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_TIMEOUTHow 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.

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