Configuration

APX uses two configuration layers — global (machine-local, never committed) and project-local (committed to the repo, no secrets). Commands at both layers use dotted-key syntax and are JSON-aware.

Global config — ~/.apx/config.json

The global config file is created on first run. It holds engine credentials, daemon settings, the super-agent model, voice, memory, and Telegram options.

Top-level structure

{
  "port": 7430,
  "host": "127.0.0.1",
  "log_level": "info",
  "user": {
    "language": "en",
    "locale": "",
    "timezone": ""
  },
  "super_agent": { ... },
  "engines": { ... },
  "memory": { ... },
  "voice": { ... },
  "telegram": { ... },
  "projects": []
}

Engines

API keys and base URLs for every supported LLM provider:

{
  "engines": {
    "anthropic":  { "api_key": "sk-ant-..." },
    "openai":     { "api_key": "sk-...", "base_url": "https://api.openai.com/v1" },
    "groq":       { "api_key": "...",    "base_url": "https://api.groq.com/openai/v1" },
    "openrouter": { "api_key": "...",    "base_url": "https://openrouter.ai/api/v1" },
    "gemini":     { "api_key": "..." },
    "ollama":     { "base_url": "http://localhost:11434" }
  }
}

Super-agent

{
  "super_agent": {
    "enabled": false,
    "name": "apx",
    "model": "anthropic:claude-sonnet-4-5",
    "permission_mode": "automatico",
    "allowed_tools": [],
    "model_fallback": {
      "enabled": true,
      "models": [
        "openrouter:meta-llama/llama-3.3-70b-instruct",
        "groq:llama-3.3-70b-versatile"
      ],
      "health_timeout_ms": 800
    }
  }
}

permission_mode controls which tools the super-agent can run without asking:

Mode	Behavior
total	All tools allowed, no confirmation
automatico	APX decides automatically based on safety heuristics
permiso	Only tools listed in allowed_tools; everything else asks

The identity file — ~/.apx/identity.json

This file sets the assistant’s user-facing name and personality:

{
  "name": "APX",
  "persona": ""
}

Change name to give your assistant a different display name across all surfaces (Telegram, Desktop, Web). The technical config key super_agent.name is separate — identity.json is what end users see.

Project config — .apc/config.json

Project-level overrides are committed alongside the agent definitions. They take priority over the global config for that project only. Never put secrets here — this file is committed.

{
  "super_agent": {
    "model": "groq:llama-3.3-70b-versatile",
    "permission_mode": "total"
  },
  "telegram": {
    "route_to_agent": "reviewer"
  }
}

Config commands

View config

Global

apx config show                   # effective config (global merged with project defaults)
apx config show --only-overrides  # only what differs from defaults

Project

apx project config show my-app
apx project config show my-app --key super_agent.model
apx project config show my-app --effective

apx

$ apx config show
{
"port": 7430,
"host": "127.0.0.1",
"log_level": "info",
"super_agent": {
  "enabled": true,
  "model": "anthropic:claude-sonnet-4-5",
  "permission_mode": "automatico"
},
"engines": {
  "anthropic": { "api_key": "sk-ant-••••a91f" },
  "openai":    { "api_key": "sk-••••7c2d" },
  "ollama":    { "base_url": "http://localhost:11434" }
},
"telegram": { "enabled": true, "channels": [ { "name": "default" } ] }
}

apx config show — full effective configuration as JSON

Set and unset values

Values are JSON-aware — booleans, numbers, and arrays are parsed correctly:

apx config set super_agent.enabled true
apx config set super_agent.model "anthropic:claude-sonnet-4-5"
apx config set engines.openai.api_key "sk-..."
apx config unset super_agent.model                  # remove key, fall back to default

For project config:

apx project config set my-app super_agent.model groq:llama-3.3-70b-versatile
apx project config set my-app telegram.route_to_agent reviewer
apx project config unset my-app super_agent.model
apx project config edit my-app                      # open in $EDITOR

Model commands

apx model manages the super-agent’s model fallback router — the ordered list of providers APX tries in sequence when the primary model is unavailable:

apx model status                                    # probe all providers, show active model
apx model order ollama openrouter groq              # set fallback order
apx model key groq sk-xxxx                          # save an API key
apx model set openrouter meta-llama/llama-3.3-70b-instruct  # pin a model for one provider
apx model test                                      # which model would be picked right now?
apx model enable                                    # enable the fallback router
apx model disable                                   # disable (primary only, no fallback)

apx

$ apx model status
Model router
primary:   anthropic:claude-sonnet-4-5
fallback:  on
order:     anthropic → openrouter → groq → ollama
active:    anthropic:claude-sonnet-4-5

✓ anthropic    claude-sonnet-4-5                up    key:config
✓ openrouter   meta-llama/llama-3.3-70b         up    key:config
✗ groq         llama-3.3-70b-versatile          down  (no key)
✓ ollama       llama3.2:3b                      up    key:config

Keys → ~/.apx/config.json engines.{groq,openrouter}.api_key
Or env: GROQ_API_KEY, OPENROUTER_API_KEY

apx model status — provider probes, API key presence, and active model

Permission commands

apx permission is a shorthand for reading and writing super_agent.permission_mode:

apx permission show                                 # print current mode
apx permission set total                            # allow all tools
apx permission set automatico                       # APX decides
apx permission set permiso                          # only allowed_tools

Tip

automatico is the recommended default for most projects. Use total only in trusted, non-interactive environments. Use permiso when you want explicit control over every tool the agent can reach.

Next

• Projects — per-project config in .apc/config.json.
• Installation — where ~/.apx/ is first created.