Anexo G: OpenCode - Mini-Curso para Gestión de Servidores

Flujos de trabajo seguros para diagnosticar, automatizar y documentar cambios

Author

Diego Saavedra

Published

Feb 8, 2026

Anexo G: OpenCode - Mini-Curso para Gestión de Servidores

Introducción

OpenCode es un asistente interactivo para tareas de ingeniería de software. En gestión de servidores, su valor aparece cuando necesitas:

diagnosticar incidentes con evidencia (logs, métricas, configuraciones)
generar procedimientos repetibles (runbooks)
automatizar tareas con scripts (Bash/PowerShell) y herramientas de provisioning
reducir errores humanos (checklists, validaciones, comandos con modo seguro)

Ver guía completa de configuración en: SETUP.qmd

Tiempo estimado: 45-60 minutos

Objetivos de aprendizaje

Al finalizar este mini-curso podrás:

recolectar evidencia básica del sistema sin interrumpir el servicio
pedir a OpenCode un plan de diagnóstico paso a paso (y verificarlo)
generar comandos seguros (read-only primero, luego cambios)
documentar y estandarizar una corrección en un runbook
crear una automatización pequeña (script) para tareas repetidas

Reglas de seguridad (antes de usar AI)

ADVERTENCIA CRITICA

Nunca pegues secretos en OpenCode.

Lo que podría salir mal: - Filtras credenciales (tokens, claves privadas, passwords) en historiales, logs o capturas. - Compartes informacion sensible (IPs publicas, nombres internos, rutas) que se usa para ataques.

Cómo prevenirlo: 1. Redacta secretos antes de pegar texto (reemplaza por REDACTED). 2. Comparte solo el mínimo necesario (1-2 comandos, 20-50 líneas de log, el error completo). 3. Prefiere comandos de lectura primero (status, show, --dry-run).

Flujo recomendado: evidencia -> análisis -> acción

Evidencia: captura estado del sistema, servicio y logs (sin modificar nada).
Análisis con OpenCode: pega evidencia y pide hipótesis + plan de verificación.
Acción controlada: ejecuta cambios pequeños, reversibles y con verificación.
Documentación: convierte lo aprendido en runbook (pasos, comandos, rollback).

Instalación de OpenCode

OpenCode se puede instalar como binario (script), como paquete Node, o via Homebrew.

BASH

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

1: curl … | bash instala el binario de OpenCode usando el instalador oficial.

BASH

1$ npm install -g opencode-ai
2$ pnpm install -g opencode-ai
3$ bun install -g opencode-ai

1: npm install -g instala OpenCode globalmente.
2: pnpm install -g instala OpenCode globalmente usando pnpm.
3: bun install -g instala OpenCode globalmente usando bun.

BASH

1$ brew install anomalyco/tap/opencode

1: brew install anomalyco/tap/opencode instala la versión más actual desde el tap oficial.

POWERSHELL

1PS> choco install opencode
2PS> scoop install opencode
3PS> npm install -g opencode-ai

1: choco install instala OpenCode con Chocolatey.
2: scoop install instala OpenCode con Scoop.
3: npm install -g instala OpenCode via Node.js.

OpenCode Desktop (Beta)

Desde v1.1.0, OpenCode ofrece una aplicación de escritorio con interfaz gráfica.

Descarga e instalación

BASH

1$ brew install --cask opencode

1: brew install –cask instala la aplicación de escritorio de OpenCode.

POWERSHELL

1PS> winget install Anomaly.OpenCode

1: winget install descarga e instala OpenCode Desktop.

BASH

1$ wget https://opencode.ai/download/linux
2$ chmod +x opencode-*.AppImage
3$ ./opencode-*.AppImage

1: wget descarga el AppImage de OpenCode.
2: chmod +x hace ejecutable el archivo.
3: **./opencode-*.AppImage** ejecuta la aplicación.

💡 RECOMENDACIÓN

¿Terminal o Desktop?

Usa Terminal (TUI) cuando: - Trabajas en servidores remotos vía SSH - Necesitas integración con scripts - Prefieres flujos de trabajo keyboard-centric

Usa Desktop cuando: - Necesitas visualizar archivos y árbol de proyecto - Prefieres interfaz gráfica para revisar cambios - Trabajas en proyectos locales con muchos archivos

Configurar proveedor (LLM)

OpenCode requiere un proveedor/modelo (y sus credenciales) para funcionar.

