Server

Il comando opencode serve esegue un server HTTP headless che espone un endpoint OpenAPI usato dai client OpenCode.

---

Utilizzo

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

Opzioni

Flag	Descrizione	Default
--port	Porta di ascolto	4096
--hostname	Hostname di ascolto	127.0.0.1
--mdns	Abilita il discovery mDNS	false
--cors	Origini addizionali per CORS	[]

--cors può essere specificato più volte:

opencode serve --cors http://localhost:5173 --cors https://app.example.com

---

Come funziona

Quando esegui opencode, vengono avviati sia il TUI che un server. Il TUI è il client che parla con il server. Il server espone un endpoint con specifica OpenAPI 3.1, usato anche per generare l’SDK.

Consiglio

Usa il server OpenCode quando vuoi interagire in modo programmatico con OpenCode.

Questa architettura permette di avere più client e di controllare OpenCode da script, app o integrazioni esterne.

Puoi eseguire opencode serve per avviare un server standalone. Se il TUI è già in esecuzione, opencode serve avvierà un nuovo server.

---

Connessione a un server esistente

All’avvio il TUI sceglie un hostname e una porta casuali. In alternativa puoi specificarli con i flag --hostname e --port (vedi CLI); altri client potranno quindi collegarsi a quel server.

L’endpoint /tui consente di pilotare il TUI attraverso il server: ad esempio pre‑compilare o inviare un prompt. Questo è il meccanismo usato dai plugin IDE.

---

Specifica

Il server pubblica una specifica OpenAPI 3.1 accessibile a:

http://<hostname>:<port>/doc

Ad esempio: http://localhost:4096/doc. Puoi usarla per generare client, ispezionare tipi di request/response o visualizzarla con Swagger.

---

API

Il server OpenCode espone le API seguenti.

---

Global

Metodo	Path	Descrizione	Risposta
GET	/global/health	Stato e versione del server	{ healthy: true, version: string }
GET	/global/event	Eventi globali (stream SSE)	Stream di eventi

---

Progetto

Metodo	Path	Descrizione	Risposta
GET	/project	Elenco di tutti i progetti	Project[]
GET	/project/current	Progetto corrente	Project

---

Path & VCS

Metodo	Path	Descrizione	Risposta
GET	/path	Path corrente	Path
GET	/vcs	Info VCS per il progetto corrente	VcsInfo

---

Istanza

Metodo	Path	Descrizione	Risposta
POST	/instance/dispose	Chiudere l’istanza corrente	boolean

---

Config

Metodo	Path	Descrizione	Risposta
GET	/config	Ottenere la configurazione	Config
PATCH	/config	Aggiornare la configurazione	Config
GET	/config/providers	Elenco provider e modelli di default	{ providers: Provider[], default: { [key: string]: string } }

---

Provider

Metodo	Path	Descrizione	Risposta
GET	/provider	Elenco di tutti i provider	{ all: Provider[], default: {...}, connected: string[] }
GET	/provider/auth	Metodi di autenticazione per provider	{ [providerID: string]: ProviderAuthMethod[] }
POST	/provider/{id}/oauth/authorize	Avviare OAuth per un provider	ProviderAuthAuthorization
POST	/provider/{id}/oauth/callback	Callback OAuth	boolean

---

Sessioni

Metodo	Path	Descrizione	Note
GET	/session	Elenco di tutte le sessioni	Restituisce Session[]
POST	/session	Creare una nuova sessione	body: { parentID?, title? } → Session
GET	/session/status	Stato di tutte le sessioni	{ [sessionID: string]: SessionStatus }
GET	/session/:id	Dettagli di una sessione	Session
DELETE	/session/:id	Eliminare una sessione e i suoi dati	boolean
PATCH	/session/:id	Aggiornare le proprietà di una sessione	body: { title? } → Session
GET	/session/:id/children	Elenco delle sotto‑sessioni	Session[]
GET	/session/:id/todo	Lista TODO per una sessione	Todo[]
POST	/session/:id/init	Analizzare il repo e generare AGENTS.md	body: { messageID, providerID, modelID } → boolean
POST	/session/:id/fork	Fork di una sessione a un certo messaggio	body: { messageID? } → Session
POST	/session/:id/abort	Annullare una sessione in esecuzione	boolean
POST	/session/:id/share	Condividere una sessione	Session
DELETE	/session/:id/share	Interrompere la condivisione di una sessione	Session
GET	/session/:id/diff	Ottenere il diff della sessione	query: messageID? → FileDiff[]
POST	/session/:id/summarize	Riassumere la sessione	body: { providerID, modelID } → boolean
POST	/session/:id/revert	Revert di un messaggio	body: { messageID, partID? } → boolean
POST	/session/:id/unrevert	Ripristinare messaggi revertiti	boolean
POST	/session/:id/permissions/:permissionID	Rispondere a una richiesta di permesso	body: { response, remember? } → boolean

