Server

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

Terminal

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:

Terminal

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

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.

Terminal

OPENCODE_SERVER_PASSWORD=your-password opencode serve

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.

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.

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.

Der opencode-Server stellt folgende APIs bereit.

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

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

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

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

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 } }`

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`

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
`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
`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`

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[]`}`

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

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)

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`

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

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

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

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`

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

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

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

Server

Nutzung

Optionen

Authentifizierung

Funktionsweise

Mit bestehendem Server verbinden

Spec

APIs

Global

Project

Path & VCS

Instanz

Konfiguration

Anbieter

Sitzungen

Nachrichten

Befehle

Dateien

/find/file Abfrageparameter

Werkzeuge (Experimentell)

LSP, Formatierer & MCP

Agenten

Logging

TUI

Authentifizierung

Events

Dokumentation

`/find/file` Abfrageparameter