En la TUI, el camino más simple es:

TEXT

/connect

1: /connect abre el flujo para configurar un proveedor (por ejemplo, OpenCode Zen u otro provider).

Inicializar un proyecto (/init)

Entra a tu repo/proyecto y levanta OpenCode:

BASH

1$ cd /path/to/project
2$ opencode

1: cd cambia al proyecto que vas a administrar.
2: opencode inicia la interfaz TUI.

Luego, inicializa el proyecto:

TEXT

/init

1: /init analiza el proyecto y crea AGENTS.md en la raiz.

Recomendación:

Commitea AGENTS.md en Git. Es parte del “contrato” del proyecto para que OpenCode entienda estructura, convenciones y límites.

Modos de trabajo: Plan vs Build

OpenCode tiene dos modos:

Plan mode: el agente propone un plan sin tocar archivos.
Build mode: el agente ejecuta cambios (edita/crea archivos).

Se alterna con Tab (verás el indicador en la esquina inferior derecha).

Uso recomendado para servidores:

Plan mode: pedir diagnóstico, hipótesis, comandos read-only, verificación.
Build mode: solo cuando el plan es correcto y el cambio es reversible.

Deshacer y rehacer cambios (/undo, /redo)

Si OpenCode hizo cambios que no quieres:

TEXT

/undo
/redo

1: /undo revierte los cambios del último pedido.
2: /redo reaplica los cambios deshechos.

Compartir sesiones (/share) y política de privacidad

Compartir es una acción explícita. Al usar /share, OpenCode sincroniza el historial a servidores para generar un link público.

TEXT

/share
/unshare

1: /share publica un link de la conversación.
2: /unshare elimina el link y deja la conversacion sin acceso publico.

Para entornos sensibles (empresas / infra / clientes), deshabilita el share por proyecto:

TEXT

{ "$schema": "https://opncd.ai/config.json", "share": "disabled" }

1: share: disabled desactiva el compartir (recomendado en proyectos con informacion sensible).

Ejemplo 1: Inventario rápido del servidor (multi-SO)

BASH

1$ uname -m
x86_64

2$ free -h
               total        used        free      shared  buff/cache   available
Mem:           15Gi       4.2Gi       8.2Gi       412Mi       3.1Gi        10Gi
Swap:         2.0Gi          0B       2.0Gi

3$ df -h /
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        80G   22G   55G  29% /

1: uname -m confirma la arquitectura (útil para binarios y contenedores)
2: free -h muestra uso de RAM en formato legible
3: df -h / revisa espacio del filesystem principal

BASH

1$ system_profiler SPHardwareDataType

Hardware Overview:
  Model Name: MacBook Pro
  Model Identifier: MacBookPro18,3
  Processor Name: Apple M3 Pro
  Number of Cores: 12 core CPU
  Memory: 16 GB

2$ df -h /
Filesystem      Size   Used  Avail Capacity iused      ifree %iused  Mounted on
/dev/disk3s1   460Gi  210Gi  245Gi    47%  1.9M       2.4G    0%    /

1: system_profiler SPHardwareDataType entrega un resumen del hardware
2: df -h / valida uso de disco (útil antes de builds, logs o backups)

POWERSHELL

1PS> systeminfo

Computer Name:          USUARIO-PC
Processor(s):           1 Logical Processor
System Type:            x86-64-based PC
Total Physical Memory:  16384 MB

2PS> Get-PSDrive -PSProvider FileSystem

Name Used (GB) Free (GB) Provider      Root
---- --------- --------- --------      ----
C       55.20     180.10 FileSystem    C:\\

1: systeminfo muestra inventario básico (CPU, tipo de sistema, RAM)
2: Get-PSDrive revisa espacio disponible por unidad

Como usarlo con OpenCode:

Pega la salida y pregunta: “Con estos datos, que riesgos ves (disco, RAM, arquitectura) para desplegar X? Dame una checklist de preflight”.

Ejemplo 2: Diagnóstico de un servicio (Nginx) en Linux

BASH

1$ systemctl status nginx --no-pager
* nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (/lib/systemd/system/nginx.service; enabled)
     Active: active (running) since Sun 2026-02-01 09:12:14 UTC; 2h 10min ago

2$ journalctl -u nginx --since "30 min ago" --no-pager
Feb 01 11:11:03 server nginx[1234]: 2026/02/01 11:11:03 [error] 1234#1234: *918 connect() failed (111: Connection refused) while connecting to upstream