---

Messaggi

Metodo	Path	Descrizione	Note
GET	/session/:id/message	Elenco messaggi di una sessione	query: limit? → { info: Message, parts: Part[]}[]
POST	/session/:id/message	Inviare un messaggio e attendere risposta	body: { messageID?, model?, agent?, noReply?, system?, tools?, parts } → { info, parts }
GET	/session/:id/message/:messageID	Dettagli di un messaggio	{ info: Message, parts: Part[]}
POST	/session/:id/prompt_async	Inviare un messaggio async (senza attesa)	body come /session/:id/message, risposta 204 No Content
POST	/session/:id/command	Eseguire un comando slash	body: { messageID?, agent?, model?, command, arguments } → { info, parts }
POST	/session/:id/shell	Eseguire un comando di shell	body: { agent, model?, command } → { info, parts }

---

Comandi

Metodo	Path	Descrizione	Risposta
GET	/command	Elenco di tutti i comandi	Command[]

---

File

Metodo	Path	Descrizione	Risposta
GET	/find?pattern=<pat>	Ricerca di testo nei file	Array di match con path, lines, line_number, absolute_offset, submatches
GET	/find/file?query=<q>	Ricerca file e directory per nome	string[] (path)
GET	/find/symbol?query=<q>	Ricerca simboli nel workspace	Symbol[]
GET	/file?path=<path>	Elenco file e directory	FileNode[]
GET	/file/content?path=<p>	Lettura di un file	FileContent
GET	/file/status	Stato dei file tracciati	File[]

Parametri di /find/file

• query (obbligatorio): stringa di ricerca (fuzzy)
• type (opzionale): limitare a "file" o "directory"
• directory (opzionale): root alternativa per la ricerca
• limit (opzionale): numero massimo di risultati (1–200)
• dirs (opzionale): flag legacy ("false" restituisce solo file)

---

Tools (Experimental)

Metodo	Path	Descrizione	Risposta
GET	/experimental/tool/ids	Elenco di tutti gli ID tool	ToolIDs
GET	/experimental/tool?provider=<p>&model=<m>	Elenco tool con schema JSON per un modello	ToolList

---

LSP, Formatter & MCP

Metodo	Path	Descrizione	Risposta
GET	/lsp	Stato dei server LSP	LSPStatus[]
GET	/formatter	Stato dei formatter	FormatterStatus[]
GET	/mcp	Stato dei server MCP	{ [name: string]: MCPStatus }
POST	/mcp	Aggiungere un server MCP	body: { name, config } → oggetto stato MCP

---

Agents

Metodo	Path	Descrizione	Risposta
GET	/agent	Elenco di tutti gli agent	Agent[]

---

Logging

Metodo	Path	Descrizione	Risposta
POST	/log	Scrivere una voce di log ({ service, level, message, extra? })	boolean

---

TUI

Metodo	Path	Descrizione	Risposta
POST	/tui/append-prompt	Aggiungere testo al prompt	boolean
POST	/tui/open-help	Aprire la finestra di help	boolean
POST	/tui/open-sessions	Aprire il selettore di sessioni	boolean
POST	/tui/open-themes	Aprire il selettore di temi	boolean
POST	/tui/open-models	Aprire il selettore di modelli	boolean
POST	/tui/submit-prompt	Inviare il prompt corrente	boolean
POST	/tui/clear-prompt	Svuotare il prompt	boolean
POST	/tui/execute-command	Eseguire un comando ({ command })	boolean
POST	/tui/show-toast	Mostrare un toast ({ title?, message, variant })	boolean
GET	/tui/control/next	Attendere la prossima richiesta di controllo	Oggetto di controllo
POST	/tui/control/response	Rispondere a una richiesta di controllo ({ body })	boolean

---

Auth

Metodo	Path	Descrizione	Risposta
PUT	/auth/:id	Impostare le credenziali per un provider (body secondo schema)	boolean

---

Eventi

Metodo	Path	Descrizione	Risposta
GET	/event	Stream SSE; primo evento server.connected, poi eventi del message bus	Stream eventi SSE

---

Docs

Metodo	Path	Descrizione	Risposta
GET	/doc	Specifica OpenAPI 3.1	Pagina HTML con la specifica