Cómo instalar OpenCode en un VPS

Qué es OpenCode y qué va a configurar

OpenCode es un agente de codificación con IA de código abierto diseñado para la terminal. Se inicia dentro del directorio de un 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 con más de 75 proveedores de modelos y cuenta con aproximadamente 165,000 estrellas en GitHub a mediados de 2026, siendo el agente de codificación de código abierto con más estrellas. Para ejecutar OpenCode en un VPS, debe instalarlo bajo un usuario sin privilegios, colocar su clave de API del modelo en un archivo privado e iniciarlo dentro de tmux para que la sesión persista si se pierde la conexión. Esta guía realiza exactamente esos pasos, en ese orden.

Una nota sobre el nombre evita confusiones. El repositorio oficial es anomalyco/opencode, mantenido por el equipo Anomaly (anteriormente conocido como SST), y el proyecto se encontraba en sst/opencode. Existe otro repositorio antiguo y no relacionado llamado opencode-ai/opencode en GitHub; verifique 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 es larga. OpenCode puede tardar muchos minutos en completar una refactorización o una suite de pruebas. Si se ejecuta en su laptop, cerrar la tapa o perder la conexión Wi-Fi interrumpirá la sesión a mitad de la tarea. En un VPS dentro de tmux, el agente continúa trabajando tras la desconexión y usted puede reanudar la sesión más tarde para revisar los resultados. Este es el mismo patrón que ejecutar Claude Code en un VPS con tmux, y es la mayor mejora de calidad de vida al mover un agente fuera de su laptop.

La segunda razón es la ubicación. Un VPS está cerca del código que despliega: el repositorio, las herramientas de compilación, la base de datos de pruebas y, a menudo, el entorno de staging ya residen allí o en la misma red. Un agente que edita código y ejecuta pruebas funciona mejor en la máquina donde se ejecutan dichas pruebas. Además, al ser un servidor bajo su control, puede proporcionar al agente un entorno aislado, como se explica en la siguiente sección.

Si aún está eligiendo una herramienta, ejecutar un agente de IA de programación en un VPS compara diversas opciones, incluyendo Aider y Goose.

Asigne un usuario propio a OpenCode

Este es el punto de partida: un agente de programación edita archivos y ejecuta comandos. Esa es su función y también su riesgo. OpenCode ejecutará builds, tests y cualquier comando de shell que la tarea requiera; el criterio del modelo es bueno, pero no es perfecto. El alcance de un comando malintencionado está limitado por los permisos del usuario que ejecuta el agente. No lo ejecute 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 un shell real y un directorio home:

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

Mantenga los proyectos en los que deba trabajar bajo /home/opencode, clonados por dicho usuario. No otorgue permisos de sudo a esta cuenta. Si el agente ejecuta un comando destructivo, solo podrá destruir lo que este usuario posea; este es el mismo principio que ejecutar servicios como un usuario sin privilegios. Trabaje también dentro de un repositorio git, ya que un repositorio convierte cualquier edición errónea en un git revert en lugar de una pérdida de datos.

Instalar OpenCode

El proyecto documenta dos métodos de instalación. El script de instalación es el más rápido. Ejecutarlo como el usuario opencode mantiene todo dentro del home de dicho usuario:

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

Se aplica la práctica habitual de curl | bash: en un servidor importante, descargue primero el script, léalo y luego ejecútelo. Tras la instalación, inicie una nueva shell para que los cambios en el PATH realizados por el instalador surtan efecto, y luego verifique la respuesta del binario:

opencode --version

Si prefiere un gestor de paquetes y Node.js ya está instalado en el equipo, la ruta de npm instala la misma herramienta de forma global. Esto añade el binario opencode al PATH para todos los usuarios:

sudo npm install -g opencode-ai

En ambos casos, la verificación es la misma: opencode --version muestra un número de versión. Un command not found tras la instalación mediante el script significa que la shell actual aún no ha leído el PATH actualizado; cierre sesión e inicie sesión nuevamente como el usuario opencode.

Guardar la clave API en un archivo privado

OpenCode requiere una clave para el proveedor de modelo que utilice. Esta clave puede generar cargos económicos, por lo que debe tratarse como una contraseña. Cree un archivo con modo 600 que solo el usuario opencode pueda leer. Guarde la clave allí en lugar de escribirla directamente en los comandos para evitar que quede registrada en el historial de la shell:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

Escriba la variable de su proveedor en el archivo, por ejemplo ANTHROPIC_API_KEY=... o el equivalente para su proveedor, ya que OpenCode utiliza las variables de entorno estándar de los proveedores. Cargue el archivo en su 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 guía el proceso para añadir un proveedor y guarda la credencial en ~/.local/share/opencode/auth.json en el home del usuario. Si utiliza este método, verifique que el archivo sea privado con chmod 600 ~/.local/share/opencode/auth.json. Ambos métodos evitan que la clave aparezca en las líneas de comandos; elija uno y manténgase consistente.

Iniciar OpenCode dentro de tmux

tmux es la herramienta clave para la configuración del VPS, ya que una sesión de tmux sigue ejecutándose cuando la conexión SSH finaliza. Inicie una, acceda a su proyecto y lance el agente:

tmux new -s opencode
cd ~/my-project
opencode