3$ nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

1: systemctl status nginx –no-pager valida estado del servicio sin paginador
2: journalctl -u nginx –since obtiene errores recientes del servicio
3: nginx -t valida sintaxis de configuración antes de recargar

Prompt sugerido para OpenCode (pega 10-30 lineas reales del log):

“Analiza este error de Nginx y propón 3 hipótesis ordenadas por probabilidad. Para cada una, dame un comando de verificación (solo lectura) y el criterio de confirmación”.

Ejemplo 2.1: Checklist de preflight (antes de tocar producción)

Objetivo: pedir a OpenCode una checklist corta, ejecutable y segura.

Prompt sugerido (Plan mode):

TEXT

Estoy por desplegar X en este servidor.

Evidencia: (pego outputs de uname/free/df/systemctl/journalctl).

Necesito una checklist de preflight de 10 items max:
- Solo comandos read-only
- Criterio de OK/FAIL por cada comando
- Riesgo si se ignora

1: Checklist de preflight fuerza a que el resultado sea accionable y verificable (no solo consejos).

Ejemplo 3: Convertir un procedimiento en runbook (plantilla)

Usa esta plantilla para estandarizar correcciones y evitar repetición:

Contexto: que paso, impacto, desde cuando
Evidencia: comandos ejecutados + salidas relevantes
Causa raíz: qué lo provocó (y cómo se confirma)
Fix: pasos exactos (preferir cambios reversibles)
Verificación: cómo confirmar que quedó bien (métricas, healthchecks)
Rollback: como volver atras si algo sale mal

Custom commands (para runbooks repetibles)

OpenCode permite comandos custom por proyecto. Esto es útil para estandarizar runbooks.

Ejemplo: crear .opencode/commands/preflight.md:

MARKDOWN

---
description: Checklist preflight (servidores)
agent: plan
---
Genera una checklist de preflight (max 12 items) para el cambio: $ARGUMENTS.
Reglas:
- solo comandos read-only
- incluye criterio OK/FAIL por item
- incluye rollback / mitigación rápida si detectas riesgo
# <1>

.opencode/commands/ permite ejecutar prompts repetibles como comandos en la TUI.

MCP Servers (Model Context Protocol)

Desde v1.1.x, OpenCode soporta MCP servers - herramientas externas que extienden las capacidades del agente.

¿Qué son los MCP Servers?

Los MCP (Model Context Protocol) servers permiten a OpenCode: - Ejecutar comandos en servidores remotos via SSH - Consultar bases de datos directamente - Integrarse con APIs externas (AWS, Azure, GCP) - Acceder a sistemas de monitoreo (Prometheus, Grafana)

Instalación de MCP servers

BASH

# Listar MCP servers disponibles
1$ opencode mcp list

# Instalar un MCP server (ejemplo: SSH)
2$ opencode mcp install mcp-server-ssh

# Configurar el MCP server
3$ opencode mcp config mcp-server-ssh

1: mcp list muestra los MCP servers disponibles en el registro
2: mcp install descarga e instala un MCP server específico
3: mcp config abre el asistente de configuración del MCP

MCP Server para Sysadmin: SSH Remote

Configuración típica para administración remota:

JSON

{
  "mcpServers": {
    "ssh-remote": {
      "command": "npx",
      "args": ["-y", "mcp-server-ssh"],
      "env": {
        "SSH_HOST": "servidor-produccion.ejemplo.com",
        "SSH_USER": "admin",
        "SSH_KEY_PATH": "~/.ssh/id_rsa"
      }
    }
  }
}

⚠️ ADVERTENCIA CRÍTICA

Seguridad con MCP servers

Lo que podría salir mal: - Exposición de credenciales SSH en configuración - Acceso no autorizado a servidores de producción - Ejecución accidental de comandos destructivos

Cómo prevenirlo: 1. Usa variables de entorno para credenciales (no hardcodificar) 2. Limita permisos del MCP server (solo lectura si es posible) 3. Testea en staging antes de producción 4. Usa agent: plan para revisar comandos antes de ejecutar

Ejemplo práctico: Diagnóstico remoto con MCP

TEXT

# Conectar a servidor remoto via MCP
/connect mcp:ssh-remote

# Ejecutar diagnóstico de disco
@ssh-remote df -h && du -sh /var/log

# Analizar logs de nginx
@ssh-remote tail -n 100 /var/log/nginx/error.log | grep "error"

