opencode/packages/web/src/content/docs/de/server.mdx

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