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 diseñado 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 unos 219,000 GitHub stars en octubre de 2026, es el agente de código 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 y en ese orden.

Una nota 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 estuvo anteriormente en sst/opencode. En GitHub también existe un repositorio antiguo y no relacionado llamado opencode-ai/opencode, ahora archivado, por lo que debe comprobar 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.

Asignar a OpenCode su propio usuario

Este es el punto de partida honesto: un agente de programación edita archivos y ejecuta comandos. Ese es su trabajo y también su riesgo. OpenCode ejecutará compilaciones, pruebas y cualquier comando de shell que la tarea requiera, y el criterio del modelo es bueno pero no perfecto. La cuenta con la que se ejecuta el agente limita el alcance de un comando malintencionado, por lo que no debe ejecutarlo como root ni como el mismo usuario que administra el servidor.

A diferencia de un agente en segundo plano, OpenCode es interactivo, por lo que su usuario necesita una shell real y un directorio personal:

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

Mantenga los proyectos en los que desea que trabaje bajo /home/opencode, clonados por ese usuario. No otorgue privilegios de sudo a la cuenta. Si el agente ejecuta un comando destructivo, solo podrá destruir lo que esta cuenta posee, lo cual sigue la misma lógica que ejecutar servicios como un usuario sin privilegios. Trabaje también dentro de un repositorio git y haga commit antes de asignar una tarea al agente, ya que una edición incorrecta en el trabajo confirmado se soluciona con un git revert o un git restore en lugar de ser una pérdida. Los cambios que nunca confirmó no están protegidos.

Instalar OpenCode

El proyecto documenta varias formas de instalación, y dos de ellas 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 | bash

Aquí se aplica la práctica habitual de curl | bash, como en cualquier otro caso: 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 y compruebe después que el binario responde:

opencode --version

Si prefiere un gestor de paquetes y Node.js ya está instalado en el equipo, la opción con npm instala la misma herramienta en el prefijo global de npm:

sudo npm install -g opencode-ai

Con un Node.js instalado para todo el sistema, ese prefijo suele ser /usr/local o /usr, cuyo directorio bin está en el PATH de todos los usuarios. Un gestor de versiones o un prefijo personalizado coloca el binario en otra ubicación, por lo que ejecute primero npm prefix -g si necesita que opencode esté disponible para el usuario 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, así que cierre la sesión y vuelva a iniciarla como el usuario opencode.

