Cómo ejecutar OpenCode en un VPS con tmux
Instala OpenCode en un VPS con un usuario sin privilegios, ejecutalo en tmux y protege la clave de API en un archivo con permisos privados.
Qué es OpenCode y qué va a configurar
OpenCode es un agente de programación con IA de código abierto diseñado para el terminal. Se inicia dentro de un directorio de proyecto, lee el código, propone cambios, edita archivos y ejecuta comandos desde una interfaz de usuario de terminal (TUI). Tiene licencia MIT, se conecta a más de 75 proveedores de modelos y tenía aproximadamente 224,000 estrellas en GitHub a fecha de 3 de noviembre de 2026. Para ejecutar OpenCode en un VPS, debe instalarlo con un usuario sin privilegios dedicado, guardar la clave de API del modelo en un archivo privado e iniciarlo dentro de tmux para que la sesión sobreviva si se interrumpe la conexión. Esta guía hace exactamente eso, en ese orden.
Una aclaración sobre los nombres evita confusiones. El repositorio canónico es anomalyco/opencode, mantenido por el equipo de Anomaly (antes conocido como SST), y el proyecto se encontraba anteriormente en sst/opencode. En GitHub también existe un repositorio antiguo y no relacionado llamado opencode-ai/opencode, que ahora está archivado. Compruebe que está consultando la documentación del proyecto correcto. El sitio oficial es opencode.ai.
Por qué ejecutar OpenCode en un VPS
Una sesión de un agente de programación puede ser larga. OpenCode puede tardar muchos minutos en completar una refactorización o una suite de pruebas. Si se ejecuta en el portátil, cerrar la tapa o perder la conexión Wi-Fi interrumpe la sesión mientras trabaja. En un VPS dentro de tmux, el agente sigue trabajando después de desconectarse. Más tarde, puede volver a conectarse para revisar lo que hizo. Este es el mismo patrón que ejecutar Claude Code en un VPS con tmux y es la principal mejora de comodidad al trasladar un agente fuera del portátil.
El segundo motivo es la ubicación. Un VPS está cerca del código que se implementa: el repositorio, las herramientas de compilación, la base de datos de pruebas y, a menudo, el entorno de staging ya están allí o en un sistema cercano. Un agente que modifica código y ejecuta pruebas funciona mejor en la máquina donde esas pruebas se ejecutan realmente. Además, como el sistema es un servidor bajo su control, puede proporcionarle deliberadamente un entorno aislado. La siguiente sección explica cómo hacerlo.
Si todavía está eligiendo una herramienta, ejecutar un agente de IA para programación en un VPS compara otras opciones, como Aider y Goose.
Asigne a OpenCode su propio usuario
Este es el punto de partida: un agente de programación edita archivos y ejecuta comandos. Esa es su función y también el riesgo. OpenCode ejecutará compilaciones, pruebas y los comandos de shell que parezcan necesarios para la tarea. El criterio del modelo es bueno, pero no perfecto. La cuenta con la que se ejecuta el agente limita lo que puede alcanzar un comando malicioso o incorrecto. Por eso, no lo ejecute como root ni como el mismo usuario que administra el servidor.
Esta guía ejecuta OpenCode de forma interactiva, por lo que su usuario necesita un shell real y un directorio principal:
sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencodeMantenga los proyectos en los que quiere que trabaje bajo /home/opencode y clónelos con ese usuario. No conceda privilegios sudo a la cuenta. Si el agente ejecuta un comando destructivo, puede dañar cualquier elemento que esta cuenta tenga permiso para modificar. El razonamiento es el mismo que en ejecutar servicios con un usuario sin privilegios. Trabaje también dentro de un repositorio de git y haga un commit antes de asignar una tarea al agente. Así, una modificación incorrecta del trabajo confirmado queda a un git revert o git restore de distancia, en lugar de suponer una pérdida. Los cambios que nunca confirmó no están protegidos.
Instalar OpenCode
La documentación del proyecto describe varias opciones de instalación, y dos son adecuadas para un servidor. El script de instalación es la opción más rápida, y ejecutarlo como el usuario opencode mantiene todo dentro del directorio personal de ese usuario:
curl -fsSL https://opencode.ai/install | bashLa precaución habitual de curl | bash también se aplica aquí: en un servidor importante, descargue primero el script, léalo y ejecútelo después. Tras la instalación, inicie un shell nuevo para que se aplique el cambio en PATH realizado por el instalador. Después, compruebe que el binario responde:
opencode --versionSi prefiere un gestor de paquetes y Node.js ya está instalado en el servidor, la opción de npm instala la misma herramienta en el prefijo global de npm:
sudo npm install -g opencode-aiCon un Node.js instalado para todo el sistema, ese prefijo suele ser /usr/local o /usr, cuyo directorio bin está incluido en el PATH de todos los usuarios. Un gestor de versiones o un prefijo personalizado coloca el binario en otra ubicación. Ejecute primero npm prefix -g si necesita que el usuario opencode encuentre opencode.
En ambos casos, la comprobación es la misma: opencode --version muestra un número de versión. Un command not found después de instalar mediante el script significa que el shell actual todavía no ha leído el PATH actualizado. Cierre la sesión y vuelva a iniciarla como el usuario opencode.
Ambos comandos instalan la línea OpenCode 1.x, que todavía publica versiones (1.19.5 el 28 de octubre de 2026), y esta guía describe esa línea. OpenCode 2 ya está disponible como una instalación independiente, desde https://opencode.ai/v2/install o mediante el paquete npm @opencode/cli, y funciona de otra manera: de forma predeterminada, el terminal funciona mediante un servidor en segundo plano compartido, administrado con opencode service, que ejecuta las sesiones. Su guía de migración indica que se debe eliminar una instalación de 1.x gestionada por un paquete antes de instalar la versión 2, porque ambas usan el comando opencode.
Guarde la clave de API en un archivo privado
OpenCode necesita una clave para el proveedor de modelos que use. Esa clave puede generar gastos, así que trátela como una contraseña. Cree un archivo que sólo pueda leer el usuario opencode, con el modo 600, y guarde allí la clave en lugar de escribirla en comandos, donde quedaría registrada en el historial del shell:
install -m 600 /dev/null ~/opencode.env
nano ~/opencode.envEscriba en él la variable de su proveedor, por ejemplo ANTHROPIC_API_KEY=... o su equivalente para el proveedor que use, porque OpenCode recoge las variables de entorno estándar de los proveedores. Cargue el archivo en el shell antes de iniciar el agente:
set -a; source ~/opencode.env; set +aOpenCode también ofrece una alternativa interactiva: el comando /connect dentro de la TUI le guía para añadir un proveedor y guarda la credencial en ~/.local/share/opencode/auth.json, dentro del directorio personal del usuario. Si usa esta opción, confirme que el archivo sea privado con chmod 600 ~/.local/share/opencode/auth.json. Ambas opciones mantienen la clave fuera de las líneas de comandos. Elija una y úsela de forma coherente.
Inicie OpenCode dentro de tmux
tmux es lo que hace que la configuración del VPS resulte útil, porque una sesión de tmux sigue ejecutándose cuando termina la conexión SSH. Inicie una sesión, acceda al proyecto y ejecute el agente:
tmux new -s opencode
cd ~/my-project
opencodeDebería ver la TUI abierta, con un indicador en la parte inferior y el nombre del proyecto en la interfaz. Asígnele una tarea en lenguaje natural. El agente empezará a leer archivos y a proponer cambios. Cuando quiera salir, desconéctese con Ctrl-b y después d. El agente seguirá trabajando aunque cierre el portátil. Vuelva a conectarse más tarde con:
tmux attach -t opencodeLa sesión, la conversación y cualquier tarea en ejecución estarán exactamente donde las dejó. Esto resiste las desconexiones, pero no un reinicio del servidor. Después de reiniciar, debe iniciar una sesión nueva de tmux del mismo modo. Puede abrir una segunda ventana de tmux y ejecutar otro agente junto al primero. Sin embargo, las sesiones de OpenCode son independientes entre sí, mientras que las sesiones de Claude Code en el mismo equipo pueden enviarse mensajes entre sí. Es otra forma de dividir una tarea en dos.
Apunte a un modelo
OpenCode no depende de un proveedor concreto. Usa AI SDK y el catálogo Models.dev para admitir más de 75 proveedores, por lo que la misma herramienta funciona con Anthropic, OpenAI, Google y docenas de proveedores más, incluidos servidores locales. La forma rápida es usar el comando /connect dentro de la TUI. Este comando muestra los proveedores y gestiona las credenciales. Para una configuración que pueda guardar en el repositorio y reproducir, coloque un archivo opencode.json en la raíz del proyecto y establezca el modelo con provider/model-id:
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-5-5"
}Elija un modelo que su proveedor siga ofreciendo. Anthropic retiró claude-sonnet-4-20250514 el 15 de junio de 2026, por lo que las configuraciones que todavía lo indiquen fallan.
Un modelo local funciona mediante el mismo archivo, porque cualquier servidor compatible con OpenAI puede declararse como proveedor. Si sirve un modelo con Ollama en el mismo VPS, la configuración apunta a su API local y el nombre del modelo es el que muestra ollama list en su sistema:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": { "baseURL": "http://127.0.0.1:11434/v1" },
"models": { "your-model-name": { "name": "Local coding model" } }
}
}
}Conviene adoptar desde el primer día una práctica integrada. OpenCode incluye dos agentes entre los que puede cambiar con la tecla Tab: Build, el agente predeterminado con acceso completo, y Plan, un agente restringido para análisis que rechaza editar archivos fuera de su propio directorio de planificación sin pedir permiso. Plan no es estrictamente de solo lectura, porque todavía puede ejecutar comandos de shell y un comando de shell puede modificar archivos. Inicie una tarea nueva en Plan, deje que lea el código y proponga un enfoque, y cambie a Build sólo cuando apruebe el plan. Si quiere que esa primera revisión sea realmente de solo lectura, no basta con denegar las ediciones y los comandos de shell para Plan. Plan puede delegar el trabajo en el subagente integrado Explore, que conserva su propio acceso al shell, porque las restricciones del agente principal no se aplican a los subagentes que inicia. Por tanto, deniegue las ediciones, los comandos de shell y la delegación a subagentes (el permiso task) para Plan en opencode.json, porque OpenCode interpreta deny como el bloqueo de la acción, mientras que ask sólo le pide aprobación:
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"plan": {
"permission": { "edit": "deny", "bash": "deny", "task": "deny" }
}
}
}En un servidor, una primera revisión que no pueda modificar nada es una medida preventiva barata. Claude Code plantea la misma decisión mediante modos de permisos en lugar de agentes, y conviene leer su cambio al modo auto como opción predeterminada si utiliza ambas herramientas, porque el modo con el que se inicia una sesión determina cuánto puede modificar un agente sin supervisión.
La superficie de impacto, sin rodeos
Un agente de codificación no es pasivo, así que hay que indicar claramente qué incluye esta configuración y qué no. Limita los daños en los archivos a lo que la cuenta opencode tiene permisos para modificar; el directorio del proyecto no es un sandbox. El modo 600 impide que otras cuentas sin privilegios lean el archivo de clave, pero OpenCode se ejecuta como su propietario y puede leerlo. No limita lo que la cuenta puede hacer legítimamente. Por tanto, si el directorio del proyecto contiene credenciales para desplegar en producción, el agente puede utilizarlas; manténgalas completamente fuera de la cuenta del agente.
OpenCode 1.x admite tanto la TUI interactiva utilizada aquí como la ejecución independiente y no interactiva del servidor con opencode serve. El servidor HTTP sin interfaz gráfica usa 127.0.0.1:4096 de forma predeterminada; establezca OPENCODE_SERVER_PASSWORD para exigir autenticación básica HTTP. Esta configuración con tmux no necesita una unidad de systemd, pero si habilita el modo de servidor, revise su dirección de escucha y las reglas del firewall antes de exponerlo. OpenCode 2 usa de forma predeterminada un servidor en segundo plano compartido, así que vuelva a comprobar este punto antes de migrar. La contención la proporcionan los permisos del sistema operativo de la cuenta de usuario. Por eso, la primera sección de esta guía es la más importante.
El servidor también necesita el mantenimiento habitual, porque un VPS para codificación sigue siendo un servidor público: SSH con autenticación únicamente mediante clave y el inicio de sesión de root deshabilitado, como se explica en Endurecimiento de SSH en un VPS, un firewall con denegación predeterminada y actualizaciones periódicas. Revise también lo que produce el agente. Lea sus diferencias antes de subirlas, igual que leería una solicitud de incorporación de cambios de un colaborador nuevo, porque usted es quien despliega el resultado.
Por último, mantenga actualizado el propio programa. OpenCode publica versiones con frecuencia, y las actualizaciones incluyen correcciones importantes para un programa que ejecuta comandos en el servidor. Para actualizarlo, use el mismo método con el que lo instaló: vuelva a ejecutar el script de instalación como el usuario opencode, o ejecute sudo npm update -g opencode-ai si lo instaló mediante npm; después, confirme la nueva versión con opencode --version. Ambos métodos mantienen la versión dentro de la serie 1.x; pasar a OpenCode 2 es una migración independiente. Un minuto de mantenimiento de vez en cuando cuesta menos que depurar un comportamiento que una versión de hace meses ya había corregido.
FAQ
¿Puede OpenCode usar un modelo local en lugar de una API de pago?
Sí. OpenCode trata cualquier servidor compatible con OpenAI como un proveedor, por lo que funciona un modelo servido por Ollama en el mismo VPS: declare el proveedor en opencode.json con el baseURL local y el nombre del modelo que muestra Ollama. La limitación es el hardware, porque un modelo suficientemente bueno para tareas reales de programación necesita bastante memoria. Dimensione el servidor para el modelo antes de descargarlo.
¿Cómo mantengo OpenCode en ejecución después de cerrar mi portátil?
Ejecútelo dentro de tmux en el VPS. Inicie el agente en una sesión con nombre mediante tmux new -s opencode y sepárese de ella con Ctrl-b y después d. La sesión seguirá ejecutándose en el servidor cuando termine la conexión SSH. Vuelva a conectarse en cualquier momento con tmux attach -t opencode; la conversación y cualquier tarea en ejecución seguirán disponibles. Un reinicio del servidor termina la sesión, así que inicie una nueva después del reinicio.
¿Es seguro permitir que OpenCode ejecute comandos en mi VPS?
Es controlable si lo aísla adecuadamente. Asigne a OpenCode un usuario sin privilegios y sin sudo. Mantenga sus proyectos en git y haga un commit antes de cada tarea para poder revertir una modificación incorrecta. Guarde la clave de API en un archivo con modo 600 y use su agente Plan para una primera revisión antes de permitir que el agente Build cambie algo. Si quiere que esa revisión sea estrictamente de solo lectura, establezca las ediciones, los comandos de shell y la delegación a subagentes (task) en deny para Plan, porque subagentes como Explore conservan sus propios permisos y aún pueden ejecutar comandos de shell. El agente puede acceder a todo lo que permitan los permisos del sistema operativo de su cuenta. El sistema de permisos de OpenCode no es un sandbox de seguridad.
¿Cuál es la diferencia entre OpenCode y Claude Code?
OpenCode es de código abierto (MIT) e independiente del proveedor. Se conecta a más de 75 proveedores de modelos, incluidos los locales, mediante una sola interfaz. Claude Code es el agente de terminal de Anthropic, diseñado para sus modelos. Si quiere una sola herramienta para varios proveedores o una pila completamente autohospedada con un modelo local, OpenCode es la opción adecuada. Ambos funcionan bien en un VPS dentro de tmux con la misma configuración de usuario sin privilegios.