Cómo ejecutar OpenCode en un VPS con tmux

Qué es OpenCode y qué va a configurar

OpenCode es un agente de IA de código abierto para el terminal. Se inicia dentro de un directorio de proyecto, lee el código, propone cambios, edita archivos y ejecuta comandos, todo desde una interfaz de usuario de terminal (TUI). Tiene licencia MIT, se conecta a más de 75 proveedores de modelos y, con aproximadamente 165,000 estrellas en GitHub a mediados de 2026, es el agente de programación de código abierto con más estrellas. Para ejecutar OpenCode en un VPS, debe instalarlo con un usuario dedicado sin privilegios, 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, así que compruebe que está leyendo 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.

Dê a OpenCode seu próprio usuário

O ponto de partida é simples: um agente de programação edita arquivos e executa comandos. Essa é a função dele e também o risco. OpenCode executará compilações, testes e quaisquer comandos de shell que a tarefa pareça exigir, e o julgamento do modelo é bom, mas não é perfeito. A conta usada pelo agente define o limite do que um comando malicioso ou incorreto pode alcançar. Portanto, não o execute como root nem como o mesmo usuário que administra o servidor.

Ao contrário de um agente em segundo plano, OpenCode é interativo. Por isso, seu usuário precisa de um shell real e de um diretório pessoal:

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

Mantenha os projetos que você quer que ele processe em /home/opencode, clonados por esse usuário. Não conceda direitos de sudo à conta. Se o agente executar um comando destrutivo, ele só poderá destruir o que essa conta possui. Esse é o mesmo princípio de executar serviços como um usuário sem privilégios. Trabalhe também dentro de um repositório git, porque um repositório transforma qualquer edição incorreta em um git revert, em vez de uma perda.

Instalar OpenCode

El proyecto documenta dos métodos de instalación. El script de instalación es el más rápido, y ejecutarlo como el usuario opencode mantiene todo dentro del directorio personal de ese usuario:

curl -fsSL https://opencode.ai/install | bash

La práctica habitual de curl | bash también se aplica aquí: en un servidor importante, descargue primero el script, léalo y después ejecútelo. Tras la instalación, inicie un shell nuevo para que se aplique el cambio de PATH realizado por el instalador. Después, compruebe que el binario responde:

opencode --version

Si prefiere un gestor de paquetes y Node.js ya está instalado en el servidor, la opción de npm instala la misma herramienta para todo el sistema. Así, el binario opencode queda disponible en el PATH de todos los usuarios:

sudo npm install -g opencode-ai

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 indica 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.

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.env

Escriba 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 +a

OpenCode 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
opencode

Deberí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 opencode

La 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 OpenCode 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 decenas de proveedores más, incluidos servidores locales. La vía rápida es el comando /connect dentro de la TUI, que muestra los proveedores y gestiona las credenciales. Para una configuración que pueda confirmar en el repositorio y reproducir, coloque un archivo opencode.json en la raíz del proyecto y establezca el modelo como provider/model-id:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

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 muestre ollama list en su equipo:

{
  "$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, que deshabilita la capacidad de realizar cambios. 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. En un servidor, una primera revisión de sólo lectura es una medida preventiva sencilla. Claude Code plantea la misma decisión mediante modos de permisos en lugar de agentes, y vale la pena leer su cambio al modo automático 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.

El alcance del daño, sin rodeos

Un agente de programación no es pasivo, así que hay que indicar claramente qué contiene esta configuración y qué no. Sí contiene los daños en archivos: el usuario opencode es propietario de su propio directorio personal y de nada más, por lo que las modificaciones y eliminaciones se detienen en ese límite. Sí contiene la exposición de credenciales: la clave está en un único archivo con permisos 600, dentro de una única cuenta. No contiene lo que la cuenta puede hacer legítimamente. Por tanto, si el directorio del proyecto contiene credenciales de despliegue de producción, el agente puede utilizarlas. Manténgalas completamente fuera de la cuenta del agente.

A diferencia de un agente de puerta de enlace como OpenClaw, OpenCode es un programa interactivo de terminal, no un daemon. No abre ningún puerto en escucha ni tiene un servicio de larga duración. Por tanto, no hay ninguna unidad de systemd que crear ni ningún puerto que filtrar para el propio agente. La contención la proporcionan la cuenta de usuario y el directorio del proyecto. Por eso la primera sección de esta guía es la más importante.

El sistema que lo rodea sigue necesitando el mantenimiento habitual, porque un VPS de programación sigue siendo un servidor público: SSH con autenticación exclusiva 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 enviarlas, del mismo modo que leería una solicitud de incorporación de cambios de un colaborador nuevo, porque usted es quien despliega el resultado.

Por último, mantenga actualizada la propia herramienta. OpenCode publica versiones con frecuencia, y las actualizaciones incluyen correcciones importantes para un programa que ejecuta comandos en el servidor. La actualización utiliza el mismo método con el que realizó la instalación: vuelva a ejecutar el script de instalación como el usuario opencode, o ejecute sudo npm update -g opencode-ai si instaló mediante npm. Después, confirme la nueva versión con opencode --version. Un minuto de mantenimiento ocasional 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 mucha memoria. Dimensione el servidor para el modelo antes de descargarlo.

¿Cómo mantengo OpenCode en ejecución después de cerrar el portátil?

Ejecútelo dentro de tmux en el VPS. Inicie el agente en una sesión con nombre mediante tmux new -s opencode, desconéctese 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, por lo que debe iniciar otra después del reinicio.

¿Es seguro permitir que OpenCode ejecute comandos en mi VPS?

Es viable si lo mantiene aislado. Asigne a OpenCode un usuario dedicado sin privilegios y sin sudo, mantenga sus proyectos en git para que todos los cambios se puedan revertir, almacene la clave de API en un archivo con el modo 600 y use su agente Plan para una primera revisión de solo lectura antes de permitir que el agente Build cambie algo. De este modo, el agente sólo puede dañar lo que pertenece a su propia cuenta y el resto del servidor queda fuera de su alcance.

¿Cuál es la diferencia entre OpenCode y Claude Code?

OpenCode es de código abierto (MIT) y no depende de un proveedor concreto. Se conecta a más de 75 proveedores de modelos, incluidos los locales, mediante una sola interfaz. Claude Code es el agente de terminal propio de Anthropic y está diseñado para trabajar con los modelos de Anthropic. Si necesita una sola herramienta para varios proveedores o una pila totalmente 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.