Servidor

Interaja com o servidor do opencode via HTTP.

O comando opencode serve roda um servidor HTTP headless que expõe um endpoint OpenAPI que um cliente do opencode pode usar.

Uso

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

Opções

Flag	Descrição	Padrão
`--port`	Porta na qual escutar	`4096`
`--hostname`	Hostname no qual escutar	`127.0.0.1`
`--mdns`	Ativar descoberta por mDNS	`false`
`--mdns-domain`	Nome de domínio personalizado para o serviço mDNS	`opencode.local`
`--cors`	Origens de navegador adicionais a permitir	`[]`

--cors pode ser passado várias vezes:

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

Autenticação

Defina OPENCODE_SERVER_PASSWORD para proteger o servidor com autenticação HTTP básica. O nome de usuário padrão é opencode, ou defina OPENCODE_SERVER_USERNAME para sobrescrevê-lo. Isso se aplica tanto ao opencode serve quanto ao opencode web.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

Como funciona

Quando você roda o opencode, ele inicia uma TUI e um servidor, em que a TUI é o cliente que se comunica com o servidor. O servidor expõe um endpoint de spec OpenAPI 3.1. Esse endpoint também é usado para gerar um SDK.

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

Essa arquitetura permite que o opencode suporte vários clientes e permite que você interaja com o opencode programaticamente.

Você pode rodar opencode serve para iniciar um servidor independente. Se você tiver a TUI do opencode em execução, opencode serve iniciará um novo servidor.

Conectar a um servidor existente

Quando você inicia a TUI, ela atribui uma porta e um hostname aleatoriamente. Em vez disso, você pode passar as flags --hostname e --port. Depois use isso para conectar ao servidor dela.

O endpoint /tui pode ser usado para controlar a TUI pelo servidor. Por exemplo, você pode pré-preencher ou executar um prompt. Essa configuração é usada pelos plugins de IDE do OpenCode.

Spec

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

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

Por exemplo, http://localhost:4096/doc. Use a spec para gerar clientes ou inspecionar os tipos de requisição e resposta. Ou visualize-a em um explorador Swagger.

APIs

O servidor do opencode expõe as seguintes APIs.

Global

Método	Caminho	Descrição	Resposta
`GET`	`/global/health`	Obter a saúde e a versão do servidor	`{ healthy: true, version: string }`
`GET`	`/global/event`	Obter eventos globais (stream SSE)	Stream de eventos

Project

Método	Caminho	Descrição	Resposta
`GET`	`/project`	Listar todos os projetos	`Project[]` (opens in a new tab)
`GET`	`/project/current`	Obter o projeto atual	`Project` (opens in a new tab)

Path e VCS

Método	Caminho	Descrição	Resposta
`GET`	`/path`	Obter o caminho atual	`Path` (opens in a new tab)
`GET`	`/vcs`	Obter info de VCS do projeto atual	`VcsInfo` (opens in a new tab)

Instance

Método	Caminho	Descrição	Resposta
`POST`	`/instance/dispose`	Descartar a instância atual	`boolean`

Config

Método	Caminho	Descrição	Resposta
`GET`	`/config`	Obter informações de config	`Config` (opens in a new tab)
`PATCH`	`/config`	Atualizar a config	`Config` (opens in a new tab)
`GET`	`/config/providers`	Listar provedores e modelos padrão	`{ providers:` Provider[] (opens in a new tab)`, default: { [key: string]: string } }`

Provider

Método	Caminho	Descrição	Resposta
`GET`	`/provider`	Listar todos os provedores	`{ all:` Provider[] (opens in a new tab)`, default: {...}, connected: string[] }`
`GET`	`/provider/auth`	Obter os métodos de autenticação do provedor	`{ [providerID: string]:` ProviderAuthMethod[] (opens in a new tab) `}`
`POST`	`/provider/{id}/oauth/authorize`	Autorizar um provedor usando OAuth	`ProviderAuthAuthorization` (opens in a new tab)
`POST`	`/provider/{id}/oauth/callback`	Tratar o callback OAuth de um provedor	`boolean`

Sessões

Método	Caminho	Descrição	Notas
`GET`	`/session`	Listar todas as sessões	Retorna `Session[]` (opens in a new tab)
`POST`	`/session`	Criar uma nova sessão	body: `{ parentID?, title? }`, retorna `Session` (opens in a new tab)
`GET`	`/session/status`	Obter o status de todas as sessões	Retorna `{ [sessionID: string]:` SessionStatus (opens in a new tab) `}`
`GET`	`/session/:id`	Obter os detalhes da sessão	Retorna `Session` (opens in a new tab)
`DELETE`	`/session/:id`	Excluir uma sessão e todos os seus dados	Retorna `boolean`
`PATCH`	`/session/:id`	Atualizar as propriedades da sessão	body: `{ title? }`, retorna `Session` (opens in a new tab)
`GET`	`/session/:id/children`	Obter as sessões filhas de uma sessão	Retorna `Session[]` (opens in a new tab)
`GET`	`/session/:id/todo`	Obter a lista de tarefas de uma sessão	Retorna `Todo[]` (opens in a new tab)
`POST`	`/session/:id/init`	Analisar o app e criar o `AGENTS.md`	body: `{ messageID, providerID, modelID }`, retorna `boolean`
`POST`	`/session/:id/fork`	Bifurcar uma sessão existente em uma mensagem	body: `{ messageID? }`, retorna `Session` (opens in a new tab)
`POST`	`/session/:id/abort`	Abortar uma sessão em execução	Retorna `boolean`
`POST`	`/session/:id/share`	Compartilhar uma sessão	Retorna `Session` (opens in a new tab)
`DELETE`	`/session/:id/share`	Deixar de compartilhar uma sessão	Retorna `Session` (opens in a new tab)
`GET`	`/session/:id/diff`	Obter o diff desta sessão	query: `messageID?`, retorna `FileDiff[]` (opens in a new tab)
`POST`	`/session/:id/summarize`	Resumir a sessão	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 uma solicitação de permissão	body: `{ response, remember? }`, retorna `boolean`

