Servidor

Interaja com o servidor opencode via HTTP.

O comando opencode serve executa um servidor HTTP headless que expoe um endpoint OpenAPI que um cliente opencode pode usar.

Uso

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

Opcoes

Flag	Descricao	Padrao
`--port`	Porta para escutar	`4096`
`--hostname`	Hostname para escutar	`127.0.0.1`
`--mdns`	Habilitar descoberta mDNS	`false`
`--mdns-domain`	Nome de dominio personalizado para servico mDNS	`opencode.local`
`--cors`	Origens de navegador adicionais permitidas	`[]`

--cors pode ser passado multiplas vezes:

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

Autenticacao

Defina OPENCODE_SERVER_PASSWORD para proteger o servidor com autenticacao HTTP basica. O nome de usuario padrao e opencode, ou defina OPENCODE_SERVER_USERNAME para altera-lo. Isso se aplica tanto a opencode serve quanto a opencode web.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

Como funciona

Quando voce executa opencode, ele inicia uma TUI e um servidor. A TUI e o cliente que se comunica com o servidor. O servidor expoe um endpoint de especificacao OpenAPI 3.1. Este endpoint tambem e usado para gerar um SDK.

Dica: Use o servidor opencode para interagir com opencode programaticamente.

Esta arquitetura permite que opencode suporte multiplos clientes e permite que voce interaja com opencode programaticamente.

Voce pode executar opencode serve para iniciar um servidor independente. Se voce ja tem a TUI do opencode em execucao, opencode serve iniciara um novo servidor.

Conectar a um servidor existente

Quando voce inicia a TUI, ela atribui aleatoriamente uma porta e hostname. Voce pode passar os flags --hostname e --port. Entao use isso para conectar ao servidor.

O endpoint /tui pode ser usado para controlar a TUI atraves do servidor. Por exemplo, voce pode preencher ou executar um prompt. Esta configuracao e usada pelos plugins de IDE do OpenCode.

Especificacao

O servidor publica uma especificacao OpenAPI 3.1 que pode ser visualizada em:

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

Por exemplo, http://localhost:4096/doc. Use a especificacao para gerar clientes ou inspecionar tipos de requisicao e resposta. Ou visualize em um explorador Swagger.

APIs

O servidor opencode expoe as seguintes APIs.

Global

Metodo	Caminho	Descricao	Resposta
`GET`	`/global/health`	Obter saude do servidor e versao	`{ healthy: true, version: string }`
`GET`	`/global/event`	Obter eventos globais (stream SSE)	Stream de eventos

Projeto

Metodo	Caminho	Descricao	Resposta
`GET`	`/project`	Listar todos os projetos	`Project[]`
`GET`	`/project/current`	Obter o projeto atual	`Project`

Caminho e VCS

Metodo	Caminho	Descricao	Resposta
`GET`	`/path`	Obter o caminho atual	`Path`
`GET`	`/vcs`	Obter info VCS do projeto atual	`VcsInfo`

Instancia

Metodo	Caminho	Descricao	Resposta
`POST`	`/instance/dispose`	Descartar a instancia atual	`boolean`

Configuracao

Metodo	Caminho	Descricao	Resposta
`GET`	`/config`	Obter info de configuracao	`Config`
`PATCH`	`/config`	Atualizar configuracao	`Config`
`GET`	`/config/providers`	Listar provedores e modelos padrao	`{ providers: Provider[], default: { [key: string]: string } }`

Provedor

Metodo	Caminho	Descricao	Resposta
`GET`	`/provider`	Listar todos os provedores	`{ all: Provider[], default: {...}, connected: string[] }`
`GET`	`/provider/auth`	Obter metodos de autenticacao do provedor	`{ [providerID: string]: ProviderAuthMethod[] }`
`POST`	`/provider/{id}/oauth/authorize`	Autorizar provedor usando OAuth	`ProviderAuthAuthorization`
`POST`	`/provider/{id}/oauth/callback`	Tratar callback OAuth do provedor	`boolean`

Sessoes

Metodo	Caminho	Descricao	Notas
`GET`	`/session`	Listar todas as sessoes	Retorna `Session[]`
`POST`	`/session`	Criar nova sessao	body: `{ parentID?, title? }`, retorna `Session`
`GET`	`/session/status`	Obter status de todas as sessoes	Retorna `{ [sessionID: string]: SessionStatus }`
`GET`	`/session/:id`	Obter detalhes da sessao	Retorna `Session`
`DELETE`	`/session/:id`	Excluir sessao e todos os dados	Retorna `boolean`
`PATCH`	`/session/:id`	Atualizar propriedades da sessao	body: `{ title? }`, retorna `Session`
`GET`	`/session/:id/children`	Obter sessoes filhas	Retorna `Session[]`
`GET`	`/session/:id/todo`	Obter lista de tarefas da sessao	Retorna `Todo[]`
`POST`	`/session/:id/init`	Analisar app e criar `AGENTS.md`	body: `{ messageID, providerID, modelID }`, retorna `boolean`
`POST`	`/session/:id/fork`	Bifurcar sessao existente em uma mensagem	body: `{ messageID? }`, retorna `Session`
`POST`	`/session/:id/abort`	Abortar sessao em execucao	Retorna `boolean`
`POST`	`/session/:id/share`	Compartilhar sessao	Retorna `Session`
`DELETE`	`/session/:id/share`	Parar de compartilhar sessao	Retorna `Session`
`GET`	`/session/:id/diff`	Obter diff desta sessao	query: `messageID?`, retorna `FileDiff[]`
`POST`	`/session/:id/summarize`	Resumir a sessao	body: `{ providerID, modelID }`, retorna `boolean`
`POST`	`/session/:id/revert`	Reverter uma mensagem	body: `{ messageID, partID? }`, retorna `boolean`
`POST`	`/session/:id/unrevert`	Restaurar todas as mensagens revertidas	Retorna `boolean`
`POST`	`/session/:id/permissions/:permissionID`	Responder a solicitacao de permissao	body: `{ response, remember? }`, retorna `boolean`