1: /connect mcp:ssh-remote conecta al servidor configurado via MCP
2: (ssh-remote?) prefijo para ejecutar comandos en el servidor remoto
3: Pipeline de comandos para diagnóstico de logs

Zen Models (OpenCode Zen)

OpenCode Zen es un servicio de suscripción que proporciona acceso a modelos optimizados para coding agents.

Características

Modelos validados: Solo modelos probados y benchmarked por OpenCode
Rendimiento consistente: Sin variaciones de calidad entre proveedores
Costo predecible: Suscripción fija vs API keys variables

Configuración

TEXT

# Conectar a Zen
/connect zen

# Listar modelos disponibles
/models

# Cambiar modelo activo
/model claude-sonnet-4

1: /connect zen autentica con el servicio Zen
2: /models lista modelos disponibles en tu suscripción
3: /model cambia el modelo activo para la sesión

Cuándo usar Zen vs otros proveedores

Escenario	Recomendación
Curso/principiantes	Zen (simplicidad)
Empresa con compliance	Zen (soporte enterprise)
Proyectos personales	API directa (costo variable)
Testing múltiples modelos	Zen (cambio fácil)

Laboratorio práctico (20-30 min)

Objetivo: generar un runbook de “Servidor lento” basado en evidencia.

BASH

1$ uptime
 11:40:12 up 18 days,  3:12,  2 users,  load average: 2.10, 1.95, 1.20

2$ top -b -n 1 | head -n 15
top - 11:40:12 up 18 days,  3:12,  2 users,  load average: 2.10, 1.95, 1.20
Tasks: 231 total,   2 running, 229 sleeping,   0 stopped,   0 zombie
%Cpu(s): 12.0 us,  2.5 sy,  0.0 ni, 84.8 id,  0.6 wa,  0.0 hi,  0.1 si,  0.0 st

3$ ss -s
Total: 842 (kernel 0)
TCP:   125 (estab 48, closed 32, orphaned 0, timewait 32)
UDP:   10

1: uptime muestra uptime y load average (primer indicador de presion)
2: top -b -n 1 toma un snapshot no interactivo (pega solo las primeras lineas)
3: ss -s resume sockets (util para identificar picos de conexiones)

Entrega:

Pega en OpenCode: uptime, las primeras 15 líneas de top y ss -s.
Pide: “Dame un plan de diagnóstico de 10 minutos con comandos read-only, y luego una propuesta de mitigación con rollback”.
Escribe el runbook usando la plantilla del Ejemplo 3.

Mejores prácticas

RECOMENDACIÓN

Usa OpenCode como copiloto, no como piloto automático.

Casos de uso: - Checklists de despliegue y preflight - Interpretación de logs y errores - Generación de scripts con validaciones y modo seguro

Cuando aplicar: - Incidentes repetitivos - Tareas manuales que se hacen más de 2 veces - Cambios con riesgo (mejorar documentación y rollback)

Anexo G: OpenCode - Mini-Curso para Gestión de Servidores

Anexo G: OpenCode - Mini-Curso para Gestión de Servidores

Introducción

Objetivos de aprendizaje

Reglas de seguridad (antes de usar AI)

Flujo recomendado: evidencia -> análisis -> acción

Instalación de OpenCode

OpenCode Desktop (Beta)

Descarga e instalación

Configurar proveedor (LLM)

Inicializar un proyecto (/init)

Modos de trabajo: Plan vs Build

Deshacer y rehacer cambios (/undo, /redo)

Ejemplo 1: Inventario rápido del servidor (multi-SO)

Ejemplo 2: Diagnóstico de un servicio (Nginx) en Linux

Ejemplo 2.1: Checklist de preflight (antes de tocar producción)

Ejemplo 3: Convertir un procedimiento en runbook (plantilla)

Custom commands (para runbooks repetibles)

MCP Servers (Model Context Protocol)

¿Qué son los MCP Servers?

Instalación de MCP servers

MCP Server para Sysadmin: SSH Remote

Ejemplo práctico: Diagnóstico remoto con MCP

Zen Models (OpenCode Zen)

Características

Configuración

Cuándo usar Zen vs otros proveedores

Laboratorio práctico (20-30 min)

Mejores prácticas

Resumen

Referencias

Documentación Oficial OpenCode

Linux y Sysadmin

MCP (Model Context Protocol)

Code Appendix