Runtimes

Un runtime es un CLI de codificación con IA externo que APX puede invocar sin interfaz (headless) en nombre de un agente. Usás apx run para delegar un prompt a una de estas herramientas; APX construye el system prompt, lanza el CLI, captura su salida y almacena un registro de sesión. La herramienta externa maneja la interacción real con el modelo, las ediciones de archivos y los comandos de shell — APX registra el envoltorio.

Esto es distinto de apx exec, que llama a un motor LLM directamente dentro de APX sin lanzar ningún proceso externo. Mirá Motores para ese camino.

Runtimes soportados

ID del runtime	Binario	Qué lanza APX
claude-code	claude	Modo headless -p; recibe el system prompt del agente vía --append-system-prompt; devuelve JSON estructurado que incluye un session_id que enlaza al transcript de Claude Code
codex	codex	codex exec --sandbox workspace-write --skip-git-repo-check; el system prompt se antepone al prompt del usuario (sin flag --system dedicado en modo exec)
opencode	opencode	opencode run; system prompt antepuesto al cuerpo del prompt
aider	aider	aider --message --yes-always --no-auto-commits; no interactivo, sin auto-commits
cursor-agent	cursor-agent	--print --output-format text --trust --force; modo print headless
gemini-cli	gemini	--prompt --output-format text --approval-mode yolo; modo prompt headless
qwen-code	qwen	--output-format text --approval-mode yolo; system prompt vía --append-system-prompt

Nota

APX pasa el system prompt del agente y el prompt del usuario. No selecciona ni sobrescribe el modelo dentro del CLI externo — la propia configuración del CLI (p. ej. los defaults de CLAUDE.md para Claude Code, o el archivo de config de Codex) controla eso.

Comprobar qué está instalado

Antes de elegir un runtime, confirmá qué CLIs están disponibles en la máquina actual:

apx env detect

apx

$ apx env detect
RUNTIME:
✓ claude-code    claude         1.0.44
✓ codex          codex          0.12.3
✓ opencode       opencode       0.3.1
· aider          aider          (not found)
· cursor-agent   cursor-agent   (not found)
✓ gemini-cli     gemini         0.2.0

ENGINE:
✓ ollama         ollama         0.5.4

TOOL:
✓ git            git            2.45.2
✓ rg             rg             14.1.0

apx env detect — muestra runtimes instalados, ejecutores de LLM locales y herramientas

La salida agrupa los resultados por categoría: runtime, engine y tool. Un runtime ausente de la lista no está instalado — instalá su binario primero, después volvé a ejecutar apx env detect.

Ejecutar un agente

apx run <agent> --runtime <id> "<prompt>" [--timeout <seconds>] [--project <name|id|path>]

Ejemplos:

# Revisión de código completa vía Claude Code
apx run reviewer --runtime claude-code "Review the diff in src/ for memory leaks"

# Tarea de refactorización vía Codex con un timeout más largo
apx run cody --runtime codex "Refactor parseAgentsMd to use a state machine" --timeout 600

# One-liner con OpenCode
apx run sofia --runtime opencode "Add JSDoc to every exported function in lib/"

apx

