Axis Configuration and Operations

Config File Loading

Axis auto-loads .env files on every command. Precedence (lowest to highest):

~/.eternum-agent/.env — global config (API keys, preferences). Auto-created on first run.
./.env (current directory) — local overrides for development or per-project settings.
Shell environment — export ANTHROPIC_API_KEY=... always wins over file values.

Values from higher-priority sources override lower ones. Shell env vars are never overwritten by file values. All runtime directories (~/.eternum-agent/data/, ~/.eternum-agent/.cartridge/) are auto-created on first run — no manual axis init required.

Core Environment Variables

Variable	Default	Purpose
`MODEL_PROVIDER`	`anthropic`	LLM provider (`anthropic`, `openai`, `openrouter`, `google`)
`MODEL_ID`	`claude-sonnet-4-5-20250929`	Model ID
`ANTHROPIC_API_KEY`	none	Required for Anthropic provider
`OPENAI_API_KEY`	none	Required for OpenAI provider
`CHAIN`	`slot`	Chain selection
`SLOT_NAME`	none	Auto-select discovered world
`GAME_NAME`	`eternum`	Session/game namespace
`TICK_INTERVAL_MS`	`60000`	Tick interval in ms
`LOOP_ENABLED`	`true`	Auto-start loop on launch
`ETERNUM_AGENT_HOME`	`~/.eternum-agent`	Runtime root
`DATA_DIR`	`$ETERNUM_AGENT_HOME/data`	Agent data root
`SESSION_BASE_PATH`	`$ETERNUM_AGENT_HOME/.cartridge`	Session/artifact root

Optional / Advanced Variables

Variable	Purpose
`RPC_URL`, `TORII_URL`, `WORLD_ADDRESS`	Manual world overrides (skip discovery)
`MANIFEST_PATH`	Explicit manifest path
`CHAIN_ID`	Override inferred chain id
`PRIVATE_KEY`, `ACCOUNT_ADDRESS`	Private-key auth mode
`MASTER_ADDRESS`, `MASTER_PRIVATE_KEY`	Optional auto top-up for non-mainnet fee token shortfalls
`CARTRIDGE_API_BASE`	Factory/discovery API base override

Runtime Directory

~/.eternum-agent/
├── data/
│   └── <world>/
│       ├── soul.md
│       ├── HEARTBEAT.md
│       └── tasks/
│           ├── game.md
│           ├── economy.md
│           ├── exploration.md
│           ├── combat.md
│           ├── priorities.md
│           └── learnings.md
└── .cartridge/
    └── <world>/
        ├── profile.json
        ├── manifest.json
        ├── policy.json
        ├── session.json
        ├── auth.json
        └── auth-qr.png

Runtime Config Updates (Headless)

Use POST /config with changes to update settings live.

Typical paths:

tickIntervalMs
loopEnabled
modelProvider
modelId
dataDir

Some backend fields (like world connection details) require restart in headless mode.

Diagnostics

Run doctor:

axis doctor

Common issues:

No worlds discovered: check network reachability and CARTRIDGE_API_BASE
--world is required for headless mode: pre-auth and set --world
Auth remains pending: complete approval or run axis auth <world> --redirect-url="..."
Password auth fails: verify username/password and that the account has a password credential on Cartridge
Session expired: re-run axis auth <world>