Aizen

Configure a custom endpoint for Aizen — a CLI agent that talks to any OpenAI-compatible endpoint (private gateway, internal proxy, LiteLLM, vLLM, Ollama, OpenRouter, Groq, DeepSeek, Anthropic...).

What is Aizen?

How Aizen talks to an endpoint

Aizen only needs an OpenAI-compatible endpoint exposing two paths:

GET {base_url}/models — model list (used during setup and by aizen models)
POST {base_url}/chat/completions — chat conversation and the agent loop
Authentication defaults to Authorization: Bearer <API key>

Most important: base_url must include the version segment

Three things to prepare

Field	Example	Note
Base URL	https://api.arzastore.com/v1	With http:// or https://, including the version path, no trailing slash
API key	sk-...	Your consumer key. For a local Ollama any value works, e.g. ollama
Model ID	claude-sonnet-4-5	Exactly the model name your endpoint advertises

Method 1 — Interactive setupRecommended

Run in your terminal:

aizen config

Or type /config (or /setup) directly inside an Aizen chat session.

The steps you will see

01Provider — the list includes OpenAI, Anthropic (Claude), OpenRouter, Groq, DeepSeek, Ollama (local) and a final Custom gateway option. Pick Custom gateway to enter your own URL.
02Base URL — enter the full URL including the version path. Aizen immediately probes it with GET {base}/models and reports the result.
03API key — Aizen verifies the key for real: if /models returns 200 without indicating anonymous access is allowed, Aizen additionally tries one POST {base}/chat/completions to surface 401/403 during setup rather than on your first real chat.
04Model & context — pick a model from the list it just fetched; if the endpoint publishes no list, enter the model ID manually. Configuration is saved after each step; press Esc or choose Done to exit.

The four probe results Aizen reports

Good — the model list was retrieved.

The endpoint is correct, it is just missing a key — this is fine, continue.

Wrong path. If the URL has no version segment, append /v1 and press Enter again.

Wrong host, DNS/TLS problem, firewall, or the service is not running.

Method 2 — aizen config set (for scripts)

aizen config set --base-url https://api.arzastore.com/v1 --api-key sk-xxxx --model claude-sonnet-4-5

Only the parameters you pass are changed; the rest is left as-is. Verify with:

aizen config show # show config, API key is always masked
aizen config path # print the config file path

Method 3 — Environment variables

Use this in CI, containers, or when you want to switch endpoints temporarily without writing to the file.

$env:AIZEN_BASE_URL = "https://api.arzastore.com/v1"
$env:AIZEN_API_KEY = "sk-xxxx"
$env:AIZEN_MODEL = "claude-sonnet-4-5"
aizen

export AIZEN_BASE_URL="https://api.arzastore.com/v1"
export AIZEN_API_KEY="sk-xxxx"
export AIZEN_MODEL="claude-sonnet-4-5"
aizen

Precedence order

Verify after configuring

aizen models # list models the endpoint advertises
aizen models --base-url https://api.arzastore.com/v1 --api-key sk-... # try another endpoint without saving
aizen chat -p "ping" # try one real chat turn

Configuration works

Configuration file

Path

Linux / macOS: ~/.aizen/cli-config.json
Windows: C:Users<tên>.aizencli-config.json

You can relocate the root directory with the AIZEN_HOME environment variable.

{
 "base_url": "https://api.arzastore.com/v1",
 "api_key": "sk-xxxx",
 "model": "claude-sonnet-4-5"
}

Notes

On Linux/macOS the file is written with mode 0600 (owner-readable only) and ~/.aizen with 0700. On Windows, permissions follow the user profile ACL.
If the file is corrupted (hand-edited with bad syntax), Aizen does not discard your data: it warns, falls back to defaults, and keeps a cli-config.json.bak copy before overwriting.
Prefer aizen config over hand-editing the JSON.

Advanced — multiple endpoints in one configuration

8.1. Per-role endpoints

