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