Server

Der Befehl opencode serve startet einen headless HTTP-Server. Er stellt einen OpenAPI-Endpunkt bereit, den ein opencode-Client nutzen kann.

---

Nutzung

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

Optionen

Flag	Description	Default
--port	Port to listen on	4096
--hostname	Hostname to listen on	127.0.0.1
--mdns	Enable mDNS discovery	false
--mdns-domain	Custom domain name for mDNS service	opencode.local
--cors	Additional browser origins to allow	[]

--cors kann mehrfach angegeben werden:

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

---

Authentifizierung

Setze OPENCODE_SERVER_PASSWORD, um den Server mit HTTP Basic Auth zu schuetzen. Der Benutzername ist standardmaessig opencode, kann aber mit OPENCODE_SERVER_USERNAME ueberschrieben werden. Das gilt fuer opencode serve und opencode web.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

---

Funktionsweise

Wenn du opencode startest, werden TUI und Server gestartet. Die TUI ist dabei der Client, der mit dem Server spricht; dessen OpenAPI-3.1-Endpunkt dient auch zur Generierung des SDK.

Tipp

Nutze den opencode-Server, um opencode programmatisch anzusteuern.

Diese Architektur erlaubt mehrere Clients und programmatische Nutzung.

Mit opencode serve startest du einen eigenstaendigen Server. Laeuft bereits eine TUI, startet opencode serve trotzdem eine neue Serverinstanz.

---

Mit bestehendem Server verbinden

Beim TUI-Start werden Port und Hostname zufaellig gewaehlt. Alternativ gibst du --hostname und --port als Flags vor und verbindest dich dann gezielt damit.

Der Endpunkt /tui kann die TUI ueber den Server steuern, etwa zum Vorbelegen oder Abschicken von Prompts. Dieses Muster nutzen auch die OpenCode-IDE-Plugins.

---

Spec

Der Server veroeffentlicht eine OpenAPI-3.1-Spezifikation unter:

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

Zum Beispiel http://localhost:4096/doc. Nutze die Spec zum Generieren von Clients, zum Pruefen von Request/Response-Typen oder in einem Swagger-Explorer.

---

APIs

Der opencode-Server stellt folgende APIs bereit.

---

Global

Method	Path	Description	Response
GET	/global/health	Ruft Server-Status und Version ab	{ healthy: true, version: string }
GET	/global/event	Ruft globale Events ab (SSE-Stream)	Event stream

---

Project

Method	Path	Description	Response
GET	/project	Listet alle Projekte	Project[]
GET	/project/current	Ruft das aktuelle Projekt ab	Project

---

Path & VCS

Method	Path	Description	Response
GET	/path	Ruft den aktuellen Pfad ab	Path
GET	/vcs	Ruft VCS-Infos fuer das aktuelle Projekt ab	VcsInfo

---

Instanz

Method	Path	Description	Response
POST	/instance/dispose	Beendet die aktuelle Instanz	boolean

---

Konfiguration

Method	Path	Description	Response
GET	/config	Ruft Konfigurationsinfos ab	Config
PATCH	/config	Aktualisiert Konfiguration	Config
GET	/config/providers	Listet Provider und Standard-Modelle	{ providers: Provider[], default: { [key: string]: string } }

---

Anbieter

Method	Path	Description	Response
GET	/provider	Listet alle Provider	{ all: Provider[], default: {...}, connected: string[] }
GET	/provider/auth	Ruft Authentifizierungsmethoden der Provider ab	{ [providerID: string]: ProviderAuthMethod[] }
POST	/provider/{id}/oauth/authorize	Autorisiert einen Provider per OAuth	ProviderAuthAuthorization
POST	/provider/{id}/oauth/callback	Behandelt OAuth-Callback fuer einen Provider	boolean

---

Sitzungen

Method	Path	Description	Notes
GET	/session	Listet alle Sitzungen	Gibt Session[] zurueck
POST	/session	Erstellt eine neue Sitzung	body: { parentID?, title? }, returns Session
GET	/session/status	Ruft Status aller Sitzungen ab	Gibt { [sessionID: string]: SessionStatus } zurueck
GET	/session/:id	Ruft Sitzungsdetails ab	Gibt Session zurueck
DELETE	/session/:id	Loescht eine Sitzung und alle Daten	Gibt boolean zurueck
PATCH	/session/:id	Aktualisiert Sitzungseigenschaften	body: { title? }, returns Session
GET	/session/:id/children	Ruft Kind-Sitzungen einer Sitzung ab	Gibt Session[] zurueck
GET	/session/:id/todo	Ruft die Todo-Liste einer Sitzung ab	Gibt Todo[] zurueck
POST	/session/:id/init	Analysiert App und erstellt AGENTS.md	body: { messageID, providerID, modelID }, returns boolean
POST	/session/:id/fork	Forkt eine bestehende Sitzung an einer Nachricht	body: { messageID? }, returns Session
POST	/session/:id/abort	Bricht eine laufende Sitzung ab	Gibt boolean zurueck
POST	/session/:id/share	Teilt eine Sitzung	Gibt Session zurueck
DELETE	/session/:id/share	Hebt Teilen einer Sitzung auf	Gibt Session zurueck
GET	/session/:id/diff	Ruft den Diff fuer diese Sitzung ab	query: messageID?, returns FileDiff[]
POST	/session/:id/summarize	Fasst die Sitzung zusammen	body: { providerID, modelID }, returns boolean
POST	/session/:id/revert	Setzt eine Nachricht zurueck	body: { messageID, partID? }, returns boolean
POST	/session/:id/unrevert	Stellt alle zurueckgesetzten Nachrichten wieder her	Gibt boolean zurueck
POST	/session/:id/permissions/:permissionID	Antwortet auf eine Berechtigungsanfrage	body: { response, remember? }, returns boolean

