Cómo alojar OneCLI: un agente aislado por persona
Aloja OneCLI en tu VPS con Docker Compose y PostgreSQL: un agente aislado por persona, claves en un gateway y 2 GiB de RAM por entorno.
Qué se obtiene al alojar OneCLI por cuenta propia
Al alojar OneCLI por cuenta propia, cada persona del equipo obtiene su propio agente. Cada agente se ejecuta en su propio sandbox y las claves de API se almacenan en un gateway que los agentes nunca pueden leer. La instalación es una pila de Docker Compose con PostgreSQL detrás, accesible en http://localhost:10254. Planifique usar un servidor real. El valor predeterminado documentado es un límite de memoria de 2 GiB por sandbox de agente. Por tanto, reserve por separado la memoria de la pila base y la memoria de trabajo real de los agentes.
La pila incluye ocho componentes. Saber qué función cumple cada uno facilita la lectura del resto de esta guía.
- Panel web (Next.js), puerto
10254. Permite crear agentes, gestionar chats, editar la memoria y las skills, y administrar conexiones y secretos. - Servidor de API, puerto
10256. Es el plano de control: gestiona la base de datos, las conversaciones y las colas de trabajo. - Gateway de Rust, puerto
10255. Intercepta las solicitudes salientes de los agentes e inyecta las credenciales. - Runner. El README lo describe como el componente que «inicia, aparca y elimina los sandboxes de los agentes. Sólo permite conexiones salientes y nunca accede a la base de datos».
- Supervisor del sandbox. El README lo describe como el componente que se ejecuta «dentro de cada sandbox y se comunica mediante una interfaz de harness independiente del proveedor, de modo que el runtime del agente se puede sustituir».
- Terminador SSH, puerto
10257. El README lo denomina «la puerta de entrada SSH»: termina las conexiones SSH con certificados de corta duración emitidos por la API y conecta cada sesión con el sandbox de un agente. Se ejecuta con el mismo perfilrunnerque el runner. - Adaptador de canales. Es un daemon que conecta una aplicación de Slack para que un agente responda en canales y mensajes directos con su propio nombre.
- PostgreSQL. El archivo compose incluido ejecuta
postgres:18-alpinecon un volumenpgdata.
El nombre dice CLI, pero el producto es un servidor
OneCLI es una plataforma de servidor. El nombre sugiere una herramienta de línea de comandos que se instala en un portátil, pero esa descripción no corresponde al componente de esta guía. Existe un cliente independiente de línea de comandos en el repositorio onecli/onecli-cli, que enruta el tráfico del agente de programación local a través de una puerta de enlace. Lo que se implementa aquí es una aplicación web multiusuario: un sistema de cuentas con organizaciones e invitaciones, una base de datos de conversaciones y secretos, y un ejecutor que inicia contenedores.
El modelo por persona es la base de todo el diseño. El README indica: «Se crea un agente por persona, se le concede el acceso que necesita y trabaja en un entorno aislado, enrutado a través de una puerta de enlace que inyecta las credenciales y aplica la política». Cada agente tiene su propio sistema de archivos y shell, su propia página de conversaciones, la memoria que conserva la plataforma y las habilidades que se escriben una sola vez. Las credenciales funcionan al contrario que en la configuración habitual. En lugar de copiar una clave de API en el entorno de cada persona, se almacena una sola vez y se concede a los agentes autorizados a utilizarla.
Requisitos del sistema antes de empezar
- Docker, con el complemento Compose en la versión 2.24.0 o posterior. El archivo compose incluido usa asignaciones opcionales de
env_fileconrequired: false, compatibles con Docker desde la versión 2.24.0. Los comentarios de migración explican que el requisito mínimo indicado, 2.19, permite usar dependencias de ejecución única conup --wait, pero no cubre los archivos de entorno opcionales del archivo. - Memoria, que es la limitación real. Lea la sección de dimensionamiento siguiente antes de elegir un plan.
- Puertos de loopback libres
10254,10255,10256,10257y5432. El puerto10257es la puerta de entrada SSH, que se inicia con el perfilrunnerhabilitado en esta guía.
No necesita instalar PostgreSQL por su cuenta: el archivo compose lo ejecuta como servicio. El asistente de configuración siguiente necesita Node.js y pnpm en el host. El trabajo con el código también usa mise para fijar la cadena de herramientas, incluido Rust para el gateway.
¿Cuántos entornos aislados de agentes caben en tu VPS?
La documentación del propio runner proporciona cifras reales, no impresiones. Cada entorno aislado está limitado a 2048 MB de memoria (RUNNER_SANDBOX_MEMORY_MB), una CPU (RUNNER_SANDBOX_CPUS) y 512 procesos (RUNNER_SANDBOX_PIDS). El límite de concurrencia es 4 (RUNNER_MAX_SANDBOXES), y la documentación recomienda disponer de unos 10 GiB de memoria libre además de la pila base para atender ese límite.
Los datos de este gráfico
[
{
"plan": "2 GB box",
"ram_gb": 2,
"sandbox_slots": 0
},
{
"plan": "4 GB box",
"ram_gb": 4,
"sandbox_slots": 1
},
{
"plan": "8 GB box",
"ram_gb": 8,
"sandbox_slots": 3
},
{
"plan": "16 GB box",
"ram_gb": 16,
"sandbox_slots": 7
},
{
"plan": "32 GB box",
"ram_gb": 32,
"sandbox_slots": 15
}
]Esas cantidades de slots son un cálculo aritmético, no un benchmark: la memoria total, menos unos 2 GB asumidos para PostgreSQL y los demás servicios de larga duración, dividida entre el límite de 2 GiB por entorno aislado. Según esa base, el presupuesto de 2 GB box permite 0 entornos aislados con su límite máximo de memoria; cero significa que, con estos supuestos, no hay presupuesto para ningún entorno con el límite completo, no que Docker rechace iniciar un agente. Un 16 GB box deja espacio para 7, por encima del límite predeterminado de cuatro y de los aproximadamente 10 GiB de memoria libre que solicita la documentación del runner. El 32 GB box permite llegar a 15. Ejecutar más de cuatro al mismo tiempo también requiere aumentar RUNNER_MAX_SANDBOXES.
Hay dos factores que modifican ese cálculo. Un entorno aislado con un proceso en segundo plano en ejecución nunca queda en reposo, por lo que mantiene su slot de forma permanente. Por tanto, dimensiona RUNNER_MAX_SANDBOXES para la carga sostenida y no para el minuto de mayor actividad. La plataforma establece un límite: de forma predeterminada, cada runner mantiene como máximo RUNNER_MAX_SANDBOXES menos un entornos aislados activos (nunca menos de uno; se puede cambiar con MAX_HELD_AWAKE_SANDBOXES mediante la API). Cuando se supera ese límite, expulsa el entorno que lleva más tiempo inactivo e informa de que el proceso supervisado se ha perdido. El uso de memoria y CPU depende del trabajo. Cada entorno aislado está limitado a una CPU, por lo que cuatro agentes ocupados pueden usar cuatro núcleos. Sin embargo, el ajuste de 2 GiB de memoria es un límite máximo, no una reserva: cuatro agentes inactivos pero activos no consumen automáticamente 8 GiB.
Ajustes del runner que quizá quieras cambiar
RUNNER_MAX_SANDBOXES(predeterminado:4): cuántos entornos aislados se ejecutan a la vez.RUNNER_SANDBOX_MEMORY_MB(predeterminado:2048): límite de memoria por entorno aislado.RUNNER_SANDBOX_CPUS(predeterminado:1): límite de CPU por entorno aislado.RUNNER_SANDBOX_PIDS(predeterminado:512): límite de procesos por entorno aislado.RUNNER_NETWORK_INTERNAL(predeterminado:true): mantiene la red del entorno aislado sin ninguna ruta de salida. Déjalo activado.RUNNER_SANDBOX_NETWORK(predeterminado:onecli-sandboxes): la red a la que se conectan los entornos aislados.RUNNER_RECONCILE_SECONDS(predeterminado:60): cada cuánto el runner reconcilia el estado.RUNNER_ORPHAN_GRACE_SECONDS(predeterminado:3600): antigüedad a partir de la cual se destruyen los contenedores y volúmenes huérfanos.RUNNER_AGENT_IMAGE: sustituye la imagen del entorno aislado, que de otro modo sigueONECLI_VERSION.
Instalar OneCLI con Docker Compose
La secuencia sin procesar del documento de autoalojamiento del proyecto escribe tres secretos en docker/.env junto al archivo de Compose. Esa secuencia omite el token del runner, el grupo del socket de Docker y las credenciales SSH que necesitan los servicios que habilita, por lo que debe ejecutar el asistente de configuración antes de iniciar el stack.
git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --waitLea ese bloque antes de ejecutarlo. El marcador heredoc no está entre comillas, por lo que el shell ejecuta cada head -c 32 /dev/urandom | base64 y escribe el resultado en lugar del texto literal. SECRET_ENCRYPTION_KEY es la clave AES-256-GCM para todos los secretos de la base de datos. GATEWAY_INTERNAL_SECRET autentica el gateway ante la API. BETTER_AUTH_SECRET firma las cookies de sesión. COMPOSE_PROFILES=runner es la línea más importante, porque el servicio runner está detrás de un perfil de Compose: si la omite, el stack se inicia correctamente, pero no se inicia ningún sandbox del agente.
--wait espera a que los servicios estén en ejecución o en estado saludable y a que la dependencia de migraciones finalice correctamente, por lo que una salida distinta de cero es la primera señal de que algo no funciona. Después, compruebe qué servicios se iniciaron realmente.
docker compose ps
docker compose logs migrationsFije la versión. ONECLI_VERSION establece la etiqueta para todos los servicios a la vez, y la imagen del sandbox del agente la sigue salvo que RUNNER_AGENT_IMAGE apunte a otro lugar. Use sólo el número de versión: las etiquetas de las imágenes publicadas no llevan el prefijo v. A fecha de 1 de noviembre de 2026, la versión actual es v2.17.0, publicada el 31 de octubre de 2026. Añádala al mismo archivo y use después el procedimiento de actualización documentado para que los sandbox en ejecución también pasen a esa imagen.
echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd dockerTambién existe un instalador, curl -fsSL https://onecli.sh/install | sh, que escribe su configuración en ~/.onecli/.env y realiza el mismo trabajo. Establece ONECLI_VERSION=latest para su propia ejecución, lo que sobrescribe una versión fijada únicamente en ese archivo .env. La ruta de Compose es la que permite leer todos los archivos antes de iniciar nada, y es la que debe usar en un equipo que ya ejecute otros stacks de Compose. La configuración mediante checkout anterior se actualiza con pnpm run setup --upgrade. Esa ruta requiere Node.js y pnpm en el host. Si trabaja directamente con el código, también necesita mise y Rust para el gateway, por lo que es adecuada para quienes tienen previsto modificar OneCLI. Para Kubernetes, la versión v2.11.0, publicada el 8 de octubre de 2026, añadió un chart de Helm. El chart actual ejecuta los sandbox de los agentes como Jobs con volúmenes persistentes, sin un daemon de Docker, y documenta los secretos, la base de datos y la configuración de enrutamiento necesarios.
Acceder al panel desde el portátil
Todos los puertos publicados en el archivo compose incluido se enlazan a ${ONECLI_BIND_HOST:-127.0.0.1}. En un VPS, esto significa que el panel está en ejecución, pero nada fuera del servidor puede acceder a él. Ese valor predeterminado es correcto. Manténgalo y cree un túnel:
ssh -N -L 10254:127.0.0.1:10254 you@your-serverAhora abra http://localhost:10254 en el portátil. El tráfico circula por la conexión SSH, por lo que no hay un panel sin cifrar expuesto en Internet pública ni es necesario abrir otro puerto en el firewall.
Configurar ONECLI_BIND_HOST=0.0.0.0 publica el panel mediante HTTP sin cifrar y también publica PostgreSQL, con la contraseña predeterminada del archivo compose, onecli, salvo que configure POSTGRES_PASSWORD. También publica la puerta de entrada SSH en el puerto 10257, un servicio que monta el socket de Docker. Si varias personas necesitan acceder al panel, coloque un proxy inverso con TLS (seguridad de la capa de transporte) delante y mantenga el host de enlace sin cambios. Configure ONECLI_EXTERNAL_URL con su URL HTTPS y use la configuración de proxy inverso del proyecto original, que dirige las rutas del panel, la API y la pasarela a sus respectivos servicios. Un proxy por sí solo no impide el acceso de personas no autorizadas. La documentación de self-hosting indica que el registro está abierto por diseño y que no existe ninguna opción para desactivarlo: cualquiera que acceda al panel puede crear una cuenta, que obtiene su propia organización; sólo es necesario invitar a los usuarios que deban unirse a su organización. La recomendación es mantener el panel detrás del perímetro de su red. Si ese proxy ya publica sus demás aplicaciones self-hosted, el reenvío de autenticación mediante una capa de inicio de sesión único autoalojada coloca el panel detrás del inicio de sesión que ya utiliza su equipo, de modo que eliminar a una persona en un solo lugar también cierra este acceso.
Cree la primera cuenta y, después, conceda una clave de modelo
Abra el panel y cree la cuenta de inmediato. Cada cuenta nueva obtiene su propia organización, y los miembros del equipo se incorporan a la suya mediante invitación. Después, el registro sigue abierto. Por eso, el panel debe estar detrás del túnel o de un proxy autenticado. Si está actualizando desde una versión anterior a la autenticación, regístrese de inmediato: la documentación de instalación autónoma indica que los datos existentes pasan a la primera cuenta que se registre. Por tanto, en un host accesible, esa cuenta debe ser la suya.
Después, almacene una clave de modelo antes de crear un agente. Un agente alojado necesita una clave de modelo concedida. El orden es importante: almacene la clave en el panel, concédasela al agente y sólo entonces inicie una conversación. Si omite la concesión, el sandbox no se inicia. El agente responde en el hilo que necesita una clave de modelo.
Conceda sólo los permisos necesarios. Cada agente obtiene únicamente lo que usted le concedió, y la pasarela lo aplica en cada solicitud. Por tanto, un agente que lee un repositorio no puede acceder a la clave de su proveedor de pagos. La misma lista de concesiones también permite controlar el gasto. Un agente por persona que pueda llamar a cualquier modelo que usted tenga genera una factura por persona. Por eso, conviene leer cómo limitar lo que un agente puede gastar en llamadas a modelos antes de crear diez agentes.
Cómo el gateway mantiene las claves fuera de los agentes
El gateway es un proxy HTTPS escrito en Rust que escucha en el puerto 10255. El cliente HTTP de un agente se configura para usarlo y el agente lleva una credencial de marcador de posición en lugar de una credencial real. El gateway compara la solicitud saliente con las autorizaciones de ese agente, descifra el secreto real, lo sustituye en la solicitud y la reenvía. Los secretos se almacenan en PostgreSQL cifrados con AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode) y sólo se descifran en el momento de la solicitud. Cada llamada se registra con la identidad del agente y su destino. Esto proporciona un registro de auditoría que no se obtiene cuando las claves se almacenan en los perfiles de shell de diez personas.
Dos aspectos determinan cómo se implementa.
- La interceptación HTTPS es un ataque de intermediario. El gateway genera una autoridad certificadora local, el agente confía en ella y el gateway termina la conexión TLS del agente; después, abre otra conexión con el servicio ascendente. Por eso, un agente cuyo cliente HTTP no confía en la autoridad certificadora del gateway falla con un error de verificación del certificado, no con un error de autenticación.
- El agente se identifica mediante una cabecera
Proxy-Authorization. En un solo equipo, donde los agentes y el gateway comparten una red Docker interna, esa cabecera nunca atraviesa una red que no sea de su propiedad. Si apunta un agente externo al gateway, proteja la conexión con una VPN o un transporte TLS, porque esa cabecera es un token portador; upstream recomienda una VPN para el puerto de proxy CONNECT sin cifrar.
La contrapartida es clara: el gateway lee en texto plano todas las solicitudes que realizan sus agentes, por diseño. Es el proceso más sensible del equipo. Proteja el host en consecuencia y limite el número de personas que pueden iniciar sesión mediante usuarios de Linux con privilegios mínimos.
Por qué el runner no necesita un puerto entrante
El runner sólo inicia conexiones salientes. Su documentación indica lo siguiente: «no mantiene ningún puerto accesible desde el exterior, por lo que funcionan tanto un portátil como un homelab o una VPC detrás de NAT, sin ingreso, sin túnel y sin necesidad de gestionar la terminación TLS». NAT significa traducción de direcciones de red, como la que realiza un router doméstico. El runner se conecta al plano de control y obtiene el trabajo desde allí, por lo que no hay nada que redirigir ni ningún puerto que abrir.
Este diseño resulta útil en la red del sandbox. El archivo compose define una segunda red marcada como internal: true, que en Docker significa que no tiene conectividad de red externa. Los sandboxes se conectan a ella. El gateway tiene interfaces en ambas redes, por lo que es la única vía de salida. La documentación del runner lo explica claramente: «una red internal con el gateway conectado a ella mediante dos interfaces es lo que convierte la salida exclusiva a través del gateway en un límite real y no en una simple recomendación». Un agente no puede eludir el gateway abriendo una conexión directa a una dirección externa; la política del gateway sigue determinando qué solicitudes permite.
Confírmelo en su propio equipo en lugar de confiar en el párrafo anterior.
docker network ls
docker network inspect onecli-sandboxes | grep -i internalDebería ver "Internal": true. Si muestra false, el control de salida está desactivado y el gateway vuelve a ser una simple recomendación. Use el nombre de red del sandbox que muestre docker network ls, ya que onecli-sandboxes sólo es el valor predeterminado.
¿Qué solidez tiene el sandbox de OneCLI?
Lea esta sección despacio, porque «sandbox» tiene mucho peso en la descripción del propio proyecto, mientras que el mecanismo se documenta en la documentación del runner y en el código del backend.
El README indica que cada agente obtiene «su propio sandbox aislado, con un sistema de archivos y un shell», y menciona Sandbox Supervisor como el componente que «se ejecuta dentro de cada sandbox y se comunica mediante una interfaz de harness independiente del proveedor, para que el runtime del agente pueda sustituirse». Ninguna de las dos frases explica en qué consiste el aislamiento. La documentación del runner sí lo hace: el backend predeterminado es Docker (RUNNER_BACKEND=docker), y un sandbox es un contenedor Docker con un límite de memoria, un límite de CPU y un límite de procesos, conectado a la red interna. El código deja un punto de extensión para otros backends. El código actual del runner también implementa un backend de Kubernetes, que el chart de Helm utiliza para los Jobs de sandbox y los volúmenes persistentes. En la instalación con Compose de esta guía, un sandbox es un contenedor Docker.
La documentación del runner describe ahora el límite de Docker: el agente se ejecuta como node, con no-new-privileges, todas las capacidades de Linux eliminadas y el perfil seccomp predeterminado de Docker. El backend monta únicamente el directorio home persistente del agente dentro de su sandbox. Por tanto, adopte una interpretación estricta. Los límites son límites de recursos. La red interna proporciona un control real de las conexiones salientes. El aislamiento entre un agente y su host utiliza estos controles de contenedor, y un contenedor comparte el kernel del host.
Hay un segundo hecho que debe tener en cuenta. El servicio del runner monta /var/run/docker.sock, porque así es como crea los sandboxes. El acceso al socket de un daemon de Docker con privilegios root equivale a tener root en el host, ya que quien puede llamar a esa API puede iniciar un contenedor con el sistema de archivos del host montado dentro. El runner basado en Docker incluido utiliza ese socket. La consecuencia es que el proceso del runner es tan sensible como el gateway. El terminador SSH monta el mismo socket para poder ejecutar comandos dentro de los contenedores de sandbox, y los propios comentarios del archivo Compose califican ese montaje como equivalente a root en el host. Por tanto, mantenga el puerto 10257 en loopback, salvo que tenga un motivo para abrirlo.
Trate el límite del kernel compartido con cautela. En la práctica, esto implica tres hábitos.
- Ejecute OneCLI en un equipo que no haga nada más. No aloje servicios de producción no relacionados, bases de datos compartidas ni datos de otros equipos.
- Suponga que un agente que consiga ejecutar código arbitrario dentro de su sandbox podría alcanzar el host, y haga que ese resultado sea recuperable mediante copias de seguridad almacenadas fuera del equipo.
- Lea
apps/runner/srco consulte al proyecto antes de decir a un compañero que el agente está contenido.
Para ver cómo es un límite documentado y qué preguntas conviene hacer al proyecto, compare esto con cómo es realmente el límite de un sandbox de agente. La cuestión es si el mecanismo documentado cubre las amenazas que necesita detener.
La división de licencias y por qué debe comprobarla antes de crear nada
El núcleo de OneCLI utiliza Apache-2.0, y está permitido alojarlo por cuenta propia en producción. Los directorios llamados ee/ están sujetos a una licencia independiente de OneCLI Enterprise: son gratuitos para desarrollo, pruebas y evaluación, pero requieren una suscripción para usarlos en producción. Las notas de la versión v2.0.1, del 18 August 2026, mencionan que se restauró un archivo de licencia Apache-2.0 detectable por GitHub, por lo que la insignia de la página del repositorio ha cambiado recientemente. Compruebe la etiqueta que realmente va a implementar, no un resumen escrito en otra fecha.
cd onecli && find . -type d -name ee -not -path '*/node_modules/*'Todo lo que esté bajo esas rutas forma parte del componente comercial. Si una función de la que piensa depender se encuentra allí, compruebe su precio antes de crear un proceso basado en ella.
Actualizaciones, migraciones y el único archivo que no puede perder
Las actualizaciones deben renovar las imágenes del servicio y la imagen independiente del agente. Después deben reiniciar los sandboxes en ejecución. En cada up, un servicio de migraciones de ejecución única se ejecuta antes que la API. Si una migración falla, la pila no se inicia en lugar de atender peticiones con un esquema migrado sólo parcialmente. Ese es el comportamiento que necesita, porque una actualización fallida se muestra como una interrupción del servicio y no como una corrupción silenciosa. docker compose logs migrations explica el motivo.
Es fácil pasar por alto un paso. La documentación de self-hosting desaconseja actualizar con un docker compose pull && docker compose up -d vacío, porque la imagen del sandbox del agente no es un servicio de Compose. Es el valor de RUNNER_AGENT_IMAGE en el runner. Por eso docker compose pull nunca lo detecta, y los agentes alojados pueden seguir usando una imagen de sandbox antigua sin ninguna advertencia. Actualice el checkout, cambie el pin y ejecute la herramienta de actualización documentada. Esta herramienta descarga la imagen del sandbox y reinicia los sandboxes en ejecución.
cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrationsSustituya 2.17.0 por la versión a la que va a actualizar. Los reinicios de los sandboxes interrumpen el trabajo en curso. El espacio de trabajo persistente de cada agente se conserva.
Si instaló el sistema con el script de instalación, vuelva a ejecutar ese script en lugar de descargar las imágenes manualmente. Así, el archivo de Compose se mantiene sincronizado con las imágenes a las que hace referencia. Exporte ONECLI_VERSION antes si quiere una versión concreta, porque el script sobrescribe un pin que sólo se conserve en su archivo .env.
Haga una copia de seguridad de la base de datos, la configuración y los volúmenes de los espacios de trabajo de los agentes. PostgreSQL almacena los agentes, las conversaciones, la memoria y los secretos cifrados. El archivo docker/.env contiene SECRET_ENCRYPTION_KEY. Sin esa clave, los secretos cifrados no se pueden leer, aunque se restaure el resto de la base de datos. El /workspace de cada agente reside en un volumen persistente independiente y necesita su propia copia de seguridad.
cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backupConserve esas copias y las copias de seguridad de los espacios de trabajo fuera del servidor. El procedimiento es el mismo que necesita cualquier pila de Compose con estado. Si ya hace copias de seguridad y actualiza una pila de Docker Compose de forma programada, añada los volúmenes de la base de datos, la configuración y los espacios de trabajo, y deje de preocuparse por ello.
Cuando no funciona
- El stack nunca llega a estar saludable y
docker compose up -d --waittermina con un código distinto de cero. Lea primerodocker compose logs migrations, porque la API espera deliberadamente a ese servicio. - Un agente permanece inactivo y no aparece ningún sandbox. Compruebe que
COMPOSE_PROFILES=runneresté endocker/.envy quedocker compose psmuestre un runner. Después, compruebe que el agente tenga una clave de modelo concedida, ya que los sandboxes no se inician sin ella. - No quedan slots disponibles.
RUNNER_MAX_SANDBOXEStiene el valor predeterminado 4, y un sandbox con un proceso en segundo plano en ejecución conserva su slot hasta que el límite de permanencia activa lo expulsa.docker psmuestra qué sigue realmente activo. - El stack no se inicia y Docker informa de que un puerto ya está en uso. Con el perfil
runneractivado, la puerta de entrada SSH necesita10257además de los otros cuatro puertos. - Los contenedores desaparecen o el host funciona con mucha lentitud. Compruebe si se ha agotado la memoria con
dmesg -T | grep -i oom; el límite de memoria predeterminado permite que un solo sandbox utilice hasta 2048 MB. - Las llamadas HTTPS de un agente fallan con errores de verificación de certificados, no con errores de autenticación. Su cliente HTTP no confía en la autoridad certificadora del gateway.
- Los contenedores o volúmenes antiguos permanecen después de eliminar un agente. El runner reconcilia el estado cada 60 segundos y destruye los huérfanos con una antigüedad superior a
RUNNER_ORPHAN_GRACE_SECONDS, cuyo valor predeterminado es 3600. Espere una hora antes de considerarlo una fuga.
¿Es esto lo que necesita ejecutar?
La prueba de adecuación es breve. OneCLI resulta útil cuando varias personas necesitan un agente y usted quiere centralizar las credenciales: un único almacén que rotar, un único registro de auditoría que revisar y un único panel donde revocar el acceso de una persona revoque realmente ese acceso. Es un problema operativo real, y copiar una clave de API en seis portátiles es una solución peor.
Para una sola persona, es demasiada infraestructura y no aporta ninguna ventaja. Tendría que ejecutar PostgreSQL, un plano de control, una gateway y un runner para disponer de un único agente, y el problema de las credenciales que resuelve la gateway apenas existe cuando usted es la única persona que tiene la clave. En su lugar, ejecute un único harness en una máquina más pequeña: un harness de agente en un VPS cumple esa función con una fracción de la memoria. Si todavía no ha elegido ninguna dirección, el análisis de comparativa de agentes de IA autoalojados es el primer paso más económico. Si lo que no conoce bien son los propios agentes y no los servidores en los que se ejecutan, siga primero un itinerario gradual para aprender cómo funcionan realmente los agentes, porque entender qué hace realmente una llamada a una herramienta y un almacén de memoria es lo que le permite determinar qué permisos debe recibir el agente de cada persona.
FAQ
¿Cuáles son los requisitos mínimos del servidor para alojar OneCLI?
Se necesita Docker con el plugin Compose 2.24.0 o posterior, Node.js y pnpm para el asistente de configuración utilizado aquí, además de memoria suficiente. PostgreSQL se incluye en el archivo de Compose, por lo que no hay que instalarlo por separado. La memoria determina la planificación: de forma predeterminada, el runner limita cada sandbox de agente a 2048 MB, y su documentación recomienda disponer de unos 10 GiB libres además de la pila base para atender el límite predeterminado de cuatro sandboxes. Según el presupuesto supuesto de 2 GB para la pila base, un equipo de 4 GB permite planificar un sandbox con su límite máximo y uno de 16 GB cubre el límite de concurrencia predeterminado. Son cifras de planificación, no requisitos mínimos medidos ni asignaciones de memoria fijas.
¿OneCLI necesita PostgreSQL o puede usar SQLite?
Necesita PostgreSQL. DATABASE_URL está documentado como una cadena de conexión de PostgreSQL, el archivo de Compose incluido ejecuta postgres:18-alpine con un volumen pgdata y un servicio de migraciones independiente aplica el esquema antes de que se inicie la API. No hay ninguna opción documentada para SQLite. Para usar un servidor PostgreSQL externo, configure la API y el servicio de migraciones para que lo utilicen; el archivo de Compose incluido establece sus cadenas de conexión con el servicio PostgreSQL incluido.
¿El sandbox del agente de OneCLI es un límite de seguridad real?
El mecanismo de Compose documentado utiliza un contenedor Docker con límites de memoria, CPU y procesos, conectado a una red marcada como internal: true para que el tráfico externo pase por el gateway. El control de salida es real y puede verificarlo con docker network inspect. El agente se ejecuta como node, con no-new-privileges, todas las capacidades de Linux eliminadas y el perfil seccomp predeterminado de Docker, pero comparte el kernel del host. El runner y el terminador SSH montan ambos /var/run/docker.sock, lo que equivale a tener root en un host que utiliza un daemon de Docker rootful. Ejecute OneCLI en un equipo dedicado y mantenga las copias de seguridad fuera de ese equipo.
¿Tengo que abrir puertos entrantes para OneCLI?
No. El runner sólo realiza conexiones salientes y no mantiene puertos accesibles desde el exterior, por lo que funciona detrás de NAT sin un túnel. De forma predeterminada, el archivo de Compose vincula el dashboard, el gateway, la API, PostgreSQL y, con el perfil runner, la puerta de entrada SSH en 10257 a 127.0.0.1. Acceda al dashboard mediante un túnel SSH o utilice la configuración de reverse proxy del proyecto upstream con TLS y las rutas necesarias para el dashboard, la API y el gateway si deben usarlo varias personas. Tenga en cuenta que el registro queda abierto a cualquiera que pueda acceder a él. El gateway en 10255 se utiliza para los agentes y, en un único equipo, esos agentes acceden a él a través de la red interna de Docker.
¿OneCLI se puede usar gratis dentro de una empresa?
El núcleo utiliza Apache-2.0 y permite el uso en producción con alojamiento propio sin una licencia comercial. Los directorios llamados ee/ están cubiertos por OneCLI Enterprise License, que es gratuita para desarrollo, pruebas y evaluación, pero requiere una suscripción en producción. La división cambia entre versiones, y las notas de v2.0.1 del 18 August 2026 mencionan que se restauró un archivo de licencia Apache-2.0 detectable en GitHub. Por tanto, compruebe LICENSE y los directorios ee/ en la etiqueta exacta que vaya a desplegar antes de crear un flujo de trabajo basado en una única funcionalidad.