Debería ver la TUI abierta con un prompt en la parte inferior y el nombre de su proyecto en la interfaz. Indique una tarea en lenguaje natural y el agente comenzará a leer archivos y proponer cambios. Para salir, desvincule la sesión con Ctrl-b y luego d; el agente continuará trabajando aunque cierre su laptop. Para volver a conectar más tarde, use:

tmux attach -t opencode

La sesión, la conversación y cualquier tarea en ejecución permanecerán exactamente donde las dejó. Esto sobrevive a las desconexiones, pero no a un reinicio del servidor; tras un reinicio, debe iniciar una nueva sesión de tmux de la misma manera.

Conéctelo a un modelo

OpenCode es agnóstico al proveedor. Utiliza el AI SDK y el catálogo Models.dev para soportar más de 75 proveedores; por tanto, la misma herramienta funciona con Anthropic, OpenAI, Google y docenas más, incluyendo servidores locales. La vía rápida es el comando /connect dentro de la TUI, que enumera los proveedores y gestiona las credenciales. Para una configuración que se pueda confirmar y reproducir, coloque un opencode.json en la raíz del proyecto y defina 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, ya que cualquier servidor compatible con OpenAI puede declararse como proveedor. Si ejecuta un modelo con Ollama en la misma 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" } }
    }
  }
}

Es recomendable adoptar un hábito integrado desde el primer día. OpenCode incluye dos agentes que se alternan con la tecla Tab: Build, el agente predeterminado con acceso total, y Plan, que desactiva la capacidad de realizar cambios. Inicie una nueva tarea en Plan, permita que lea el código y proponga un enfoque, y cambie a Build solo cuando esté de acuerdo con el plan. En un servidor, una primera pasada de solo lectura es una medida de seguridad económica.

El radio de impacto, sinceramente

Un agente de codificación no es pasivo, así que defina claramente qué incluye y qué no incluye esta configuración. Incluye daños en archivos: el usuario opencode es propietario de su propio home y nada más, por lo que las ediciones y eliminaciones se detienen en ese límite. Incluye exposición de credenciales: la clave reside en un único archivo con modo 600, en una sola cuenta. No incluye las acciones que la cuenta puede realizar legítimamente; si el directorio del proyecto contiene credenciales de despliegue de producción, el agente puede usarlas. Mantenga esas credenciales fuera de la cuenta del agente por completo.

A diferencia de un agente de puerta de enlace como OpenClaw, OpenCode es un programa de terminal interactivo, no un daemon. No abre ningún puerto de escucha ni tiene un servicio de larga duración, por lo que no es necesario escribir una unidad systemd ni configurar un firewall para el agente en sí. El aislamiento consiste en la cuenta de usuario y el directorio del proyecto; por ello, la primera sección de esta guía es la más importante.

El entorno aislado requiere el mantenimiento estándar, ya que un VPS de codificación sigue siendo un servidor público: SSH solo mediante clave con el login de root deshabilitado, como se indica en SSH hardening on a VPS, un firewall con política de denegación por defecto y actualizaciones rutinarias. Además, revise lo que el agente produce. Lea sus diffs antes de hacer push, de la misma forma que leería un pull request de un nuevo colaborador, ya que usted es quien despliega el resultado.

Finalmente, mantenga la herramienta actualizada. OpenCode lanza versiones con frecuencia, y las actualizaciones incluyen correcciones críticas para un programa que ejecuta comandos en su servidor. La actualización utiliza el mismo método que la instalación: ejecute el script de instalación como el usuario opencode, o ejecute sudo npm update -g opencode-ai si instaló mediante npm, y luego confirme la nueva versión con opencode --version. Un minuto de mantenimiento ocasional es más económico que depurar un comportamiento que una versión antigua 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. Un modelo servido por Ollama en el mismo VPS funciona: declare el proveedor en opencode.json con el baseURL local y el nombre del modelo que reporte Ollama. El factor limitante es el hardware, ya que un modelo apto para tareas de programación requiere mucha memoria; dimensione el servidor para el modelo antes de descargarlo.

¿Cómo mantengo OpenCode ejecutándose después de cerrar mi laptop?

Ejecútelo dentro de tmux en el VPS. Inicie el agente en una sesión con nombre usando tmux new -s opencode, desvincule con Ctrl-b y luego d; la sesión continuará ejecutándose en el servidor tras finalizar la conexión SSH. Reincorpórese en cualquier momento con tmux attach -t opencode y la conversación y 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 se limita su alcance. Asigne a OpenCode un usuario dedicado sin privilegios y sin sudo, mantenga sus proyectos en git para que cada edición sea reversible, guarde la clave API en un archivo con modo 600 y utilice su agente Plan para una primera pasada de solo lectura antes de permitir que el agente Build realice cambios. El agente solo podrá afectar a los archivos que pertenezcan a su propia cuenta, manteniendo el resto del servidor fuera de su alcance.

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

OpenCode es de código abierto (MIT) y agnóstico al proveedor; se conecta a más de 75 proveedores de modelos, incluidos los locales, mediante una única interfaz. Claude Code es el agente de terminal propio de Anthropic, diseñado para los modelos de Anthropic. Si necesita una herramienta para múltiples proveedores, o un stack totalmente auto-alojado con un modelo local, OpenCode es la opción adecuada; ambos funcionan correctamente en un VPS dentro de tmux con la misma configuración de usuario sin privilegios.