Servidor

El comando opencode serve ejecuta un servidor HTTP “headless” que expone un endpoint OpenAPI para que los clientes de OpenCode lo usen.

---

Uso

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

Opciones

Flag	Descripción	Por defecto
--port	Puerto de escucha	4096
--hostname	Host de escucha	127.0.0.1
--mdns	Habilitar descubrimiento mDNS	false
--cors	Orígenes adicionales permitidos para CORS	[]

--cors se puede pasar varias veces:

opencode serve --cors http://localhost:5173 --cors https://app.example.com

---

Cómo funciona

Cuando ejecutas opencode, se inician tanto el TUI como un servidor. El TUI actúa como cliente y habla con el servidor. Este servidor expone un endpoint con especificación OpenAPI 3.1, que también se usa para generar el SDK.

Consejo

Usa el servidor de OpenCode cuando quieras interactuar con OpenCode de forma programática.

Esta arquitectura permite tener múltiples clientes y controlar OpenCode desde scripts, apps o integraciones externas.

Puedes ejecutar opencode serve para iniciar un servidor independiente. Si ya tienes el TUI abierto, opencode serve levantará otro servidor adicional.

---

Conectarse a un servidor existente

Al iniciar el TUI, OpenCode elige por defecto un puerto y hostname aleatorios. Alternativamente, puedes fijarlos con los flags --hostname y --port (ver CLI). A partir de ahí, otros clientes pueden conectarse a ese servidor.

El endpoint /tui permite controlar el TUI a través del servidor: por ejemplo, rellenar el prompt o enviarlo. Este mecanismo es el que usan los plugins de IDE.

---

Especificación

El servidor publica una especificación OpenAPI 3.1 accesible en:

http://<hostname>:<port>/doc

Por ejemplo: http://localhost:4096/doc. Puedes usarla para generar clientes, inspeccionar tipos de request/response o visualizarla con Swagger.

---

APIs

El servidor de OpenCode expone las APIs siguientes.

---

Global

Método	Path	Descripción	Respuesta
GET	/global/health	Obtener estado y versión del servidor	{ healthy: true, version: string }
GET	/global/event	Eventos globales (SSE)	Stream de eventos

---

Proyecto

Método	Path	Descripción	Respuesta
GET	/project	Listar todos los proyectos	Project[]
GET	/project/current	Proyecto actual	Project

---

Ruta y VCS

Método	Path	Descripción	Respuesta
GET	/path	Obtener la ruta actual	Path
GET	/vcs	Info de VCS para el proyecto actual	VcsInfo

---

Instancia

Método	Path	Descripción	Respuesta
POST	/instance/dispose	Liberar la instancia actual	boolean

---

Config

Método	Path	Descripción	Respuesta
GET	/config	Obtener información de configuración	Config
PATCH	/config	Actualizar configuración	Config
GET	/config/providers	Listar proveedores y modelos por defecto	{ providers: Provider[], default: { [key: string]: string } }

---

Proveedor

Método	Path	Descripción	Respuesta
GET	/provider	Listar todos los proveedores	{ all: Provider[], default: {...}, connected: string[] }
GET	/provider/auth	Métodos de autenticación por proveedor	{ [providerID: string]: ProviderAuthMethod[] }
POST	/provider/{id}/oauth/authorize	Iniciar OAuth para un proveedor	ProviderAuthAuthorization
POST	/provider/{id}/oauth/callback	Callback OAuth	boolean

---

Sesiones

Método	Path	Descripción	Notas
GET	/session	Listar todas las sesiones	Devuelve Session[]
POST	/session	Crear una sesión nueva	body: { parentID?, title? } → Session
GET	/session/status	Estado de todas las sesiones	{ [sessionID: string]: SessionStatus }
GET	/session/:id	Detalle de una sesión	Session
DELETE	/session/:id	Borrar una sesión y sus datos	boolean
PATCH	/session/:id	Actualizar propiedades de una sesión	body: { title? } → Session
GET	/session/:id/children	Sesiones hijas	Session[]
GET	/session/:id/todo	Lista TODO de una sesión	Todo[]
POST	/session/:id/init	Analizar repo y generar AGENTS.md	body: { messageID, providerID, modelID } → boolean
POST	/session/:id/fork	Bifurcar una sesión en un mensaje	body: { messageID? } → Session
POST	/session/:id/abort	Cancelar una sesión en curso	boolean
POST	/session/:id/share	Compartir una sesión	Session
DELETE	/session/:id/share	Dejar de compartir una sesión	Session
GET	/session/:id/diff	Obtener diff de la sesión	query: messageID? → FileDiff[]
POST	/session/:id/summarize	Resumir la sesión	body: { providerID, modelID } → boolean
POST	/session/:id/revert	Revertir un mensaje	body: { messageID, partID? } → boolean
POST	/session/:id/unrevert	Restaurar mensajes revertidos	boolean
POST	/session/:id/permissions/:permissionID	Responder a una petición de permiso	body: { response, remember? } → boolean

