Algunos equipos no pueden enviar su tráfico a la nube. Quizás estés detrás de un firewall corporativo que bloquea las llamadas salientes a servicios de terceros. Quizás una regla de cumplimiento estipula que los datos de solicitud y respuesta deben permanecer en máquinas que tú controlas. Quizás todo el entorno esté aislado de la red (air-gapped) y nada sale de la intranet en absoluto. En cualquiera de esos casos, una URL simulada alojada en la infraestructura de otra persona es inaceptable, incluso cuando los propios datos simulados son falsos.
Apidog maneja esto con un ejecutor autoalojado (self-hosted runner). En lugar de que tus solicitudes vayan a la simulación en la nube de Apidog, despliegas un pequeño programa en un servidor de tu propiedad, y ese programa devuelve las respuestas simuladas desde el interior de tu propia red. El diseño reside en tu proyecto de Apidog como siempre; solo el servicio se traslada a tu hardware. Esta guía explica qué es el ejecutor, cuándo elegirlo en lugar de la simulación en la nube, cómo configurarlo siguiendo la documentación, y una distinción que confunde a la gente: el ejecutor no es la CLI. Si quieres una visión más amplia de por qué los equipos ejecutan simulaciones en sus propios equipos, la guía sobre servidores de simulación de API autoalojados cubre el caso general, y la OpenAPI Initiative explica la especificación a partir de la cual se generan estas simulaciones. ¿Quieres seguir el proceso? Descarga Apidog primero.
Qué es el ejecutor autoalojado
El ejecutor autoalojado de Apidog es un programa automatizado que tú alojas en un servidor independiente. Oficialmente se le llama General Runner, y realiza tres tareas: ejecuta pruebas automatizadas programadas, importa documentos API y devuelve respuestas simuladas. Esta tercera tarea es de lo que trata este artículo.
Aquí está la idea clave. Una vez que despliegas un General Runner y configuras su Server Host, un nuevo entorno llamado Runner Mock aparece automáticamente en tu proyecto. Cualquier solicitud que envíes a través de ese entorno obtiene su respuesta simulada de tu ejecutor autoalojado en lugar de la simulación en la nube de Apidog. El mismo diseño de simulación, los mismos datos generados, pero una máquina diferente realiza el servicio. Tu tráfico nunca sale de tu red.
Esta es la alternativa autoalojada a la simulación en la nube. Si tu equipo puede acceder a Internet y no tiene ninguna regla en contra, la simulación en la nube de Apidog es más sencilla porque no hay nada que desplegar. Recurre al ejecutor cuando se cumpla alguna de estas condiciones:
- El tráfico saliente a hosts externos está bloqueado o fuertemente auditado.
- Una política de cumplimiento requiere que los datos de la solicitud permanezcan en la infraestructura interna.
- El entorno está aislado de la red (air-gapped) y no puede acceder a un punto final en la nube en absoluto.
- Quieres que la latencia de la simulación se mida en tu propia LAN, no a través de la Internet pública.
Si ninguna de estas opciones se aplica, el host Docker adicional es una sobrecarga que no necesitas. Sé honesto contigo mismo acerca de en qué grupo te encuentras antes de aprovisionar un servidor.
Una nota sobre planes y permisos. La documentación de Apidog no establece una barrera explícita entre gratuita y de pago para el General Runner o para la simulación autoalojada, y no lista cifras de precios para ello, por lo que esta guía no inventará ninguna. Lo que la configuración sí requiere es permiso de administrador de equipo o proyecto, porque el despliegue de un ejecutor ocurre dentro de Recursos del Equipo, y solo los administradores pueden abrir esa configuración. Si no puedes ver el panel de Recursos, esa es la razón.
Lo que necesitas antes de empezar
El ejecutor se distribuye como un contenedor Docker, por lo que el servidor que lo aloja necesita tener Docker instalado. La documentación requiere una versión mínima de 20.10.0 y recomienda 20.10.13 o posterior. Comprueba qué tienes:
docker --version
También necesitas un lugar para ejecutarlo: una máquina Linux, macOS o Windows a la que puedan acceder tanto los clientes Apidog de tu equipo como el servicio Apidog. En una intranet, esto generalmente significa un servidor interno con una IP o nombre de host estables. Esa es toda la lista de requisitos previos: Docker, un host y derechos de administrador en el equipo. Todo lo demás lo configuras dentro de Apidog.
Desplegar el General Runner
El comando de despliegue se genera automáticamente desde Apidog e incluye un token, por lo que no tienes que escribirlo a mano. Así es como funciona.
Generar el comando
Abre Apidog Home, selecciona tu equipo, luego haz clic en Recursos en la barra lateral derecha y elige Desplegar General Runner. Aparecerá una ventana emergente donde configurarás algunas cosas:
- Sistema Operativo del Servidor: Linux, macOS o Windows, para que el comando generado coincida con tu host.
- Imagen Docker: elige General, Slim o Custom. General viene con Node.js 18, Java 21, Python 3 y PHP 8 preinstalados. Slim solo viene con Node.js 18, para una imagen más pequeña. Custom te permite proporcionar tu propio Dockerfile cuando necesitas tiempos de ejecución adicionales para scripts de prueba.
- Puerto Expuesto: configurado con el parámetro
-p, por ejemplo-p 80:4524, que mapea el puerto 80 del host al puerto interno del ejecutor. - Directorio de Datos Montado: configurado con el parámetro
-v, para que los datos del ejecutor persistan en el host a través de los reinicios.
Cuando hayas terminado, copia el comando generado. Esto es importante: el comando se muestra solo una vez, por razones de seguridad de datos, porque incrusta tu token. Si lo pierdes, generas uno nuevo en lugar de recuperar el anterior. Cópialo inmediatamente.
Ejecútalo en el servidor
Pega el comando en la terminal de tu servidor. La instalación comienza por sí sola y descarga la imagen. Un comando terminado se ve aproximadamente así (el tuyo será diferente e incluirá el token real):
docker run -d \
--name apidog-runner \
-p 80:4524 \
-v /opt/apidog-runner/data:/app/data \
apidog/runner:latest \
--token <TU_TOKEN_GENERADO>
Confirma que el contenedor está activo:
docker ps
Deberías ver el contenedor del ejecutor listado con su mapeo de puertos. Un cliente Docker como Docker Desktop muestra lo mismo si prefieres ver una interfaz de usuario.
Confirmar que se registró
De vuelta en Apidog, ve a Recursos del Equipo y abre General Runner. Haz clic en el botón de actualizar. El ejecutor debería mostrarse ahora como desplegado con un estado de Iniciado. Si no aparece al principio, el botón de actualizar es tu solución; dale un momento y haz clic de nuevo.
El estado del ejecutor tiene tres estados importantes que debes conocer:
- Iniciado: habilitado, comunicándose con Apidog, manejando tareas. Este es el estado que deseas.
- Detenido: alguien lo detuvo manualmente en Apidog. Permanece desplegado pero no procesará tareas.
- Sin conexión: ha perdido su conexión con Apidog, por lo que no puede procesar nada. Verifica el contenedor y la ruta de red.
Activar la simulación del ejecutor
Desplegar el ejecutor te proporciona el agente. Un paso más es dirigir tu tráfico simulado hacia él.
En Recursos del Equipo, abre General Runner y busca el campo Server Host. Introduce la dirección donde tu ejecutor es accesible. En una configuración HTTP simple, esa es la dirección del host y el puerto que expusiste, como http://127.0.0.1:80 para una prueba local o http://runner.internal.example.com:80 para un host de intranet compartido. Detrás de un proxy de terminación TLS, se vería como https://runner.example.com:443. Más sobre HTTPS en un momento.
Una vez configurado Server Host, Apidog cablea automáticamente el entorno Runner Mock para tu proyecto. Verifícalo: abre el proyecto, ve a Gestión de Entornos y confirma que Runner Mock ahora aparece en la lista de entornos. No lo creaste manualmente; la configuración de Server Host es lo que hizo que apareciera.
Enviar una solicitud a través de la simulación autoalojada
Ahora úsalo. Digamos que tienes un punto final `GET /orders/{orderId}` en un proyecto para una API interna de gestión de pedidos. Abre ese punto final, luego en el menú desplegable de entorno en la parte superior, selecciona Runner Mock en lugar del entorno de la nube. Envía la solicitud.
La respuesta proviene de tu ejecutor. Debido a que Apidog genera datos simulados a partir de tu esquema, un esquema `Order` bien definido devuelve valores realistas en lugar de marcadores de posición vacíos:
curl http://runner.internal.example.com:80/orders/10583
{
"orderId": 10583,
"customerEmail": "amelia.turner@example.com",
"status": "shipped",
"total": 148.5,
"currency": "USD",
"createdAt": "2026-07-14T09:32:11Z"
}
Ese JSON nunca tocó la Internet pública. El ejecutor lo construyó a partir del esquema de tu punto final y lo sirvió desde dentro de tu red. La generación consciente de campos como el valor `customerEmail` anterior proviene de que Apidog lee los tipos y nombres de campo de tu esquema, el mismo motor cubierto en el artículo complementario sobre generación automática de datos simulados realistas con simulación inteligente. Si deseas controlar exactamente lo que devuelve una solicitud determinada, agregas una expectativa de simulación en el punto final, y el ejecutor sirve esa expectativa de la misma manera que lo haría la simulación en la nube. La mecánica de construir buenas respuestas simuladas es la misma, ya sea que el servidor sea de Apidog o tuyo; solo cambia el host. Los conceptos generales detrás de la simulación de API se aplican sin cambios.
HTTPS, montajes de datos y otros detalles del mundo real
Una prueba ejecutada en http://127.0.0.1 es fácil. Un despliegue compartido en la intranet tiene algunas particularidades que vale la pena conocer antes de implementarlo en un equipo.
HTTPS necesita un proxy inverso
El ejecutor no tiene soporte integrado para certificados HTTPS y no realiza el aprovisionamiento automático de certificados. No obtendrá ni gestionará un certificado TLS por ti. Si necesitas https://, termina TLS en un proxy inverso delante del ejecutor, por ejemplo, Nginx con tu certificado, luego apunta el Server Host a la URL HTTPS del proxy. Sin un proxy, usa http://host:port. No configures Server Host como https:// y esperes que el ejecutor responda directamente a TLS; no puede.
Un bloque mínimo de Nginx que se coloca delante de un ejecutor en el puerto 4524 se ve así:
server {
listen 443 ssl;
server_name runner.example.com;
ssl_certificate /etc/ssl/certs/runner.example.com.pem;
ssl_certificate_key /etc/ssl/private/runner.example.com.key;
location / {
proxy_pass http://127.0.0.1:4524;
proxy_set_header Host $host;
}
}
Entonces, el Server Host se convierte en https://runner.example.com:443. La guía de MDN sobre HTTPS es un buen repaso si la terminación de TLS es nueva para tu equipo.
Los montajes de archivos son específicos de la ruta
Si tus simulaciones o pruebas necesitan archivos adicionales, el ejecutor los espera en rutas fijas dentro del contenedor, así que móntalos allí:
- Los programas externos van en
/app/external-programs/. - La configuración de conexión a la base de datos va en
/app/database/database-connections.json. - Los certificados de cliente SSL van en
/app/ssl/ssl-client-cert-list.json.
Conecta estos a través de tus montajes -v para que sobrevivan a los reinicios.
Comportamiento de redespliegue y actualización
Cuando se lanza una nueva versión del ejecutor, verás una opción de Actualizar, y en Más Acciones podrás Redesplegar. Ambas detienen el contenedor en ejecución mientras se inicia el nuevo. La parte tranquilizadora: las tareas programadas existentes en el cliente Apidog no se ven afectadas por un redespliegue o actualización, por lo que solo interrumpes el servicio en vivo por el momento en que se reinicia el contenedor, sin perder la configuración.
Automatiza el flujo de trabajo con la CLI de Apidog
Aquí está la distinción que evita confusiones: el ejecutor es un agente de larga duración que puede servir simulaciones y ejecutar tareas programadas, mientras que la CLI de Apidog es un ejecutor de pruebas de una sola vez para CI. Son herramientas diferentes. La CLI no puede servir, iniciar u hospedar un servidor de simulaciones. No existe apidog run mock ni apidog mock serve. El comando apidog run de la CLI ejecuta escenarios de prueba, carpetas de escenarios de prueba y suites de prueba, y su grupo de comandos mock solo realiza operaciones CRUD en expectativas de simulaciones como datos. El servicio de simulaciones es trabajo del ejecutor, nunca de la CLI.
Así es como encajan los dos. La CLI y los agentes de codificación de IA como Cursor, Claude Code y Codex pueden crear y actualizar los puntos finales y esquemas de tu proyecto, lo que mantiene la precisión de tu salida simulada a medida que evoluciona la especificación. Una vez que la simulación autoalojada ha desbloqueado el trabajo de frontend, los escenarios de prueba del mismo proyecto se ejecutan de forma desatendida en CI con un solo comando, validando el backend real contra el mismo contrato que describió la simulación:
apidog run -t <scenario_id> -e <env_id> -r html,cli
Ese único comando ejecuta tus escenarios contra el backend en vivo y escribe un informe HTML más CLI. La instalación es npm install -g apidog-cli en Node.js v16 o posterior; la guía de instalación de la CLI de Apidog cubre la configuración de apidog login y del token. Para que esa ejecución de prueba ocurra en cada push, conéctala a tu pipeline con la guía CI/CD de la CLI de Apidog. El artículo sobre simulación de API desde la CLI explica exactamente por qué la terminal gestiona las definiciones de simulación pero no las aloja.
Preguntas frecuentes
¿Necesito el ejecutor autoalojado si mi equipo puede acceder a Internet?
Probablemente no. La simulación en la nube no necesita nada desplegado y es el camino más simple. Elige el ejecutor cuando el tráfico saliente esté bloqueado o auditado, una regla de cumplimiento mantenga los datos en la infraestructura interna o el entorno esté aislado de la red (air-gapped). Si estás comparando el enfoque autoalojado con el gestionado, el tutorial de simulación en la nube de Apidog es el compañero natural de esta guía.
¿Puede la CLI de Apidog iniciar un servidor de simulación autoalojado?
No. La CLI ejecuta pruebas con apidog run y gestiona las expectativas de simulación como datos con su grupo de comandos mock. El servicio de tráfico de simulación lo realiza el General Runner o la simulación en la nube, nunca la CLI. Si esperabas escribir un comando en la terminal y obtener una simulación en ejecución en un puerto, ese es el trabajo del ejecutor, configurado a través de la interfaz gráfica como se describió anteriormente.
¿El ejecutor soporta HTTPS por sí mismo?
No incluye certificados ni los aprovisiona automáticamente. Coloca un proxy inverso como Nginx delante para terminar TLS, luego apunta el Server Host a la URL https:// del proxy. Sin un proxy, usa http://host:port.
¿Por qué mi ejecutor no aparece después de que ejecuté el comando?
Abre Recursos del Equipo, ve a General Runner y haz clic en el botón de actualizar. El registro puede tardar un momento. Si aún no aparece, confirma que el contenedor está en ejecución con docker ps y que el host es accesible desde Apidog. Un estado de Desconectado significa que la conexión se perdió; Iniciado es lo que deseas.
¿Pueden varios equipos compartir un solo ejecutor para el servicio global de simulaciones?
Un ejecutor se registra en el equipo donde lo desplegaste, y su entorno Runner Mock aparece por proyecto. Si tienes equipos distribuidos que comparten entornos de simulación, los patrones de la guía sobre compartir entornos de simulación entre equipos globales te ayudarán a decidir cuántos ejecutores desplegar y dónde.
Conclusión
La simulación autoalojada con el General Runner mantiene tus datos de solicitud en la infraestructura que tú controlas, mientras que tu diseño de simulación permanece donde siempre estuvo, en tu proyecto de Apidog. Despliegas un contenedor Docker, configuras el Server Host, y el entorno Runner Mock hace el resto. Recurre a él cuando la nube no esté disponible, y quédate con la simulación en la nube cuando sí lo esté. ¿Listo para ejecutar simulaciones en tu propia red? Descarga Apidog, despliega un ejecutor y sirve tu primera respuesta de Runner Mock sin que un solo paquete salga de tu intranet.