Server

The opencode serve command runs a headless HTTP server that exposes an OpenAPI endpoint that an opencode client can use.

---

Usage

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

Options

Flag	Short	Description	Default
--port	-p	Port to listen on	4096
--hostname	-h	Hostname to listen on	127.0.0.1

---

How it works

When you run opencode it starts a TUI and a server. Where the TUI is the client that talks to the server. The server exposes an OpenAPI 3.1 spec endpoint. This endpoint is also used to generate an SDK.

Tip

Use the opencode server to interact with opencode programmatically.

This architecture lets opencode support multiple clients and allows you to interact with opencode programmatically.

You can run opencode serve to start a standalone server. If you have the opencode TUI running, opencode serve will start a new server.

---

Connect to an existing server

When you start the TUI it randomly assigns a port and hostname. You can instead pass in the --hostname and --port flags. Then use this to connect to its server.

The /tui endpoint can be used to drive the TUI through the server. For example, you can prefill or run a prompt. This setup is used by the opencode IDE plugins.

---

Spec

The server publishes an OpenAPI 3.1 spec that can be viewed at:

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

For example, http://localhost:4096/doc. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.

---

APIs

The opencode server exposes the following APIs.

---

App

Method	Path	Description	Response
GET	/app	Get app info	App
POST	/app/init	Initialize the app	boolean

---

Config

Method	Path	Description	Response
GET	/config	Get config info	Config
GET	/config/providers	List providers and default models	{ providers: Provider[], default: { [key: string]: string } }

---

Sessions

Method	Path	Description	Notes
GET	/session	List sessions	Returns Session[]
GET	/session/:id	Get session	Returns Session
GET	/session/:id/children	List child sessions	Returns Session[]
POST	/session	Create session	body: { parentID?, title? }, returns Session
DELETE	/session/:id	Delete session
PATCH	/session/:id	Update session properties	body: { title? }, returns Session
POST	/session/:id/init	Analyze app and create AGENTS.md	body: { messageID, providerID, modelID }
POST	/session/:id/abort	Abort a running session
POST	/session/:id/share	Share session	Returns Session
DELETE	/session/:id/share	Unshare session	Returns Session
POST	/session/:id/summarize	Summarize session
GET	/session/:id/message	List messages in a session	Returns { info: Message, parts: Part[]}[]
GET	/session/:id/message/:messageID	Get message details	Returns { info: Message, parts: Part[]}
POST	/session/:id/message	Send chat message	body matches ChatInput, returns Message
POST	/session/:id/shell	Run a shell command	body matches CommandInput, returns Message
POST	/session/:id/revert	Revert a message	body: { messageID }
POST	/session/:id/unrevert	Restore reverted messages
POST	/session/:id/permissions/:permissionID	Respond to a permission request	body: { response }

---

Files

Method	Path	Description	Response
GET	/find?pattern=<pat>	Search for text in files	Array of match objects with path, lines, line_number, absolute_offset, submatches
GET	/find/file?query=<q>	Find files by name	string[] (file paths)
GET	/find/symbol?query=<q>	Find workspace symbols	Symbol[]
GET	/file?path=<path>	Read a file	{ type: "raw" | "patch", content: string }
GET	/file/status	Get status for tracked files	File[]

---

Logging

Method	Path	Description	Response
POST	/log	Write log entry. Body: { service, level, message, extra? }	boolean

---

Agents

Method	Path	Description	Response
GET	/agent	List all available agents	Agent[]

---

TUI

Method	Path	Description	Response
POST	/tui/append-prompt	Append text to the prompt	boolean
POST	/tui/open-help	Open the help dialog	boolean
POST	/tui/open-sessions	Open the session selector	boolean
POST	/tui/open-themes	Open the theme selector	boolean
POST	/tui/open-models	Open the model selector	boolean
POST	/tui/submit-prompt	Submit the current prompt	boolean
POST	/tui/clear-prompt	Clear the prompt	boolean
POST	/tui/execute-command	Execute a command ({ command })	boolean
POST	/tui/show-toast	Show toast ({ title?, message, variant })	boolean
GET	/tui/control/next	Wait for the next control request	Control request object
POST	/tui/control/response	Respond to a control request ({ body })	boolean

---

Auth

Method	Path	Description	Response
PUT	/auth/:id	Set authentication credentials. Body must match provider schema	boolean

---

Events

Method	Path	Description	Response
GET	/event	Server-sent events stream. First event is server.connected, then bus events	Server-sent events stream

---

Docs

Method	Path	Description	Response
GET	/doc	OpenAPI 3.1 specification	HTML page with OpenAPI spec