$ apx run reviewer --runtime claude-code 'Review this diff'
• inyectando el system prompt de reviewer en claude-code
• project: Acme Store (#2)   cwd: ~/code/acme-store

I reviewed the diff. Three findings:
1. cart.js:42 — total is recomputed inside the render loop; hoist it.
2. checkout.js:88 — Stripe webhook signature is never verified.
3. tests are missing for the empty-cart path.

I'd block the merge on #2 until the signature check lands.

# claude-code | exit 0 | session: ~/.claude/projects/...../a1f3c92e.jsonl

apx run en progreso — sesión externa de Claude Code con system prompt inyectado

Opciones

Flag	Descripción
--runtime <id>	Obligatorio. Uno de los IDs de runtime de la tabla de arriba
--timeout <seconds>	Tiempo de reloj máximo antes de que APX mate el subproceso
--project <name|id|path>	Fija a un proyecto específico; por defecto el directorio actual

Cómo APX inyecta el system prompt

Cuando ejecutás apx run, APX:

1. Lee la definición del agente desde .apc/agents/<slug>.md más la memoria de runtime desde ~/.apx/projects/<apx_id>/agents/<slug>/memory.md y cualquier skill cargada para construir el system prompt completo.

2. Llama a buildAgentSystem({ invocation: "runtime", runtime: "<id>" }) — el mismo builder usado por apx exec y apx chat, pero con la etiqueta de invocación runtime para que los prompts puedan ramificarse.

3. Pasa el resultado al mecanismo de inyección de system prompt del CLI (p. ej. --append-system-prompt para claude-code y qwen-code, o antepuesto al cuerpo del prompt para los runtimes que carecen de un flag dedicado).

4. Captura stdout. Si la salida incluye una línea que empieza con APC_RESULT:, ese valor se almacena como el campo de resultado estructurado de la sesión.

5. Escribe un archivo de sesión en ~/.apx/projects/<apx-id>/agents/<slug>/sessions/<date>-<runtime>-<id>.md con un enlace en el frontmatter de vuelta al propio path del transcript de la herramienta externa (cuando el runtime lo provee).

Registros de sesión y reanudación

Después de que apx run termina, APX crea un registro de sesión:

# ~/.apx/projects/<apx-id>/agents/reviewer/sessions/2026-05-27-claude-code-abc123.md
---
runtime: claude-code
session_id: abc123
external_session_path: /Users/me/.claude/projects/<encoded-cwd>/abc123.jsonl
---

El external_session_path apunta al propio transcript de la herramienta externa. Podés leerlo, resumirlo o continuarlo usando los comandos de sesión:

# Listar las sesiones de runtime recientes de un agente
apx session list reviewer

# Resumir lo que pasó en una sesión
apx session resume <id> --summary

# Leer el transcript en crudo
apx session get <id> --full

# Continuar la sesión en el CLI nativo de Claude Code
apx session resume <id> --continue

Resultados estructurados con APC_RESULT

Si querés que APX capture un valor legible por máquina del runtime externo, instruí al modelo (vía el prompt) para que imprima en su última línea:

APC_RESULT: <one-line value>

APX parsea esto y lo almacena como el campo result de la sesión, que otras rutinas o el super-agente pueden leer.

Delegar desde el super-agente (call_runtime)

apx run es un comando que escribís vos. Pero el super-agente también puede decidir, en medio de una conversación, delegarle una tarea a un runtime externo — tiene una tool call_runtime para eso exactamente (los mismos IDs de runtime, la misma lógica de lanzamiento de arriba). Esto es lo que pasa cuando le pedís al agente por Telegram, web, o apx exec que “hagas que Claude Code refactorice esto” o “corras esto por Codex”.

Nota

call_runtime y apx run terminan lanzando los mismos runtimes de la misma manera. La diferencia es quién inicia el llamado: vos, desde el CLI (apx run), o el super-agente, como una tool call durante una conversación (call_runtime).

Delegación síncrona vs. en segundo plano

Un llamado a call_runtime puede bloquear el turno actual hasta que el runtime termine, o lanzar el runtime desacoplado (detached) y dejar que el turno termine de inmediato:

• Síncrona (bloqueante) — el default en superficies sin forma de entregar un resultado tardío (web, desktop, apx exec). El tool call no retorna hasta que el proceso del runtime termina, y la salida del runtime vuelve como el resultado de la tool call de este turno.
• En segundo plano (async) — el default en Telegram, porque un runtime como claude-code puede tardar minutos o más de una hora, y bloquear congelaría al super-agente y mantendría el indicador de “escribiendo…” todo ese tiempo. En modo background, call_runtime lanza el runtime desacoplado y retorna de inmediato con { status: "launched", background: true, apc_session: "<id>" }. El agente responde enseguida (p. ej. “lo lancé, te aviso”) y el turno termina — el runtime sigue trabajando en segundo plano.

El modo background solo está disponible cuando hay un canal al cual entregarle el resultado más tarde (ver Entrega de callback (A2A) más abajo); hoy eso significa un chat de Telegram. El modelo igual puede forzar un llamado bloqueante en Telegram pasando background: false — útil cuando necesita la salida del runtime dentro del mismo turno para un seguimiento inmediato.

El timeout también cambia según el modo: un llamado en foreground usa 300s por defecto antes de que APX mande SIGTERM; un llamado en background usa 3600s (1 hora) por defecto, ya que se espera que las corridas desacopladas tarden más. Ambos se pueden sobrescribir por llamado.

Entrega de callback (A2A)

Cuando una corrida en background termina, su resultado tiene que llegar al usuario sin que nadie se quede esperándolo. APX lo entrega de una de dos formas:

1. Reporte A2A (preferido) — el resultado se reinyecta en un turno nuevo del super-agente como un reporte interno (etiquetado para que se lea como un traspaso agente-a-agente, no como un mensaje del usuario). El super-agente se lo cuenta al usuario en su propia voz, y puede encadenar un próximo paso si la tarea no terminó. Esto es lo que pasa en Telegram: la corrida terminada reingresa a la conversación y el agente manda un mensaje nuevo resumiéndola.
2. Envío directo al canal (fallback) — si el camino A2A no está disponible o falla, APX manda un mensaje simple al chat de origen: una línea de ”✅ terminó” o “⚠️ falló” seguida del resultado del runtime, sin que el super-agente lo reformule.

Entrega durable a través de reinicios del daemon

Lanzar una corrida en background también escribe un pequeño registro de callback pendiente (~/.apx/pending-callbacks/<apc_session>.json) — una IOU que anota qué chat espera el resultado. Si el daemon que lanzó la corrida muere antes de que el runtime termine (un crash, un git pull + reinicio, o una tarea delegada que reinicia el daemon), ese callback en memoria normalmente se perdería. En cambio, un reconciliador corre al arrancar el daemon y en un intervalo de 30 segundos, revisa el registro de sesión de cada callback pendiente, y una vez que la sesión muestra que la corrida terminó, entrega el resultado como un envío directo al canal y borra la IOU. Esto también cubre el caso en que el propio runtime externo cerró proactivamente su sesión de APX (p. ej. vía apx session close) en lugar de que la espera del proceso de APX detecte la salida.

Los dos caminos de entrega no se duplican: el reconciliador le da una ventana de gracia a la entrega en proceso en vivo antes de entregar él mismo el mismo callback.

run vs. exec

	apx run	apx exec
Qué se ejecuta	CLI externo (claude, codex, …)	Llamada LLM directa dentro de APX
Ediciones de archivos / shell	Sí — el CLI externo puede escribir archivos y ejecutar comandos	No — respuesta LLM de solo lectura
Elección de modelo	Controlado por la propia config del CLI externo	Controlado por --model o el modelo configurado del agente
Transcript de sesión	Almacenado tanto en APX como en el propio path de la herramienta externa	Almacenado solo en las conversaciones de APX
Usalo cuando	Necesitás capacidades completas de agente de código (ediciones, terminal)	Necesitás una respuesta rápida o una generación one-shot

Precaución

apx run es siempre headless — el CLI externo se ejecuta de forma no interactiva. Para sesiones de codificación interactivas, invocá el CLI directamente (p. ej. claude para Claude Code). Además, evitá prompts muy grandes vía la línea de comandos; aplican los límites de argumentos del shell.

Relacionado

• Motores — llamadas LLM directas con apx exec y apx chat
• Configuración — referencia de ~/.apx/config.json