Servidor

Interactua con el servidor de opencode a traves de HTTP.

El comando opencode serve ejecuta un servidor HTTP headless que expone un endpoint OpenAPI que un cliente de opencode puede usar.

Uso

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

Opciones

Flag	Descripcion	Predeterminado
`--port`	Puerto de escucha	`4096`
`--hostname`	Hostname de escucha	`127.0.0.1`
`--mdns`	Habilitar descubrimiento mDNS	`false`
`--mdns-domain`	Nombre de dominio personalizado para servicio mDNS	`opencode.local`
`--cors`	Origenes de navegador adicionales permitidos	`[]`

--cors puede pasarse multiples veces:

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

Autenticacion

Establece OPENCODE_SERVER_PASSWORD para proteger el servidor con autenticacion HTTP basica. El nombre de usuario predeterminado es opencode, o establece OPENCODE_SERVER_USERNAME para cambiarlo. Esto aplica tanto a opencode serve como a opencode web.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

Como funciona

Cuando ejecutas opencode, inicia una TUI y un servidor. La TUI es el cliente que se comunica con el servidor. El servidor expone un endpoint de especificacion OpenAPI 3.1. Este endpoint tambien se usa para generar un SDK.

Consejo: Usa el servidor de opencode para interactuar con opencode programaticamente.

Esta arquitectura permite que opencode soporte multiples clientes y te permite interactuar con opencode programaticamente.

Puedes ejecutar opencode serve para iniciar un servidor independiente. Si ya tienes la TUI de opencode ejecutandose, opencode serve iniciara un nuevo servidor.

Conectar a un servidor existente

Cuando inicias la TUI, asigna aleatoriamente un puerto y hostname. En su lugar, puedes pasar los flags --hostname y --port. Luego usa esto para conectarte a su servidor.

El endpoint /tui puede usarse para controlar la TUI a traves del servidor. Por ejemplo, puedes prellenar o ejecutar un prompt. Esta configuracion es usada por los plugins de IDE de OpenCode.

Especificacion

El servidor publica una especificacion OpenAPI 3.1 que puede verse en:

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

Por ejemplo, http://localhost:4096/doc. Usa la especificacion para generar clientes o inspeccionar tipos de solicitud y respuesta. O visualizala en un explorador Swagger.

APIs

El servidor de opencode expone las siguientes APIs.

Global

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/global/health`	Obtener salud del servidor y version	`{ healthy: true, version: string }`
`GET`	`/global/event`	Obtener eventos globales (stream SSE)	Stream de eventos

Proyecto

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/project`	Listar todos los proyectos	`Project[]`
`GET`	`/project/current`	Obtener el proyecto actual	`Project`

Ruta y VCS

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/path`	Obtener la ruta actual	`Path`
`GET`	`/vcs`	Obtener info VCS del proyecto actual	`VcsInfo`

Instancia

Metodo	Ruta	Descripcion	Respuesta
`POST`	`/instance/dispose`	Eliminar la instancia actual	`boolean`

Configuracion

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/config`	Obtener info de configuracion	`Config`
`PATCH`	`/config`	Actualizar configuracion	`Config`
`GET`	`/config/providers`	Listar proveedores y modelos predeterminados	`{ providers: Provider[], default: { [key: string]: string } }`

