File size: 19,059 Bytes
0dbc9de | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 | ---
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 <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:
```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://<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 | <a href={typesUrl}><code>Project[]</code></a> |
| `GET` | `/project/current` | Ruft das aktuelle Projekt ab | <a href={typesUrl}><code>Project</code></a> |
---
### Path & VCS
| Method | Path | Description | Response |
| ------ | ------- | ------------------------------------------- | ------------------------------------------- |
| `GET` | `/path` | Ruft den aktuellen Pfad ab | <a href={typesUrl}><code>Path</code></a> |
| `GET` | `/vcs` | Ruft VCS-Infos fuer das aktuelle Projekt ab | <a href={typesUrl}><code>VcsInfo</code></a> |
---
### Instanz
| Method | Path | Description | Response |
| ------ | ------------------- | ---------------------------- | --------- |
| `POST` | `/instance/dispose` | Beendet die aktuelle Instanz | `boolean` |
---
### Konfiguration
| Method | Path | Description | Response |
| ------- | ------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- |
| `GET` | `/config` | Ruft Konfigurationsinfos ab | <a href={typesUrl}><code>Config</code></a> |
| `PATCH` | `/config` | Aktualisiert Konfiguration | <a href={typesUrl}><code>Config</code></a> |
| `GET` | `/config/providers` | Listet Provider und Standard-Modelle | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
---
### Anbieter
| Method | Path | Description | Response |
| ------ | -------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
| `GET` | `/provider` | Listet alle Provider | `{ all: `<a href={typesUrl}>Provider[]</a>`, default: {...}, connected: string[] }` |
| `GET` | `/provider/auth` | Ruft Authentifizierungsmethoden der Provider ab | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` |
| `POST` | `/provider/{id}/oauth/authorize` | Autorisiert einen Provider per OAuth | <a href={typesUrl}><code>ProviderAuthAuthorization</code></a> |
| `POST` | `/provider/{id}/oauth/callback` | Behandelt OAuth-Callback fuer einen Provider | `boolean` |
---
### Sitzungen
| Method | Path | Description | Notes |
| -------- | ---------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET` | `/session` | Listet alle Sitzungen | Gibt <a href={typesUrl}><code>Session[]</code></a> zurueck |
| `POST` | `/session` | Erstellt eine neue Sitzung | body: `{ parentID?, title? }`, returns <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/status` | Ruft Status aller Sitzungen ab | Gibt `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` zurueck |
| `GET` | `/session/:id` | Ruft Sitzungsdetails ab | Gibt <a href={typesUrl}><code>Session</code></a> zurueck |
| `DELETE` | `/session/:id` | Loescht eine Sitzung und alle Daten | Gibt `boolean` zurueck |
| `PATCH` | `/session/:id` | Aktualisiert Sitzungseigenschaften | body: `{ title? }`, returns <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/children` | Ruft Kind-Sitzungen einer Sitzung ab | Gibt <a href={typesUrl}><code>Session[]</code></a> zurueck |
| `GET` | `/session/:id/todo` | Ruft die Todo-Liste einer Sitzung ab | Gibt <a href={typesUrl}><code>Todo[]</code></a> 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 <a href={typesUrl}><code>Session</code></a> |
| `POST` | `/session/:id/abort` | Bricht eine laufende Sitzung ab | Gibt `boolean` zurueck |
| `POST` | `/session/:id/share` | Teilt eine Sitzung | Gibt <a href={typesUrl}><code>Session</code></a> zurueck |
| `DELETE` | `/session/:id/share` | Hebt Teilen einer Sitzung auf | Gibt <a href={typesUrl}><code>Session</code></a> zurueck |
| `GET` | `/session/:id/diff` | Ruft den Diff fuer diese Sitzung ab | query: `messageID?`, returns <a href={typesUrl}><code>FileDiff[]</code></a> |
| `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: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
| `POST` | `/session/:id/message` | Sendet eine Nachricht und wartet auf Antwort | body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `GET` | `/session/:id/message/:messageID` | Ruft Nachrichtendetails ab | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `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: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/shell` | Fuehrt einen Shell-Befehl aus | body: `{ agent, model?, command }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
---
### Befehle
| Method | Path | Description | Response |
| ------ | ---------- | ------------------- | --------------------------------------------- |
| `GET` | `/command` | Listet alle Befehle | <a href={typesUrl}><code>Command[]</code></a> |
---
### 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 | <a href={typesUrl}><code>Symbol[]</code></a> |
| `GET` | `/file?path=<path>` | Listet Dateien und Verzeichnisse | <a href={typesUrl}><code>FileNode[]</code></a> |
| `GET` | `/file/content?path=<p>` | Liest eine Datei | <a href={typesUrl}><code>FileContent</code></a> |
| `GET` | `/file/status` | Ruft Status fuer getrackte Dateien ab | <a href={typesUrl}><code>File[]</code></a> |
#### `/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 | <a href={typesUrl}><code>ToolIDs</code></a> |
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | Listet Tools mit JSON-Schemas fuer ein Modell | <a href={typesUrl}><code>ToolList</code></a> |
---
### LSP, Formatierer & MCP
| Method | Path | Description | Response |
| ------ | ------------ | -------------------------------- | -------------------------------------------------------- |
| `GET` | `/lsp` | Ruft LSP-Server-Status ab | <a href={typesUrl}><code>LSPStatus[]</code></a> |
| `GET` | `/formatter` | Ruft Formatter-Status ab | <a href={typesUrl}><code>FormatterStatus[]</code></a> |
| `GET` | `/mcp` | Ruft MCP-Server-Status ab | `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` |
| `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 | <a href={typesUrl}><code>Agent[]</code></a> |
---
### 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 |
|