Servidor

O comando opencode serve executa um servidor HTTP sem cabeça que expõe um endpoint OpenAPI que um cliente opencode pode usar.

---

Uso

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

Opções

Flag	Descrição	Padrão
--port	Porta para escutar	4096
--hostname	Nome do host para escutar	127.0.0.1
--mdns	Habilitar descoberta mDNS	false
--mdns-domain	Nome de domínio personalizado para o serviço mDNS	opencode.local
--cors	Origens adicionais de navegador 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 básica HTTP. O nome de usuário padrão é opencode, ou defina OPENCODE_SERVER_USERNAME para substituí-lo. Isso se aplica tanto ao opencode serve quanto ao opencode web.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

---

Como funciona

Quando você executa opencode, ele inicia um TUI e um servidor. Onde o TUI é o cliente que se comunica com o servidor. O servidor expõe um endpoint de especificação OpenAPI 3.1. Este endpoint também é usado para gerar um SDK.

Dica

Use o servidor opencode para interagir com o opencode programaticamente.

Essa arquitetura permite que o opencode suporte múltiplos clientes e permite que você interaja com o opencode programaticamente.

Você pode executar opencode serve para iniciar um servidor autônomo. Se você tiver o TUI do opencode em execução, opencode serve iniciará um novo servidor.

---

Conectar a um servidor existente

Quando você inicia o TUI, ele atribui aleatoriamente uma porta e um nome de host. Você pode passar os flags --hostname e --port. Em seguida, use isso para se conectar ao seu servidor.

O endpoint /tui pode ser usado para controlar o TUI através do servidor. Por exemplo, você pode preencher ou executar um prompt. Essa configuração é usada pelos plugins do opencode IDE.

---

Especificação

O servidor publica uma especificação OpenAPI 3.1 que pode ser visualizada em:

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

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

---

APIs

O servidor opencode expõe as seguintes APIs.

---

Global

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

---

Projeto

Método	Caminho	Descrição	Resposta
GET	/project	Listar todos os projetos	Project[]
GET	/project/current	Obter o projeto atual	Project

---

Caminho & VCS

Método	Caminho	Descrição	Resposta
GET	/path	Obter o caminho atual	Path
GET	/vcs	Obter informações do VCS para o projeto atual	VcsInfo

---

Instância

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

---

Configuração

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

---

Provedor

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

---

Sessões

Método	Caminho	Descrição	Notas
GET	/session	Listar todas as sessões	Retorna Session[]
POST	/session	Criar uma nova sessão	corpo: { parentID?, title? }, retorna Session
GET	/session/status	Obter status da sessão para todas as sessões	Retorna { [sessionID: string]: SessionStatus }
GET	/session/:id	Obter detalhes da sessão	Retorna Session
DELETE	/session/:id	Deletar uma sessão e todos os seus dados	Retorna boolean
PATCH	/session/:id	Atualizar propriedades da sessão	corpo: { title? }, retorna Session
GET	/session/:id/children	Obter as sessões filhas de uma sessão	Retorna Session[]
GET	/session/:id/todo	Obter a lista de tarefas para uma sessão	Retorna Todo[]
POST	/session/:id/init	Analisar o app e criar AGENTS.md	corpo: { messageID, providerID, modelID }, retorna boolean
POST	/session/:id/fork	Fazer um fork de uma sessão existente em uma mensagem	corpo: { messageID? }, retorna Session
POST	/session/:id/abort	Abortar uma sessão em execução	Retorna boolean
POST	/session/:id/share	Compartilhar uma sessão	Retorna Session
DELETE	/session/:id/share	Descompartilhar uma sessão	Retorna Session
GET	/session/:id/diff	Obter a diferença para esta sessão	query: messageID?, retorna FileDiff[]
POST	/session/:id/summarize	Resumir a sessão	corpo: { providerID, modelID }, retorna boolean
POST	/session/:id/revert	Reverter uma mensagem	corpo: { messageID, partID? }, retorna boolean
POST	/session/:id/unrevert	Restaurar todas as mensagens revertidas	Retorna boolean
POST	/session/:id/permissions/:permissionID	Responder a um pedido de permissão	corpo: { response, remember? }, retorna boolean

---

Mensagens

Método	Caminho	Descrição	Notas
GET	/session/:id/message	Listar mensagens em uma sessão	query: limit?, retorna { info: Message, parts: Part[]}[]
POST	/session/:id/message	Enviar uma mensagem e aguardar resposta	corpo: { 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 uma mensagem assíncrona (sem espera)	corpo: igual a /session/:id/message, retorna 204 No Content
POST	/session/:id/command	Executar um comando de barra	corpo: { messageID?, agent?, model?, command, arguments }, retorna { info: Message, parts: Part[]}
POST	/session/:id/shell	Executar um comando shell	corpo: { agent, model?, command }, retorna { info: Message, parts: Part[]}

---

Comandos

Método	Caminho	Descrição	Resposta
GET	/command	Listar todos os comandos	Command[]

---

Arquivos

Método	Caminho	Descrição	Resposta
GET	/find?pattern=<pat>	Pesquisar 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[]
GET	/file?path=<path>	Listar arquivos e diretórios	FileNode[]
GET	/file/content?path=<p>	Ler um arquivo	FileContent
GET	/file/status	Obter status para arquivos rastreados	File[]

Parâmetros de consulta /find/file

• query (obrigatório) — string de pesquisa (correspondência difusa)
• type (opcional) — limitar resultados a "file" ou "directory"
• directory (opcional) — substituir a raiz do projeto para a pesquisa
• limit (opcional) — resultados máximos (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
GET	/experimental/tool?provider=<p>&model=<m>	Listar ferramentas com esquemas JSON para um modelo	ToolList

---

LSP, Formatadores & MCP

Método	Caminho	Descrição	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	corpo: { name, config }, retorna objeto de status MCP

---

Agentes

Método	Caminho	Descrição	Resposta
GET	/agent	Listar todos os agentes disponíveis	Agent[]

---

Registro

Método	Caminho	Descrição	Resposta
POST	/log	Escrever entrada de log. Corpo: { 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 toast ({ title?, message, variant })	boolean
GET	/tui/control/next	Aguardar o próximo pedido de controle	Objeto de pedido de controle
POST	/tui/control/response	Responder a um pedido de controle ({ body })	boolean

---

Auth

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

---

Eventos

Método	Caminho	Descrição	Resposta
GET	/event	Fluxo de eventos enviados pelo servidor. O primeiro evento é server.connected, depois eventos de bus	Fluxo de eventos enviados pelo servidor

---

Docs

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