Settings and environment variables
The files you edit and the environment variables you set to change how Ekamyth Agent OS behaves on your machine.
Settings files you edit
| File | What it's for | How to change it |
|---|---|---|
Your rules file, such as CLAUDE.md | The rules you want Agent OS to check. Any path. | Edit it, then run hero init <file>. Agent OS never edits it. |
~/.hero/govern.json | Your action policy: what Agent OS allows, refuses or holds for tool calls. | hero govern init writes a starting file; hero govern add adds a rule. A file written by hero govern init has pack, posture, derived_from, capabilities (each action's scope and stakes), dangerous, trust_ledger and autonomy_policy (flag_after and block_after). Stakes are low, moderate, high, critical or unknown. It can also hold a data_policy section. This isn't a closed schema, so don't add fields of your own. |
| Your Brain files | What session memory gives your agent. | See hero brain. |
| Your rates file | Your own invoiced prices, used instead of public list prices. | Point HERO_BILLING_RATES at it, and check it with hero efficiency billing <path>. The file is a JSON object that maps a model id to its rates. Give each rate in dollars per million tokens as in_per_mtok, out_per_mtok, cache_read_per_mtok, cache_creation_per_mtok and cache_creation_1h_per_mtok, or per token as in_usd_per_token, out_usd_per_token, cache_read_usd_per_token, cache_creation_usd_per_token and cache_creation_1h_usd_per_token. If both are present, the per-million value wins. Prices must be finite, not negative, and at most 1,000,000 dollars per million tokens. A price class you leave out stays unpriced, and an entry with no recognised price is ignored. vendor is optional. |
~/.hero is the default Agent OS folder. HERO_HOME moves it. For the files Agent OS writes there itself, see Data files.
Environment variables
| Variable | What it does | Values | Default |
|---|---|---|---|
HERO_HOME | Where Agent OS keeps its data. | A folder path | ~/.hero |
HERO_PROXY_PORT | The model gateway's port, for every Agent OS command. | 1 to 65535. Anything else falls back to 8081. | The port recorded at install, else 8081 |
HERO_PORTAL_PORT | The Portal's port. hero portal --port wins over it. | 1 to 65535 | 7878 |
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_CODIFY_ENFORCE | Stops your rules from refusing tool calls. Matching calls are recorded instead, and the change is recorded too. | 0, off, false or no | Unset: rules follow the enforcement setting. |
HERO_BRAIN_SESSION_MEMORY | Turns off session memory at session start. | off | Unset: on |
HERO_BRAIN_CAPTURE_OFF | Turns off saving facts from prompts that start "Remember that". | 1 | Unset: on |
HERO_BEACON | Turns off the anonymous usage heartbeat. 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. | off, 0, false or no | Unset: on |
HERO_LEARNED_ROUTING | Turns off the learned-routing plan check and policy pull, two of the flows hero privacy lists. | off, 0, false or no | Unset: on |
HERO_MCP | Turns off hero mcp serving and the MCP wrapper. | off, 0 or false | Unset: on |
HERO_BILLING_RATES | The path to your rates file. | A file path | Unset: public list prices |
HERO_METER_RETENTION_DAYS | How many days of individual model-call records to keep in meter.jsonl. Older records are archived when hero prune runs, not deleted. | A whole number. Below 1 counts as 1. | 90 |
HERO_ACTIVITY_RETENTION_DAYS | How many days of session records hero prune keeps before it archives them. | A whole number, 14 or more. A lower value, or one that isn't a whole number, is refused, and 14 applies. | 14 |
HERO_TRACE_LEVEL | How much each session record keeps. | off, summary or full | full |
HERO_KILL, HERO_MAX_CALLS | Stop every model call, or cap them. | HERO_KILL: 1, true or yes. HERO_MAX_CALLS: a whole number. See Stop or undo Agent OS. | Unset |
The model gateway also reads HERO_MAX_BODY, HERO_PROXY_TIMEOUT and HERO_PROXY_STREAM_TIMEOUT; see Model gateway variables.
These are the variables a customer sets. Agent OS reads other HERO_ variables for its own services and tests; they aren't supported settings and can change without notice.
Agent settings that hero setup writes
These are in your agents' own files. Read them to see where your agent sends model calls. See Model gateway address for the values.
| Agent | File | Setting |
|---|---|---|
| Claude Code | ~/.claude/settings.json | env.ANTHROPIC_BASE_URL, plus the Agent OS hook entries |
| Codex | ~/.codex/config.toml, or under CODEX_HOME | model_provider, the [model_providers.hero_runtime] table, and OPENAI_BASE_URL under [shell_environment_policy.set] |
hero setup --undo takes out only the values setup wrote, and puts back a value it replaced.
How to set a variable
For one command, put it before the command:
HERO_BEACON=off hero status
The model gateway, the scheduler and the Portal run as background services, and read their variables when they start.
What your agent can't change
Your agent can't make a lasting change to the variables that switch off your rules, such as HERO_CODIFY_ENFORCE or HERO_HOME: writing one into a shell start-up file or a service definition is refused. Setting one inside a single tool call has no effect on the hooks. Your agent also can't edit Agent OS's own settings files, such as govern.json. Only you can, from your own terminal. See How Governance works.
Related
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.