Configuración

APX usa dos capas de configuración — global (local a la máquina, nunca commiteada) y local al proyecto (commiteada al repo, sin secretos). Los comandos de ambas capas usan sintaxis de claves con puntos y entienden JSON.

Config global — ~/.apx/config.json

El archivo de config global se crea en la primera ejecución. Contiene las credenciales de los engines, los ajustes del daemon, el modelo del super-agente, voz, memoria y las opciones de Telegram.

Estructura de nivel superior

{
  "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 y base URLs para cada proveedor de LLM soportado:

{
  "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" },
    "cerebras":   { "api_key": "...",    "base_url": "https://api.cerebras.ai/v1" },
    "openrouter": { "api_key": "...",    "base_url": "https://openrouter.ai/api/v1" },
    "gemini":     { "api_key": "..." },
    "ollama":     { "base_url": "http://localhost:11434" }
  }
}

Residencia del modelo Ollama

APX manda keep_alive: -1 en cada request de chat a Ollama. Una vez que APX carga un modelo, Ollama lo mantiene en memoria, así los turnos siguientes evitan carga en frío. Liberalo explícitamente con ollama stop <model> o reiniciá Ollama.

Esto aplica sólo a modelos llamados por APX. Si host no tiene RAM o VRAM disponible suficiente, Ollama igual puede descargar modelo inactivo para cargar otro.

Proxy de salida por motor

Cualquier motor acepta un proxy, y sale por ahí solamente el tráfico de ese motor:

{
  "engines": {
    "zen": { "proxy": "http://127.0.0.1:8888" }
  }
}

Todo lo demás —Telegram, los otros proveedores, el vault, el chequeo de actualizaciones— sigue usando la ruta normal. Es a propósito más angosto que HTTPS_PROXY o el --use-env-proxy de Node, que son para todo el proceso.

Como el túnel vive detrás de la dirección del proxy y no en la tabla de ruteo de esta máquina, no pelea con Tailscale como sí lo hace un cliente de VPN. Hay un contenedor listo para usar en examples/egress-proxy/.

Un proxy configurado pero inalcanzable hace fallar la llamada en vez de caer a la ruta directa: caer en silencio mandaría el tráfico justo a donde el proxy se puso para evitarlo.

Super-agente

{
  "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 controla qué herramientas puede correr el super-agente sin preguntar:

Modo	Comportamiento
total	Todas las herramientas permitidas, sin confirmación
automatico	APX decide automáticamente según heurísticas de seguridad
permiso	Sólo las herramientas listadas en allowed_tools; el resto pregunta

El archivo de identidad — ~/.apx/identity.json

Este archivo define el nombre de cara al usuario y la personalidad del asistente:

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

Cambiá name para darle a tu asistente un nombre distinto en todas las superficies (Telegram, Desktop, Web). La clave técnica de config super_agent.name es algo aparte — identity.json es lo que ven los usuarios finales.

Config de proyecto — ~/.apx/projects/<apx_id>/config.json

Los valores a nivel de proyecto tienen prioridad sobre la config global, sólo para ese proyecto. El archivo vive en el storage del proyecto, no en su repo: antes era .apc/config.json, que se commitea, así que equivocarse de scope podía dejar una api key lista para el próximo push. Acá las claves están seguras. Los proyectos configurados antes de la mudanza se migran la primera vez que el daemon los lee — el archivo viejo se mueve, no se copia.

En .apc/ queda la mitad portable — project.json, agentes, skills, organization — y el daemon se niega a escribir ahí cualquier cosa con forma de credencial.

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

Comandos de config

Ver la config

apx config llega a las dos capas. Por defecto edita la capa de proyecto, y con --global (o --scope global) la capa global — o sea que el flag decide qué archivo estás tocando.

Global

apx config show --global          # ~/.apx/config.json, con los secretos ocultos
apx config show --global | jq .super_agent   # el JSON va a stdout, el encabezado a stderr

Project

apx config show                   # lo propio de este proyecto + la config efectiva
apx config show --effective       # sólo la config efectiva combinada
apx config show --only-overrides  # sólo los overrides del proyecto

apx project config show my-app    # lo mismo, para un proyecto en el que no estás parado
apx project config show my-app --key super_agent.model

Precaución

--effective y --only-overrides describen la combinación proyecto↔global, así que se rechazan junto con --global: en la capa global no hay un segundo archivo con el cual combinar.

apx

$ apx config show --global
{
"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 --global — la configuración global como JSON, con los secretos ocultos

Setear y desetear valores

Los valores entienden JSON — booleanos, números y arrays se parsean correctamente:

Los ajustes globales — credenciales, el daemon, la voz y los valores por defecto del super-agente — necesitan --global. La escritura pasa por el daemon, que recarga el valor nuevo al instante:

apx config set --global super_agent.enabled true
apx config set --global super_agent.model "anthropic:claude-sonnet-4-5"
apx config set --global engines.openai.api_key "sk-..."
apx config unset --global super_agent.model         # borra la clave y vuelve al default

Precaución

Pasá --global para lo que use toda la máquina. Las dos capas son locales a esta máquina, así que una clave en cualquiera de las dos está a salvo de git — pero un subsistema que sólo lee la global (la voz, el daemon, el router de modelos) no va a ver un valor que dejaste en un proyecto.

apx config set --global engines.openai.api_key <value>   # todos los proyectos, todo subsistema
apx config set engines.openai.api_key <value>            # sólo este proyecto

Los overrides de proyecto son el caso por defecto, así que no llevan flag. Dentro del proyecto:

apx config set super_agent.model groq:llama-3.3-70b-versatile
apx config set telegram.route_to_agent reviewer
apx config unset super_agent.model

Desde cualquier lado, nombrando el proyecto:

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

Comandos de modelo

apx model gestiona el router de fallback de modelos del super-agente — la lista ordenada de proveedores que APX prueba en secuencia cuando el modelo primario no está disponible:

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 — sondeos de proveedores, presencia de API key y modelo activo

Comandos de permisos

apx permission es un atajo para leer y escribir 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

Consejo

automatico es el default recomendado para la mayoría de los proyectos. Usá total sólo en entornos confiables y no interactivos. Usá permiso cuando quieras control explícito sobre cada herramienta que el agente puede alcanzar.

Próximo

• Proyectos — config por proyecto y dónde vive.
• Instalación — dónde se crea por primera vez ~/.apx/.