Ambos comandos instalan la línea OpenCode 1.x, que sigue publicando versiones (1.19.3 el 16 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 forma: un servidor en segundo plano compartido por cada cuenta de usuario administra las sesiones, los permisos y la ejecución de herramientas, y el terminal se conecta a él. Su guía de migración indica que debe eliminar una instalación 1.x administrada por un paquete antes de instalar la versión 2, porque ambas utilizan 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.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.

Indicarle un modelo

OpenCode no depende de un proveedor concreto. Utiliza 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 otros proveedores, incluidos servidores locales. La opción rápida es el comando /connect dentro de la TUI, que muestra los proveedores y gestiona la credencial. Para preparar una configuración que pueda confirmar en el repositorio y reproducir, coloque un 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-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 ollama list muestre 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, un agente restringido para análisis que rechaza editar archivos fuera de su propio directorio de planificación sin solicitar 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 solo cuando acepte el plan. Si quiere que esa primera pasada sea realmente de solo lectura, deniegue las ediciones y los comandos de shell para Plan en opencode.json, porque OpenCode considera que deny bloquea la acción, mientras que ask solo le solicita aprobación:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

En un servidor, una primera pasada que no puede modificar nada es una medida de seguridad sencilla. Claude Code plantea la misma decisión mediante modos de permisos en lugar de agentes, y conviene leer sobre su cambio al modo automático como opción predeterminada si ejecuta ambas herramientas, porque el modo con el que se inicia una sesión determina cuánto puede modificar un agente sin supervisión.

El radio de impacto, sinceramente

Un agente de programación no es pasivo, así que defina claramente qué contiene y qué no esta configuración. Contiene riesgo de daño a archivos: el usuario opencode es propietario de su directorio home y de nada más, por lo que las ediciones y eliminaciones se detienen en ese límite. Contiene riesgo de exposición de credenciales: la clave reside en un único archivo con modo 600, en una sola cuenta. No contiene lo que la cuenta puede hacer legítimamente, por lo que si el directorio del proyecto contiene credenciales de despliegue en producción, el agente puede utilizarlas; mantenga esos elementos fuera de la cuenta del agente por completo.

A diferencia de un agente de puerta de enlace como OpenClaw, OpenCode 1.x es un programa de terminal interactivo, no un daemon. Por defecto no abre ningún puerto de escucha (solo las flags --port, --hostname o --mdns hacen que la TUI escuche) y no tiene ningún servicio en ejecución prolongada, por lo que no hay ninguna unidad de systemd que escribir ni puerto que configurar en el firewall para el agente en sí. OpenCode 2 cambia esto con su servidor compartido en segundo plano, así que verifique este punto antes de migrar. El confinamiento es la cuenta de usuario y el directorio del proyecto, razón por la cual la primera sección de esta guía es la más importante.

El entorno sigue necesitando el cuidado estándar, ya que un VPS de programación sigue siendo un servidor público: SSH solo con claves y acceso root deshabilitado, como en Endurecimiento de SSH en un VPS, un firewall con política de denegación por defecto y actualizaciones rutinarias. Además, revise lo que produce el agente. Lea sus diffs antes de enviarlos, de la misma manera que leería una pull request de un nuevo colaborador, porque usted es quien despliega el resultado.

Finalmente, mantenga la herramienta actualizada. OpenCode lanza versiones frecuentemente y las actualizaciones incluyen correcciones importantes para un programa que ejecuta comandos en su servidor. La actualización utiliza la misma ruta con la que instaló: vuelva a ejecutar el script de instalación como usuario opencode, o ejecute sudo npm update -g opencode-ai si instaló a través de npm, luego confirme la nueva versión con opencode --version. Ambos le mantienen en la línea 1.x; migrar a OpenCode 2 es un proceso distinto. Un minuto de mantenimiento de vez en cuando es más barato que depurar un comportamiento que una versión de hace meses ya tiene 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 un modelo servido por Ollama en el mismo VPS funciona: declare el proveedor en opencode.json con la baseURL local y el nombre del modelo que reporta Ollama. El inconveniente es el hardware, ya que un modelo con capacidad suficiente para tareas de programación reales requiere memoria considerable; 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, des conéctese con Ctrl-b seguido de d, y la sesión seguirá ejecutándose en el servidor después de que finalice su conexión SSH. Vuelva a conectarse en cualquier momento con tmux attach -t opencode y la conversación, junto con cualquier tarea en curso, seguirán allí. Un reinicio del servidor finaliza la sesión, por lo que debe iniciar una nueva tras reiniciar.

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

Es manejable si lo mantiene contenido. Asigne a OpenCode un usuario dedicado sin privilegios y sin acceso a sudo, mantenga sus proyectos en git y realice un commit antes de cada tarea para poder revertir una edición incorrecta, almacene la clave de API en un archivo con modo 600 y utilice su agente Plan para una primera revisión antes de permitir que el agente Build modifique algo, configurando las ediciones y los comandos de shell en deny para Plan si desea que esa fase sea estrictamente de solo lectura. El agente solo podrá dañar lo que su propia cuenta posee, y el resto del servidor permanecerá fuera de su alcance.

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

OpenCode es de código abierto (MIT) y agnóstico respecto al proveedor, conectándose a más de 75 proveedores de modelos, incluidos los locales, a través de una única interfaz. Claude Code es el agente de terminal propio de Anthropic, construido en torno a los modelos de Anthropic. Si desea una única herramienta para múltiples 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.