Cómo alojar OneCLI: un agente aislado por persona

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 entorno aislado. 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. La configuración predeterminada documentada es de 2 GiB de memoria por entorno aislado de agente. Por tanto, esta carga no es adecuada para un VPS de 1 GB.

La pila incluye siete componentes. Saber cuál es cada uno facilita la lectura del resto de esta guía.

• Panel web (Next.js), puerto 10254. Creación de agentes, chat, edición de memoria y habilidades, conexiones y secretos.
• Servidor de API, puerto 10256. Es el plano de control: base de datos, gestión de conversaciones y 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 entornos aislados de los agentes. Sólo permite conexiones salientes y nunca accede a la base de datos».
• Supervisor de entornos aislados. El README lo describe como un componente que se ejecuta «dentro de cada entorno aislado y se comunica mediante una interfaz de harness independiente del proveedor, de modo que el runtime del agente se puede sustituir».
• Adaptador de canal. 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-alpine con un volumen pgdata.

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 dirige el tráfico de un 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 en el que la primera cuenta es propietaria de la instancia, 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 a cada agente el acceso que necesita y trabaja en un entorno aislado, a través de una puerta de enlace que inyecta las credenciales y aplica la política definida". Cada agente tiene su propio sistema de archivos y shell, su propia página de conversaciones, la memoria que conserva la plataforma y las skills 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 la clave una sola vez y se concede acceso a los agentes autorizados para usarla.

Requisitos del servidor antes de empezar

• Docker, con el complemento Compose en la versión 2.19 o posterior. El archivo Compose usa un servicio de migraciones de ejecución única del que depende la API, y esta forma de declarar la dependencia requiere la versión 2.19.
• Memoria, que es la limitación real. Lea la sección sobre dimensionamiento más abajo antes de elegir un plan.
• Puertos de loopback libres 10254, 10255, 10256 y 5432.

No necesita instalar PostgreSQL manualmente: el archivo Compose lo ejecuta como un servicio. Tampoco necesita Node.js ni Rust. Solo se utilizan en el procedimiento de compilación desde el código fuente, donde mise fija la cadena de herramientas.

¿Cuántos entornos aislados de agentes caben en tu VPS?

La documentación del propio runner proporciona cifras reales, no impresiones. Cada entorno aislado obtiene 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.