---

Mensajes

Método	Path	Descripción	Notas
GET	/session/:id/message	Listar mensajes de una sesión	query: limit? → { info: Message, parts: Part[]}[]
POST	/session/:id/message	Enviar mensaje y esperar respuesta	body: { messageID?, model?, agent?, noReply?, system?, tools?, parts } → { info, parts }
GET	/session/:id/message/:messageID	Detalle de un mensaje	{ info: Message, parts: Part[]}
POST	/session/:id/prompt_async	Enviar mensaje asincrónico (sin esperar)	body igual que /session/:id/message, respuesta 204 No Content
POST	/session/:id/command	Ejecutar un comando slash	body: { messageID?, agent?, model?, command, arguments } → { info, parts }
POST	/session/:id/shell	Ejecutar comando de shell	body: { agent, model?, command } → { info, parts }

---

Comandos

Método	Path	Descripción	Respuesta
GET	/command	Listar todos los comandos	Command[]

---

Archivos

Método	Path	Descripción	Respuesta
GET	/find?pattern=<pat>	Buscar texto en archivos	Array con matches: path, lines, line_number, absolute_offset, submatches
GET	/find/file?query=<q>	Buscar archivos y directorios por nombre	string[] (rutas)
GET	/find/symbol?query=<q>	Buscar símbolos en el workspace	Symbol[]
GET	/file?path=<path>	Listar archivos y directorios	FileNode[]
GET	/file/content?path=<p>	Leer archivo	FileContent
GET	/file/status	Estado de archivos trackeados	File[]

Parámetros de /find/file

• query (requerido): cadena de búsqueda (fuzzy)
• type (opcional): limitar a "file" o "directory"
• directory (opcional): raíz alternativa para la búsqueda
• limit (opcional): máximo de resultados (1–200)
• dirs (opcional): flag legado ("false" devuelve solo archivos)

---

Tools (Experimental)

Método	Path	Descripción	Respuesta
GET	/experimental/tool/ids	Listar todos los IDs de herramienta	ToolIDs
GET	/experimental/tool?provider=<p>&model=<m>	Listar herramientas con esquemas JSON	ToolList

---

LSP, Formatters y MCP

Método	Path	Descripción	Respuesta
GET	/lsp	Estado de servidores LSP	LSPStatus[]
GET	/formatter	Estado de formatters	FormatterStatus[]
GET	/mcp	Estado de servidores MCP	{ [name: string]: MCPStatus }
POST	/mcp	Añadir servidor MCP dinámicamente	body: { name, config } → objeto de estado MCP

---

Agents

Método	Path	Descripción	Respuesta
GET	/agent	Listar todos los agentes	Agent[]

---

Logging

Método	Path	Descripción	Respuesta
POST	/log	Escribir entrada de log ({ service, level, message, extra? })	boolean

---

TUI

Método	Path	Descripción	Respuesta
POST	/tui/append-prompt	Añadir texto al prompt	boolean
POST	/tui/open-help	Abrir el panel de ayuda	boolean
POST	/tui/open-sessions	Abrir selector de sesiones	boolean
POST	/tui/open-themes	Abrir selector de temas	boolean
POST	/tui/open-models	Abrir selector de modelos	boolean
POST	/tui/submit-prompt	Enviar el prompt actual	boolean
POST	/tui/clear-prompt	Limpiar el prompt	boolean
POST	/tui/execute-command	Ejecutar un comando ({ command })	boolean
POST	/tui/show-toast	Mostrar toast ({ title?, message, variant })	boolean
GET	/tui/control/next	Esperar la siguiente petición de control	Objeto de control
POST	/tui/control/response	Responder a una petición de control ({ body })	boolean

---

Auth

Método	Path	Descripción	Respuesta
PUT	/auth/:id	Configurar credenciales para un proveedor (body según esquema)	boolean

---

Eventos

Método	Path	Descripción	Respuesta
GET	/event	Stream SSE. El primer evento es server.connected, luego eventos del bus	Stream de eventos SSE

---

Docs

Método	Path	Descripción	Respuesta
GET	/doc	Especificación OpenAPI 3.1	Página HTML con el spec