Skip to content

server.mdx

Latest commit

 

History

History
291 lines (204 loc) · 18.6 KB

server.mdx

File metadata and controls

291 lines (204 loc) · 18.6 KB
Raw
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

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:

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.

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.

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

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

Werkzeuge (Experimentell)

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

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