--- title: Server description: Nutze den opencode-Server ueber HTTP. --- import config from "../../../../config.mjs" export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts` Der Befehl `opencode serve` startet einen headless HTTP-Server. Er stellt einen OpenAPI-Endpunkt bereit, den ein opencode-Client nutzen kann. --- ### Nutzung ```bash opencode serve [--port ] [--hostname ] [--cors ] ``` #### 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: ```bash 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`. ```bash 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](/docs/sdk). :::tip 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](/docs/cli) vor und verbindest dich dann gezielt damit. Der Endpunkt [`/tui`](#tui) kann die TUI ueber den Server steuern, etwa zum Vorbelegen oder Abschicken von Prompts. Dieses Muster nutzen auch die OpenCode-[IDE](/docs/ide)-Plugins. --- ## Spec Der Server veroeffentlicht eine OpenAPI-3.1-Spezifikation unter: ``` http://:/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=` | Sucht Text in Dateien | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` | | `GET` | `/find/file?query=` | Findet Dateien und Verzeichnisse nach Namen | `string[]` (paths) | | `GET` | `/find/symbol?query=` | Findet Workspace-Symbole | Symbol[] | | `GET` | `/file?path=` | Listet Dateien und Verzeichnisse | FileNode[] | | `GET` | `/file/content?path=

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

&model=` | 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 |