Configuration

Karate Agent reads configuration from two surfaces: karate-agent.json for non-secret settings, and environment variables for secrets and the install directory.

karate-agent.json

Located at $KARATE_AGENT_HOME (defaults to the directory you run the jar from). Read once on dashboard startup. Flat schema:

{
  "port": 4444,
  "maxSessions": 10,
  "models": [
    "openrouter/anthropic/claude-sonnet-4-6",
    "openrouter/google/gemma-3-27b-it"
  ],
  "idleTimeout": 300,
  "hardTimeout": 1800
}

Key	Type	Purpose	Default
port	number	Dashboard HTTP port	4444
maxSessions	number	Concurrent worker containers allowed	10
models	string[]	Allowed LLM models. First is the default. Empty disables autonomous mode.	—
idleTimeout	number	Session idle timeout in seconds	300
hardTimeout	number	Session hard cap in seconds	1800

CLI flags override the JSON:

java -jar karate-agent.jar dashboard --port 5555 --max-sessions 25

Models — Bring Your Own LLM

The models array drives the model selector in the dashboard UI and the allowed-list for autonomous job submissions. Format: provider/modelId.

Prefix	Provider	API key env var
openrouter/	OpenRouter	OPENROUTER_API_KEY
anthropic/	Anthropic direct	ANTHROPIC_API_KEY
ollama/	Local Ollama (TODO)	(none)

Examples:

"models": [
  "openrouter/anthropic/claude-sonnet-4-6",
  "openrouter/google/gemma-3-27b-it",
  "anthropic/claude-haiku-4-5"
]

Empty models is allowed — autonomous mode is disabled, Live mode still works.

Environment variables

Variable	Purpose	Required
KARATE_AGENT_HOME	Install directory. Defaults to current directory.	No
OPENROUTER_API_KEY	OpenRouter API key	If using openrouter/
ANTHROPIC_API_KEY	Anthropic API key	If using anthropic/

The dashboard does not read API keys from karate-agent.json — they stay in the shell environment.

Startup validation

When the dashboard boots, it runs these checks in order:

1. License (blocking) — karate.lic must exist in $KARATE_AGENT_HOME and contain the agent entitlement. On failure, the dashboard prints the contact-sales URL and exits 1.
2. Worker image (blocking) — docker pull karatelabs/karate-agent:<version> runs synchronously. This also verifies Docker is installed and reachable.
3. LLM ping (warning) — if models is non-empty and the first model's API key is set, the dashboard sends a 1-token request. Failures are logged but don't block startup.

A missing API key or empty models is a warning, not an error — Live mode does not need an LLM.