Mensagens

Metodo	Caminho	Descricao	Notas
`GET`	`/session/:id/message`	Listar mensagens na sessao	query: `limit?`, retorna `{ info: Message, parts: Part[] }[]`
`POST`	`/session/:id/message`	Enviar mensagem e aguardar resposta	body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, retorna `{ info: Message, parts: Part[] }`
`GET`	`/session/:id/message/:messageID`	Obter detalhes da mensagem	Retorna `{ info: Message, parts: Part[] }`
`POST`	`/session/:id/prompt_async`	Enviar mensagem assincronamente (sem esperar)	body: igual a `/session/:id/message`, retorna `204 No Content`
`POST`	`/session/:id/command`	Executar comando slash	body: `{ messageID?, agent?, model?, command, arguments }`, retorna `{ info: Message, parts: Part[] }`
`POST`	`/session/:id/shell`	Executar comando shell	body: `{ agent, model?, command }`, retorna `{ info: Message, parts: Part[] }`

Comandos

Metodo	Caminho	Descricao	Resposta
`GET`	`/command`	Listar todos os comandos	`Command[]`

Arquivos

Metodo	Caminho	Descricao	Resposta
`GET`	`/find?pattern=<pat>`	Buscar texto em arquivos	Array de objetos de correspondencia com `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`GET`	`/find/file?query=<q>`	Encontrar arquivos e diretorios por nome	`string[]` (caminhos)
`GET`	`/find/symbol?query=<q>`	Encontrar simbolos do workspace	`Symbol[]`
`GET`	`/file?path=<path>`	Listar arquivos e diretorios	`FileNode[]`
`GET`	`/file/content?path=<p>`	Ler um arquivo	`FileContent`
`GET`	`/file/status`	Obter status de arquivos rastreados	`File[]`

Parametros de consulta de `/find/file`

query (obrigatorio) — string de busca (correspondencia difusa)
type (opcional) — limitar resultados a "file" ou "directory"
directory (opcional) — sobrescrever raiz do projeto para busca
limit (opcional) — max resultados (1–200)
dirs (opcional) — flag legado ("false" retorna apenas arquivos)

Ferramentas (Experimental)

Metodo	Caminho	Descricao	Resposta
`GET`	`/experimental/tool/ids`	Listar todos os IDs de ferramentas	`ToolIDs`
`GET`	`/experimental/tool?provider=<p>&model=<m>`	Listar ferramentas com schemas JSON para modelo	`ToolList`

LSP, Formatadores e MCP

Metodo	Caminho	Descricao	Resposta
`GET`	`/lsp`	Obter status do servidor LSP	`LSPStatus[]`
`GET`	`/formatter`	Obter status do formatador	`FormatterStatus[]`
`GET`	`/mcp`	Obter status do servidor MCP	`{ [name: string]: MCPStatus }`
`POST`	`/mcp`	Adicionar servidor MCP dinamicamente	body: `{ name, config }`, retorna objeto de status MCP

Agentes

Metodo	Caminho	Descricao	Resposta
`GET`	`/agent`	Listar todos os agentes disponiveis	`Agent[]`

Logging

Metodo	Caminho	Descricao	Resposta
`POST`	`/log`	Escrever entrada de log. Body: `{ service, level, message, extra? }`	`boolean`

TUI

Metodo	Caminho	Descricao	Resposta
`POST`	`/tui/append-prompt`	Adicionar texto ao prompt	`boolean`
`POST`	`/tui/open-help`	Abrir dialogo de ajuda	`boolean`
`POST`	`/tui/open-sessions`	Abrir seletor de sessoes	`boolean`
`POST`	`/tui/open-themes`	Abrir seletor de temas	`boolean`
`POST`	`/tui/open-models`	Abrir seletor de modelos	`boolean`
`POST`	`/tui/submit-prompt`	Enviar o prompt atual	`boolean`
`POST`	`/tui/clear-prompt`	Limpar o prompt	`boolean`
`POST`	`/tui/execute-command`	Executar comando (`{ command }`)	`boolean`
`POST`	`/tui/show-toast`	Mostrar toast (`{ title?, message, variant }`)	`boolean`
`GET`	`/tui/control/next`	Aguardar proxima solicitacao de controle	Objeto de solicitacao de controle
`POST`	`/tui/control/response`	Responder a solicitacao de controle (`{ body }`)	`boolean`

Auth

Metodo	Caminho	Descricao	Resposta
`PUT`	`/auth/:id`	Definir credenciais de autenticacao. Body deve corresponder ao schema do provedor	`boolean`

Eventos

Metodo	Caminho	Descricao	Resposta
`GET`	`/event`	Stream de eventos enviados pelo servidor. Primeiro evento e `server.connected`, depois eventos do bus	Stream de eventos enviados pelo servidor

Docs

Metodo	Caminho	Descricao	Resposta
`GET`	`/doc`	Especificacao OpenAPI 3.1	Pagina HTML com especificacao OpenAPI

SDK Plugins