[
  {
    "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, no una prueba de rendimiento: la memoria total, menos aproximadamente 2 GB para PostgreSQL y los cuatro servicios de ejecución prolongada, dividida entre el límite de 2 GiB por entorno aislado. Con esa base, 2 GB box admite 0 entornos aislados, por lo que el plan más barato no puede ejecutar un agente alojado. Un 16 GB box deja espacio para 7, claramente 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.

Dos factores modifican ese cálculo. Un entorno aislado con un proceso en segundo plano en ejecución nunca queda aparcado, por lo que conserva su slot de forma permanente. Por tanto, dimensiona RUNNER_MAX_SANDBOXES para la carga sostenida, no para el minuto de mayor actividad. Además, la memoria se agota antes que la CPU. Cada entorno aislado está limitado a una CPU, así que cuatro agentes ocupados necesitan cuatro núcleos, pero cuatro agentes inactivos que siguen despiertos todavía ocupan 8 GiB.

Instalar OneCLI con Docker Compose

La documentación de self-hosting del proyecto proporciona esta secuencia exacta. Escribe tres secretos en docker/.env, junto al archivo de Compose, y después inicia 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
docker compose up -d --wait

Lea ese bloque antes de ejecutarlo. El marcador del heredoc no está entre comillas, por lo que el shell ejecuta cada head -c 32 /dev/urandom | base64 y escribe el resultado, no el texto literal. SECRET_ENCRYPTION_KEY es la clave AES-256-GCM de todos los secretos de la base de datos. GATEWAY_INTERNAL_SECRET autentica el gateway frente a 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 nunca se inicia ningún sandbox de agente.

--wait mantiene el shell bloqueado hasta que todos los servicios informan de un estado healthy, por lo que una salida distinta de cero es la primera señal de que algo falla. Después, compruebe qué se inició realmente.

docker compose ps
docker compose logs migrations

Fije la versión. ONECLI_VERSION establece el tag de todos los servicios a la vez, y la imagen del sandbox de agente lo sigue, salvo que RUNNER_AGENT_IMAGE apunte a otro lugar. A fecha de 19 August 2026, la versión actual es v2.0.1, publicada el 18 August 2026. Añádala al mismo archivo y vuelva a iniciar el stack.

echo 'ONECLI_VERSION=v2.0.1' >> .env
docker compose up -d --wait

También existe un instalador, curl -fsSL https://onecli.sh/install | sh, que escribe su configuración en ~/.onecli/.env y realiza el mismo trabajo. La ruta de Compose permite leer todos los archivos antes de ejecutar nada y es la opción adecuada en un servidor que ya ejecuta otros stacks de Compose. La compilación desde el código fuente es una tercera opción, documentada como pnpm install y después pnpm run setup en el repositorio clonado. Esta opción requiere mise, Rust para el gateway y Docker de todos modos, y está destinada a quienes pretenden modificar el código.

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-server

Ahora abra http://localhost:10254 en el portátil. El tráfico circula por la conexión SSH. Por tanto, el panel no queda expuesto sin cifrar en Internet y no es necesario abrir otro puerto en el firewall.

Configurar ONECLI_BIND_HOST=0.0.0.0 publica el panel mediante HTTP sin cifrado y también publica PostgreSQL. Si varias personas necesitan acceder al panel, coloque un proxy inverso con TLS (seguridad de la capa de transporte) delante del puerto 10254 y mantenga sin cambios el host de enlace. Hágalo antes de que la instancia tenga un propietario. La documentación original explica claramente el motivo: "Hasta que lo haga, la instancia no tiene propietario y, en un host accesible, el primero que llegue se convierte en uno." Si ese proxy ya está delante de las demás aplicaciones autohospedadas, reenviar la autenticación mediante una capa de inicio de sesión único autohospedada coloca el panel detrás del inicio de sesión que ya utiliza su equipo. Así, eliminar a alguien en un solo lugar también cierra este acceso.

Cree primero la cuenta y, después, conceda una clave de modelo

Abra el panel y cree la cuenta de inmediato. Esa cuenta es la propietaria de la instancia. Cuando existe, es necesario invitar a los demás para que puedan unirse.

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 después inicie una conversación. Si omite la concesión, el sandbox nunca se inicia. El agente queda inactivo.

Conceda únicamente los permisos necesarios. Cada agente recibe sólo lo que usted le concede y el gateway aplica esa restricción 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 mantiene el gateway 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 provisional en lugar de una real. El gateway compara la petición saliente con las autorizaciones de ese agente, descifra el secreto real, lo sustituye en la petición 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 cuando se procesa la petición. Cada llamada se registra con la identidad del agente y su destino. Esto crea un registro de auditoría que no se obtiene cuando las claves están en los perfiles de shell de diez personas.

Dos aspectos determinan cómo se implementa.

• La interceptación HTTPS es un ataque man-in-the-middle. El gateway genera una autoridad de certificación local, el agente confía en ella y el gateway termina la conexión TLS del agente y abre otra nueva con el servicio upstream. Por eso, si el cliente HTTP de un agente no confía en la autoridad de certificación del gateway, falla con un error de verificación del certificado y no con un error de autenticación.
• El agente se identifica con 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 suya. Si se apunta un agente externo al gateway, el puerto del proxy necesita su propio TLS, porque esa cabecera es un token de portador.

La contrapartida es clara: el gateway lee en texto plano todas las peticiones 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 Linux con privilegios mínimos.

Por qué el runner no necesita un puerto entrante

El runner sólo inicia conexiones salientes. Según su documentación: «no mantiene ningún puerto al que pueda acceder el exterior, por lo que funcionan un portátil, un homelab o una VPC detrás de NAT sin ingress, sin túnel y sin necesidad de terminar TLS». NAT significa traducción de direcciones de red, como la que realiza un router doméstico. El runner inicia una conexión con el plano de control y obtiene trabajo de él. Por tanto, 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. En Docker, esto significa que no existe ninguna ruta fuera del host. Los sandboxes se conectan a ella. El gateway tiene interfaces en ambas redes, por lo que es la única salida. La documentación del runner lo indica claramente: «una red internal con el gateway conectado a ambas redes 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 que decida enviar el código fuente a una dirección que elija no tiene ninguna ruta para hacerlo.

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 internal

Debería ver "Internal": true. Si aparece false, el control de salida está desactivado y el gateway vuelve a ser una simple recomendación. Use el nombre de la red del sandbox que muestre docker network ls, porque onecli-sandboxes sólo es el valor predeterminado.

¿Qué nivel de aislamiento ofrece el sandbox de OneCLI?

Lea esta sección despacio, porque el término «sandbox» tiene mucho peso en la descripción del propio proyecto, mientras que el mecanismo sólo está documentado en un lugar.

El README indica que cada agente obtiene «su propio sandbox aislado, con un sistema de archivos y un shell», y señala Sandbox Supervisor 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 pueda sustituir». 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 límites de memoria, CPU y procesos, conectado a la red interna. El código deja una interfaz para otros backends, y la documentación menciona Kubernetes y las microVM como módulos que alguien tendría que implementar. Actualmente, en su equipo, un sandbox es un contenedor.

Lo que la documentación no dice es igual de importante. No existe un modelo de amenazas. Tampoco hay ninguna declaración sobre ejecutar el daemon de Docker en modo rootless, el remapeo de user namespaces o los perfiles de seccomp o AppArmor más allá de los valores predeterminados de Docker. No hay ninguna afirmación sobre un límite basado en el kernel, como gVisor o una microVM. Por tanto, adopte la interpretación más limitada. Los límites son límites de recursos. La red interna es un control real de las conexiones salientes. El aislamiento entre un agente y su host es el que proporciona un contenedor Docker estándar, y un contenedor comparte el kernel del host.

Hay un segundo hecho que debe tener en cuenta. El servicio runner monta /var/run/docker.sock porque así crea los sandboxes. El acceso al socket de Docker 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 en su interior. Todos los runners basados en Docker funcionan así. La consecuencia es que el proceso runner es tan sensible como el gateway.

Considere que el límite no está demostrado hasta que el proyecto upstream lo documente. En la práctica, esto implica tres hábitos.

1. Ejecute OneCLI en un equipo que no haga nada más. No aloje allí ningún servicio de producción no relacionado, ninguna base de datos compartida ni datos de otro equipo.
2. Suponga que un agente que obtenga ejecución de 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.
3. Lea apps/runner/src o consulte al proyecto upstream antes de decirle 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 upstream, compare este contenido con cómo es el límite de un sandbox real para agentes. La diferencia está en si alguien ha documentado el mecanismo y ha especificado qué cosas no impide.

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 consisten en cambiar la versión y reiniciar. Un servicio de migraciones de ejecución única se ejecuta antes que la API en cada up. Si una migración falla, la pila no se inicia en lugar de atender peticiones con un esquema migrado parcialmente. Este es el comportamiento esperado, porque un fallo de actualización se manifiesta como una interrupción del servicio y no como una corrupción silenciosa. docker compose logs migrations explica el motivo.

cd onecli/docker
docker compose pull
docker compose up -d --wait
docker compose logs migrations

Si realizó la instalación con el script de instalación, vuelva a ejecutar ese script en lugar de descargar los archivos manualmente. Así, el archivo Compose se mantiene sincronizado con las imágenes a las que hace referencia.

Haga una copia de seguridad de dos elementos. 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, por lo que un volcado de la base de datos por sí solo no restaura nada utilizable.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Guarde ambas copias fuera del servidor. El procedimiento es el mismo que necesita cualquier pila Compose con estado. Si ya hace copias de seguridad y actualiza una pila Docker Compose de forma programada, añada estas dos rutas y deje de preocuparse por ello.

Cuando no funciona

• La pila nunca llega al estado healthy y docker compose up -d --wait termina con un código distinto de cero. Lea primero docker compose logs migrations, porque la API espera deliberadamente a que ese servicio esté disponible.
• Un agente permanece inactivo y no aparece ningún sandbox. Compruebe que COMPOSE_PROFILES=runner esté en docker/.env y que docker compose ps muestre un runner. Después, compruebe que el agente tenga una clave de modelo concedida, porque los sandboxes no se inician sin ella.
• No quedan slots. RUNNER_MAX_SANDBOXES tiene el valor predeterminado 4, y un sandbox con un proceso en segundo plano en ejecución conserva su slot de forma permanente. docker ps muestra qué procesos siguen realmente activos.
• Los contenedores desaparecen o el host funciona con mucha lentitud. Se ha quedado sin memoria. dmesg -T | grep -i oom registra las terminaciones por falta de memoria del kernel, y un solo sandbox puede reclamar 2048 MB por sí mismo.
• Las llamadas HTTPS de un agente fallan con errores de verificación de certificados en lugar de 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 que superan 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, implica mucha infraestructura sin aportar ventajas. 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 posee la clave. Ejecute en su lugar un único harness en un equipo más pequeño: 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 opción, el análisis de comparativa de agentes de IA autoalojados es un primer paso más económico.

FAQ

¿Cuáles son los requisitos mínimos del servidor para alojar OneCLI?

Docker con el complemento Compose en la versión 2.19 o posterior, y memoria suficiente. PostgreSQL se incluye en el archivo Compose, por lo que no es necesario instalarlo por separado. La memoria determina el plan: el runner asigna 2048 MB por sandbox de agente de forma predeterminada, su documentación solicita alrededor de 10 GiB libres además de la pila base para atender el límite predeterminado de cuatro sandboxes, y aproximadamente 2 GB se destinan a PostgreSQL y a los cuatro servicios de ejecución prolongada. Un equipo con 4 GB ejecuta un agente cada vez. Un equipo con 16 GB cubre cómodamente el límite predeterminado. Una VPS de 1 GB o 2 GB no puede iniciar ningún agente alojado.

¿OneCLI necesita PostgreSQL o puede usar SQLite?

Necesita PostgreSQL. DATABASE_URL está documentado como una cadena de conexión de PostgreSQL, el archivo 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 de SQLite documentada. Si ya ejecuta PostgreSQL en otro lugar, apunte DATABASE_URL a esa instancia y mantenga el servicio de migraciones, porque una migración fallida detiene la pila en lugar de permitir que sirva un esquema aplicado parcialmente.

¿El sandbox del agente de OneCLI es un límite de seguridad real?

El mecanismo documentado es un contenedor Docker con límites de memoria, CPU y procesos, conectado a una red marcada como internal: true para que no tenga ninguna ruta de salida salvo a través de la gateway. El control del tráfico saliente es real y puede verificarlo con docker network inspect. El aislamiento del host tiene el nivel de un contenedor, y el proyecto no publica ningún modelo de amenazas, ninguna afirmación sobre rootless o espacios de nombres de usuario, ni ningún límite del kernel como gVisor o una microVM. El runner también monta /var/run/docker.sock, lo que equivale a tener root en el host. Considere que el límite entre el agente y el host no está demostrado hasta que el proyecto lo documente, ejecute OneCLI en un equipo dedicado y mantenga las copias de seguridad fuera de ese equipo.

¿Es necesario abrir algún puerto entrante para OneCLI?

No. El runner sólo realiza conexiones salientes y no mantiene ningún puerto accesible desde el exterior, por lo que funciona detrás de NAT sin un túnel. El archivo Compose enlaza el dashboard, la gateway, la API y PostgreSQL a 127.0.0.1 de forma predeterminada. Acceda al dashboard mediante un túnel SSH o coloque un reverse proxy con TLS delante del puerto 10254 si varias personas necesitan acceder. La gateway del puerto 10255 se utiliza para los agentes y, en un solo equipo, esos agentes acceden a ella a través de la red interna de Docker.

¿OneCLI se puede usar gratis dentro de una empresa?

El núcleo se distribuye con Apache-2.0 y se permite su 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 separación cambia entre releases, y las notas de v2.0.1 del 18 August 2026 mencionan que se restauró un archivo de licencia Apache-2.0 detectable por GitHub. Por ello, compruebe LICENSE y los directorios ee/ en el tag exacto que vaya a desplegar antes de crear un flujo de trabajo basado en una única funcionalidad.