---

Nachrichten

Method	Path	Description	Notes
GET	/session/:id/message	Listet Nachrichten in einer Sitzung	query: limit?, returns { info: Message, parts: Part[]}[]
POST	/session/:id/message	Sendet eine Nachricht und wartet auf Antwort	body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, returns { info: Message, parts: Part[]}
GET	/session/:id/message/:messageID	Ruft Nachrichtendetails ab	Returns { info: Message, parts: Part[]}
POST	/session/:id/prompt_async	Sendet eine Nachricht asynchron (ohne Warten)	body: same as /session/:id/message, returns 204 No Content
POST	/session/:id/command	Fuehrt einen Slash-Befehl aus	body: { messageID?, agent?, model?, command, arguments }, returns { info: Message, parts: Part[]}
POST	/session/:id/shell	Fuehrt einen Shell-Befehl aus	body: { agent, model?, command }, returns { info: Message, parts: Part[]}

---

Befehle

Method	Path	Description	Response
GET	/command	Listet alle Befehle	Command[]

---

Dateien

Method	Path	Description	Response
GET	/find?pattern=<pat>	Sucht Text in Dateien	Array of match objects with path, lines, line_number, absolute_offset, submatches
GET	/find/file?query=<q>	Findet Dateien und Verzeichnisse nach Namen	string[] (paths)
GET	/find/symbol?query=<q>	Findet Workspace-Symbole	Symbol[]
GET	/file?path=<path>	Listet Dateien und Verzeichnisse	FileNode[]
GET	/file/content?path=<p>	Liest eine Datei	FileContent
GET	/file/status	Ruft Status fuer getrackte Dateien ab	File[]

/find/file Abfrageparameter

• query (erforderlich) — Suchbegriff (Fuzzy-Suche)
• type (optional) — Ergebnisse auf "file" oder "directory" beschränken
• directory (optional) — Projektstammverzeichnis für die Suche überschreiben
• limit (optional) — Maximale Ergebnisse (1–200)
• dirs (optional) — Legacy-Flag ("false" gibt nur Dateien zurück)

---

Werkzeuge (Experimentell)

Method	Path	Description	Response
GET	/experimental/tool/ids	Listet alle Tool-IDs	ToolIDs
GET	/experimental/tool?provider=<p>&model=<m>	Listet Tools mit JSON-Schemas fuer ein Modell	ToolList

---

LSP, Formatierer & MCP

Method	Path	Description	Response
GET	/lsp	Ruft LSP-Server-Status ab	LSPStatus[]
GET	/formatter	Ruft Formatter-Status ab	FormatterStatus[]
GET	/mcp	Ruft MCP-Server-Status ab	{ [name: string]: MCPStatus }
POST	/mcp	Fuegt MCP-Server dynamisch hinzu	body: { name, config }, returns MCP status object

---

Agenten

Method	Path	Description	Response
GET	/agent	Listet alle verfuegbaren Agenten	Agent[]

---

Logging

Method	Path	Description	Response
POST	/log	Schreibt Log-Eintrag. Body: { service, level, message, extra? }	boolean

---

TUI

Method	Path	Description	Response
POST	/tui/append-prompt	Haengt Text an den Prompt an	boolean
POST	/tui/open-help	Oeffnet den Hilfedialog	boolean
POST	/tui/open-sessions	Oeffnet die Session-Auswahl	boolean
POST	/tui/open-themes	Oeffnet die Theme-Auswahl	boolean
POST	/tui/open-models	Oeffnet die Modell-Auswahl	boolean
POST	/tui/submit-prompt	Sendet den aktuellen Prompt ab	boolean
POST	/tui/clear-prompt	Leert den Prompt	boolean
POST	/tui/execute-command	Fuehrt einen Befehl aus ({ command })	boolean
POST	/tui/show-toast	Zeigt Toast ({ title?, message, variant })	boolean
GET	/tui/control/next	Wartet auf die naechste Kontrollanfrage	Control request object
POST	/tui/control/response	Antwortet auf eine Kontrollanfrage ({ body })	boolean

---

Authentifizierung

Method	Path	Description	Response
PUT	/auth/:id	Setzt Authentifizierungsdaten. Body muss dem Provider-Schema entsprechen	boolean

---

Events

Method	Path	Description	Response
GET	/event	Server-Sent Events Stream. Erstes Event ist server.connected, dann Bus-Events	Server-sent events stream

---

Dokumentation

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