You can run each role on a different gateway/model: a cheap model for chores, a strong model for hard work.

Role	Used for	CLI flags
summarizer	Summarizing when context fills up / session handoff	--summarizer-model--summarizer-base-url--summarizer-api-key-ref
subagent_default	Default model for sub-agents	--subagent-model--subagent-base-url--subagent-api-key-ref
oracle	Review pass before finishing (use a strong model)	--oracle-model--oracle-base-url--oracle-api-key-ref
apply	Reserved for the fast-apply model (currently config-only)	--apply-model--apply-base-url--apply-api-key-ref

aizen config set  --summarizer-model claude-haiku-4-5  --summarizer-base-url https://api.arzastore.com/v1  --summarizer-api-key-ref env:CHEAP_KEY

The same precedence applies per role: AIZEN_<ROLE>_MODEL / AIZEN_<ROLE>_BASE_URL / AIZEN_<ROLE>_API_KEY → config roles.<role>.* → the main endpoint. Example: AIZEN_ORACLE_BASE_URL. Pass an empty string to a flag to clear that setting.

Note on oracle

8.2. model → endpoint mapping

When a sub-agent is pinned to a specific model, Aizen consults this table to know which gateway that model lives on:

aizen config set --model-endpoint "claude-sonnet-4-5,base_url=https://api.arzastore.com/v1,api_key_ref=env:ARZASTORE_KEY"
aizen config set --model-endpoint "deepseek-chat,base_url=https://api.deepseek.com/v1,api_key_ref=env:DS_KEY"

The --model-endpoint flag can be repeated.
Pass "model,clear" (or just the model name with no fields) to remove an entry.
Matching env vars: AIZEN_MODEL_<UPPERCASED_MODEL>_BASE_URL and ..._API_KEY, where non-alphanumeric characters become _ — e.g. gpt-4o → AIZEN_MODEL_GPT_4O_BASE_URL. With no matching entry, the sub-agent only switches model name and keeps the parent process endpoint.

8.3. api_key_ref — keep keys off disk

env:VAR_NAME — recommended: the key is read from the environment at runtime and never stored in the config file.
A literal key string — still works, but the key is stored in cli-config.json.

Troubleshooting

Symptom	Common cause	Fix
no model list at {base}/models (404/405)	Base URL is missing the version path	Append /v1 (or /v1beta, /openai/v1... depending on the provider)
could not reach it: dns error	Wrong domain, or the machine cannot resolve DNS	Check URL spelling, VPN, firewall
could not reach it: connection refused	Internal service not running, or wrong port	For Ollama: check http://localhost:11434/v1 and the Ollama process
reachable (needs a key) then a key error	Wrong key, expired, or pasted incompletely	Create a new key and paste it in full
aizen models OK but chat returns 401	The gateway allows anonymous /models but not /chat/completions	Check the key's permissions on the gateway
config set ran but the old endpoint is still used	AIZEN_BASE_URL / AIZEN_API_KEY are overriding the file	Unset the environment variables or open a new terminal
Config corruption warning	JSON hand-edited with invalid syntax	Use the cli-config.json.bak copy, or re-run aizen config

Security recommendations

Prefer api_key_ref = env:VAR_NAME over writing the key into the file.
Do not commit cli-config.json to git, and do not share screenshots containing a key.
aizen config show always masks the key (first 6 characters and length only) — use it when you need to send your configuration to support.
Use separate keys per environment (dev, CI, production) so they can be revoked independently.

Appendix — Quick reference

Task	Command
Interactive configuration	aizen config
Set a custom endpoint	aizen config set --base-url <URL> --api-key <KEY> --model <ID>
View config (key masked)	aizen config show
Show config file path	aizen config path
List models	aizen models
Try an endpoint without saving	aizen models --base-url <URL> --api-key <KEY>
Temporary override	AIZEN_BASE_URL / AIZEN_API_KEY / AIZEN_MODEL