Proveedor

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/provider`	Listar todos los proveedores	`{ all: Provider[], default: {...}, connected: string[] }`
`GET`	`/provider/auth`	Obtener metodos de autenticacion del proveedor	`{ [providerID: string]: ProviderAuthMethod[] }`
`POST`	`/provider/{id}/oauth/authorize`	Autorizar proveedor usando OAuth	`ProviderAuthAuthorization`
`POST`	`/provider/{id}/oauth/callback`	Manejar callback OAuth del proveedor	`boolean`

Sesiones

Metodo	Ruta	Descripcion	Notas
`GET`	`/session`	Listar todas las sesiones	Devuelve `Session[]`
`POST`	`/session`	Crear nueva sesion	body: `{ parentID?, title? }`, devuelve `Session`
`GET`	`/session/status`	Obtener estado de todas las sesiones	Devuelve `{ [sessionID: string]: SessionStatus }`
`GET`	`/session/:id`	Obtener detalles de sesion	Devuelve `Session`
`DELETE`	`/session/:id`	Eliminar sesion y todos sus datos	Devuelve `boolean`
`PATCH`	`/session/:id`	Actualizar propiedades de sesion	body: `{ title? }`, devuelve `Session`
`GET`	`/session/:id/children`	Obtener sesiones hijas	Devuelve `Session[]`
`GET`	`/session/:id/todo`	Obtener lista de tareas de la sesion	Devuelve `Todo[]`
`POST`	`/session/:id/init`	Analizar app y crear `AGENTS.md`	body: `{ messageID, providerID, modelID }`, devuelve `boolean`
`POST`	`/session/:id/fork`	Bifurcar sesion existente en un mensaje	body: `{ messageID? }`, devuelve `Session`
`POST`	`/session/:id/abort`	Abortar sesion en ejecucion	Devuelve `boolean`
`POST`	`/session/:id/share`	Compartir sesion	Devuelve `Session`
`DELETE`	`/session/:id/share`	Dejar de compartir sesion	Devuelve `Session`
`GET`	`/session/:id/diff`	Obtener diff de esta sesion	query: `messageID?`, devuelve `FileDiff[]`
`POST`	`/session/:id/summarize`	Resumir la sesion	body: `{ providerID, modelID }`, devuelve `boolean`
`POST`	`/session/:id/revert`	Revertir un mensaje	body: `{ messageID, partID? }`, devuelve `boolean`
`POST`	`/session/:id/unrevert`	Restaurar todos los mensajes revertidos	Devuelve `boolean`
`POST`	`/session/:id/permissions/:permissionID`	Responder a solicitud de permiso	body: `{ response, remember? }`, devuelve `boolean`

Mensajes

Metodo	Ruta	Descripcion	Notas
`GET`	`/session/:id/message`	Listar mensajes en sesion	query: `limit?`, devuelve `{ info: Message, parts: Part[] }[]`
`POST`	`/session/:id/message`	Enviar mensaje y esperar respuesta	body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, devuelve `{ info: Message, parts: Part[] }`
`GET`	`/session/:id/message/:messageID`	Obtener detalles del mensaje	Devuelve `{ info: Message, parts: Part[] }`
`POST`	`/session/:id/prompt_async`	Enviar mensaje asincronamente (sin esperar)	body: igual que `/session/:id/message`, devuelve `204 No Content`
`POST`	`/session/:id/command`	Ejecutar comando slash	body: `{ messageID?, agent?, model?, command, arguments }`, devuelve `{ info: Message, parts: Part[] }`
`POST`	`/session/:id/shell`	Ejecutar comando shell	body: `{ agent, model?, command }`, devuelve `{ info: Message, parts: Part[] }`

Comandos

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/command`	Listar todos los comandos	`Command[]`

Archivos

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/find?pattern=<pat>`	Buscar texto en archivos	Array de objetos de coincidencia con `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 simbolos del workspace	`Symbol[]`
`GET`	`/file?path=<path>`	Listar archivos y directorios	`FileNode[]`
`GET`	`/file/content?path=<p>`	Leer un archivo	`FileContent`
`GET`	`/file/status`	Obtener estado de archivos rastreados	`File[]`

Parametros de consulta de `/find/file`

query (requerido) — cadena de busqueda (coincidencia difusa)
type (opcional) — limitar resultados a "file" o "directory"
directory (opcional) — sobrescribir raiz del proyecto para busqueda
limit (opcional) — max resultados (1–200)
dirs (opcional) — flag legacy ("false" devuelve solo archivos)

Herramientas (Experimental)

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/experimental/tool/ids`	Listar todos los IDs de herramientas	`ToolIDs`
`GET`	`/experimental/tool?provider=<p>&model=<m>`	Listar herramientas con esquemas JSON para modelo	`ToolList`

LSP, Formateadores y MCP

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/lsp`	Obtener estado del servidor LSP	`LSPStatus[]`
`GET`	`/formatter`	Obtener estado del formateador	`FormatterStatus[]`
`GET`	`/mcp`	Obtener estado del servidor MCP	`{ [name: string]: MCPStatus }`
`POST`	`/mcp`	Agregar servidor MCP dinamicamente	body: `{ name, config }`, devuelve objeto de estado MCP

Agentes

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/agent`	Listar todos los agentes disponibles	`Agent[]`

Registro

Metodo	Ruta	Descripcion	Respuesta
`POST`	`/log`	Escribir entrada de log. Body: `{ service, level, message, extra? }`	`boolean`

TUI

Metodo	Ruta	Descripcion	Respuesta
`POST`	`/tui/append-prompt`	Agregar texto al prompt	`boolean`
`POST`	`/tui/open-help`	Abrir dialogo 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 comando (`{ command }`)	`boolean`
`POST`	`/tui/show-toast`	Mostrar toast (`{ title?, message, variant }`)	`boolean`
`GET`	`/tui/control/next`	Esperar siguiente solicitud de control	Objeto de solicitud de control
`POST`	`/tui/control/response`	Responder a solicitud de control (`{ body }`)	`boolean`

Auth

Metodo	Ruta	Descripcion	Respuesta
`PUT`	`/auth/:id`	Establecer credenciales de autenticacion. Body debe coincidir con esquema del proveedor	`boolean`

Eventos

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/event`	Stream de eventos enviados por servidor. Primer evento es `server.connected`, luego eventos del bus	Stream de eventos enviados por servidor

Docs

Metodo	Ruta	Descripcion	Respuesta
`GET`	`/doc`	Especificacion OpenAPI 3.1	Pagina HTML con especificacion OpenAPI

SDK Plugins