Capitulo 19: SDK y Server Mode

< Volver al Indice del Tutorial

OpenCode no esta limitado a la TUI. Puedes ejecutarlo como servidor HTTP, accederlo desde el navegador, conectar multiples terminales al mismo proceso y usarlo programaticamente con el SDK. Este capitulo cubre todos los modos de ejecucion avanzados.

opencode serve (Servidor Headless)

El comando serve arranca OpenCode como un servidor HTTP sin interfaz grafica. Expone una API REST que permite interactuar programaticamente con el agente.

Uso Basico

opencode serve --port 4096 --hostname 0.0.0.0

Flag	Descripcion	Default
--port	Puerto del servidor HTTP	4096
--hostname	Direccion de escucha	127.0.0.1

Casos de Uso

• Integraciones custom: conectar OpenCode a Slack, Discord u otras plataformas
• Bots automatizados: agente AI que responde a eventos externos
• Aplicaciones web: construir interfaces personalizadas sobre OpenCode
• Pipelines de CI: ejecutar el agente como servicio en un servidor

Autenticacion

Protege el servidor con basic auth usando una variable de entorno:

export OPENCODE_SERVER_PASSWORD="tu-password-seguro"
opencode serve --port 4096

Con el password configurado, todas las peticiones a la API requieren autenticacion HTTP basic. El usuario es opencode y el password es el valor de la variable.

CORS

Configura CORS en la seccion server de la configuracion para permitir peticiones desde dominios especificos. Esto es necesario si tu aplicacion web esta en un dominio diferente al servidor de OpenCode.

mDNS (Descubrimiento Local)

OpenCode soporta mDNS para descubrimiento automatico en red local. Cuando arrancas el servidor, otros dispositivos en la misma red pueden descubrirlo sin conocer la IP exacta.

opencode web

El comando web es similar a serve pero ademas abre una interfaz web en el navegador:

opencode web

Esto arranca el servidor HTTP y abre automaticamente la interfaz web. La interfaz es accesible desde cualquier dispositivo en la red que pueda alcanzar el servidor.

Acceso Remoto

Si arrancas con --hostname 0.0.0.0, puedes acceder desde:

• Otro computador en la misma red
• Tablet o telefono via navegador
• Cualquier dispositivo con un navegador web moderno

Esto es ideal para trabajar desde un iPad o tablet cuando tu servidor de desarrollo esta en otro equipo.

opencode attach

El comando attach permite conectar una TUI local a un servidor remoto de OpenCode:

opencode attach --port 4096

Multiples Clientes

Varias instancias de TUI pueden conectarse al mismo servidor simultaneamente:

# Terminal 1: arranca el servidor
opencode serve --port 4096

# Terminal 2: conecta una TUI
opencode attach --port 4096

# Terminal 3: conecta otra TUI
opencode attach --port 4096

Todos los clientes comparten la misma sesion. Lo que un cliente envia, los demas lo ven en tiempo real. Esto permite pair programming con AI: dos desarrolladores interactuan con el mismo agente desde terminales separadas.

Conexion Remota

Puedes hacer attach a un servidor en otra maquina:

opencode attach --hostname 192.168.1.100 --port 4096

Sessions

OpenCode persiste las sesiones en una base de datos SQLite desde la version v1.2.0. Puedes exportar, importar y gestionar sesiones.

Export

Exporta una sesion completa como JSON:

opencode session export <session-id>

El JSON incluye todos los mensajes, herramientas invocadas y resultados. Util para auditorias, debugging o compartir conversaciones.

Import

Importa una sesion previamente exportada:

opencode session import <archivo.json>

Persistencia

Las sesiones se almacenan en SQLite, lo que ofrece:

• Busqueda rapida entre sesiones anteriores
• Durabilidad: las sesiones sobreviven a reinicios
• Portabilidad: puedes copiar la base de datos entre maquinas

SDK

OpenCode expone un SDK para integracion programatica. Esto permite construir aplicaciones que usen OpenCode como motor AI sin depender de la TUI ni de la API REST.

Capacidades del SDK

• Crear y gestionar sesiones programaticamente
• Enviar mensajes y recibir respuestas como datos estructurados
• Acceder al historial de conversaciones
• Configurar agentes y herramientas via codigo
• Suscribirse a eventos en tiempo real (streaming)

Cuando Usar Cada Modo

Modo	Ideal Para	Comando
TUI	Desarrollo interactivo diario	opencode
Web	Acceso desde navegador/dispositivos	opencode web
Serve	APIs, bots, integraciones	opencode serve
Attach	Conectar TUI a servidor remoto	opencode attach
ACP	Integracion con IDEs	opencode acp
SDK	Aplicaciones programaticas	Importar libreria
Run	Scripts y pipelines (no interactivo)	opencode run "prompt"

Cada modo resuelve un caso de uso diferente. Puedes combinarlos: por ejemplo, serve como backend y attach + web como clientes simultaneos.

---

Siguiente: Capitulo 20: Tips de Productividad —>