Mensagens

Método	Caminho	Descrição	Notas
`GET`	`/session/:id/message`	Listar as mensagens de uma sessão	query: `limit?`, retorna `{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}[]`
`POST`	`/session/:id/message`	Enviar uma mensagem e aguardar a resposta	body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, retorna `{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}`
`GET`	`/session/:id/message/:messageID`	Obter os detalhes da mensagem	Retorna `{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}`
`POST`	`/session/:id/prompt_async`	Enviar uma mensagem de forma assíncrona (sem aguardar)	body: igual a `/session/:id/message`, retorna `204 No Content`
`POST`	`/session/:id/command`	Executar um comando de barra	body: `{ messageID?, agent?, model?, command, arguments }`, retorna `{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}`
`POST`	`/session/:id/shell`	Executar um comando de shell	body: `{ agent, model?, command }`, retorna `{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}`

Comandos

Método	Caminho	Descrição	Resposta
`GET`	`/command`	Listar todos os comandos	`Command[]` (opens in a new tab)

Arquivos

Método	Caminho	Descrição	Resposta
`GET`	`/find?pattern=<pat>`	Buscar texto em arquivos	Array de objetos de correspondência com `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`GET`	`/find/file?query=<q>`	Encontrar arquivos e diretórios por nome	`string[]` (caminhos)
`GET`	`/find/symbol?query=<q>`	Encontrar símbolos do workspace	`Symbol[]` (opens in a new tab)
`GET`	`/file?path=<path>`	Listar arquivos e diretórios	`FileNode[]` (opens in a new tab)
`GET`	`/file/content?path=<p>`	Ler um arquivo	`FileContent` (opens in a new tab)
`GET`	`/file/status`	Obter o status dos arquivos rastreados	`File[]` (opens in a new tab)

Parâmetros de query de `/find/file`

query (obrigatório) — string de busca (correspondência difusa)
type (opcional) — limitar os resultados a "file" ou "directory"
directory (opcional) — sobrescrever a raiz do projeto para a busca
limit (opcional) — máximo de resultados (1-200)
dirs (opcional) — flag legada ( "false" retorna apenas arquivos)

Ferramentas (Experimental)

Método	Caminho	Descrição	Resposta
`GET`	`/experimental/tool/ids`	Listar todos os IDs de ferramentas	`ToolIDs` (opens in a new tab)
`GET`	`/experimental/tool?provider=<p>&model=<m>`	Listar ferramentas com schemas JSON para um modelo	`ToolList` (opens in a new tab)

LSP, Formatadores e MCP

Método	Caminho	Descrição	Resposta
`GET`	`/lsp`	Obter o status do servidor LSP	`LSPStatus[]` (opens in a new tab)
`GET`	`/formatter`	Obter o status do formatador	`FormatterStatus[]` (opens in a new tab)
`GET`	`/mcp`	Obter o status do servidor MCP	`{ [name: string]:` MCPStatus (opens in a new tab) `}`
`POST`	`/mcp`	Adicionar um servidor MCP dinamicamente	body: `{ name, config }`, retorna o objeto de status do MCP

Agentes

Método	Caminho	Descrição	Resposta
`GET`	`/agent`	Listar todos os agentes disponíveis	`Agent[]` (opens in a new tab)

Logging

Método	Caminho	Descrição	Resposta
`POST`	`/log`	Escrever uma entrada de log. Body: `{ service, level, message, extra? }`	`boolean`

TUI

Método	Caminho	Descrição	Resposta
`POST`	`/tui/append-prompt`	Anexar texto ao prompt	`boolean`
`POST`	`/tui/open-help`	Abrir o diálogo de ajuda	`boolean`
`POST`	`/tui/open-sessions`	Abrir o seletor de sessões	`boolean`
`POST`	`/tui/open-themes`	Abrir o seletor de temas	`boolean`
`POST`	`/tui/open-models`	Abrir o 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 um comando (`{ command }`)	`boolean`
`POST`	`/tui/show-toast`	Mostrar um toast (`{ title?, message, variant }`)	`boolean`
`GET`	`/tui/control/next`	Aguardar a próxima solicitação de controle	Objeto de solicitação de controle
`POST`	`/tui/control/response`	Responder a uma solicitação de controle (`{ body }`)	`boolean`

Auth

Método	Caminho	Descrição	Resposta
`PUT`	`/auth/:id`	Definir as credenciais de autenticação. O body deve corresponder ao schema do provedor	`boolean`

Eventos

Método	Caminho	Descrição	Resposta
`GET`	`/event`	Stream de server-sent events. O primeiro evento é `server.connected`, depois os eventos do bus	Stream de server-sent events

Docs

Método	Caminho	Descrição	Resposta
`GET`	`/doc`	Especificação OpenAPI 3.1	Página HTML com a spec OpenAPI

SDK Plugins