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
|
---
title: Server
description: Interagisci con il server opencode via HTTP.
---
import config from "../../../../config.mjs"
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
Il comando `opencode serve` avvia un server HTTP headless che espone un endpoint OpenAPI utilizzabile da un client opencode.
---
### Utilizzo
```bash
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
```
#### Opzioni
| Flag | Descrizione | Predefinito |
| --------------- | --------------------------------------- | ---------------- |
| `--port` | Porta su cui ascoltare | `4096` |
| `--hostname` | Hostname su cui ascoltare | `127.0.0.1` |
| `--mdns` | Abilita la scoperta mDNS | `false` |
| `--mdns-domain` | Nome di dominio personalizzato mDNS | `opencode.local` |
| `--cors` | Origin browser aggiuntive da permettere | `[]` |
`--cors` puo essere passato piu volte:
```bash
opencode serve --cors http://localhost:5173 --cors https://app.example.com
```
---
### Autenticazione
Imposta `OPENCODE_SERVER_PASSWORD` per proteggere il server con HTTP basic auth. Lo username predefinito e `opencode`, oppure imposta `OPENCODE_SERVER_USERNAME` per sovrascriverlo. Questo vale sia per `opencode serve` sia per `opencode web`.
```bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve
```
---
### Come funziona
Quando esegui `opencode` avvia una TUI e un server. La TUI e il client che parla col server. Il server espone un endpoint con specifica OpenAPI 3.1. Questo endpoint viene anche usato per generare un [SDK](/docs/sdk).
:::tip
Usa il server opencode per interagire con opencode in modo programmatico.
:::
Questa architettura permette a opencode di supportare piu client e di essere usato in modo programmatico.
Puoi eseguire `opencode serve` per avviare un server standalone. Se la TUI di opencode e gia in esecuzione, `opencode serve` avviera un nuovo server.
---
#### Connettersi a un server esistente
Quando avvii la TUI assegna casualmente porta e hostname. In alternativa puoi passare i [flag](/docs/cli) `--hostname` e `--port` e poi usare questi valori per connetterti al suo server.
L'endpoint [`/tui`](#tui) puo essere usato per pilotare la TUI tramite il server. Per esempio, puoi precompilare o eseguire un prompt. Questa configurazione e usata dai plugin [IDE](/docs/ide) di OpenCode.
---
## Specifica
Il server pubblica una specifica OpenAPI 3.1 visualizzabile su:
```
http://<hostname>:<port>/doc
```
Per esempio, `http://localhost:4096/doc`. Usa la spec per generare client o ispezionare i tipi di request/response, oppure visualizzala in uno Swagger explorer.
---
## API
Il server opencode espone le seguenti API.
---
### Globale
| Metodo | Path | Descrizione | Response |
| ------ | ---------------- | --------------------------- | ------------------------------------ |
| `GET` | `/global/health` | Stato di salute e versione | `{ healthy: true, version: string }` |
| `GET` | `/global/event` | Eventi globali (stream SSE) | Event stream |
---
### Progetto
| Metodo | Path | Descrizione | Response |
| ------ | ------------------ | ----------------------- | --------------------------------------------- |
| `GET` | `/project` | Elenca tutti i progetti | <a href={typesUrl}><code>Project[]</code></a> |
| `GET` | `/project/current` | Progetto corrente | <a href={typesUrl}><code>Project</code></a> |
---
### Percorso e VCS
| Metodo | Path | Descrizione | Response |
| ------ | ------- | --------------------------------- | ------------------------------------------- |
| `GET` | `/path` | Percorso corrente | <a href={typesUrl}><code>Path</code></a> |
| `GET` | `/vcs` | Info VCS per il progetto corrente | <a href={typesUrl}><code>VcsInfo</code></a> |
---
### Istanza
| Metodo | Path | Descrizione | Response |
| ------ | ------------------- | --------------------------- | --------- |
| `POST` | `/instance/dispose` | Rilascia l'istanza corrente | `boolean` |
---
### Configurazione
| Metodo | Path | Descrizione | Response |
| ------- | ------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
| `GET` | `/config` | Info sulla config | <a href={typesUrl}><code>Config</code></a> |
| `PATCH` | `/config` | Aggiorna la config | <a href={typesUrl}><code>Config</code></a> |
| `GET` | `/config/providers` | Elenca provider e modelli default | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
---
### Fornitori
| Metodo | Path | Descrizione | Response |
| ------ | -------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| `GET` | `/provider` | Elenca tutti i provider | `{ all: `<a href={typesUrl}>Provider[]</a>`, default: {...}, connected: string[] }` |
| `GET` | `/provider/auth` | Metodi auth dei provider | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` |
| `POST` | `/provider/{id}/oauth/authorize` | Autorizza un provider via OAuth | <a href={typesUrl}><code>ProviderAuthAuthorization</code></a> |
| `POST` | `/provider/{id}/oauth/callback` | Gestisce callback OAuth | `boolean` |
---
### Sessioni
| Metodo | Path | Descrizione | Note |
| -------- | ---------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET` | `/session` | Elenca tutte le sessioni | Returns <a href={typesUrl}><code>Session[]</code></a> |
| `POST` | `/session` | Crea una nuova sessione | body: `{ parentID?, title? }`, returns <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/status` | Stato di tutte le sessioni | Returns `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` |
| `GET` | `/session/:id` | Dettagli di sessione | Returns <a href={typesUrl}><code>Session</code></a> |
| `DELETE` | `/session/:id` | Elimina una sessione e i suoi dati | Returns `boolean` |
| `PATCH` | `/session/:id` | Aggiorna proprieta sessione | body: `{ title? }`, returns <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/children` | Sessioni figlie | Returns <a href={typesUrl}><code>Session[]</code></a> |
| `GET` | `/session/:id/todo` | Todo list della sessione | Returns <a href={typesUrl}><code>Todo[]</code></a> |
| `POST` | `/session/:id/init` | Analizza app e crea `AGENTS.md` | body: `{ messageID, providerID, modelID }`, returns `boolean` |
| `POST` | `/session/:id/fork` | Fork di sessione su un messaggio | body: `{ messageID? }`, returns <a href={typesUrl}><code>Session</code></a> |
| `POST` | `/session/:id/abort` | Interrompe una sessione in esecuzione | Returns `boolean` |
| `POST` | `/session/:id/share` | Condivide una sessione | Returns <a href={typesUrl}><code>Session</code></a> |
| `DELETE` | `/session/:id/share` | Annulla condivisione | Returns <a href={typesUrl}><code>Session</code></a> |
| `GET` | `/session/:id/diff` | Diff della sessione | query: `messageID?`, returns <a href={typesUrl}><code>FileDiff[]</code></a> |
| `POST` | `/session/:id/summarize` | Riassume la sessione | body: `{ providerID, modelID }`, returns `boolean` |
| `POST` | `/session/:id/revert` | Ripristina un messaggio | body: `{ messageID, partID? }`, returns `boolean` |
| `POST` | `/session/:id/unrevert` | Ripristina tutti i messaggi revertiti | Returns `boolean` |
| `POST` | `/session/:id/permissions/:permissionID` | Risponde a una richiesta permessi | body: `{ response, remember? }`, returns `boolean` |
---
### Messaggi
| Metodo | Path | Descrizione | Note |
| ------ | --------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/session/:id/message` | Elenca messaggi in una sessione | query: `limit?`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
| `POST` | `/session/:id/message` | Invia un messaggio e attende risposta | 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` | Dettagli messaggio | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/prompt_async` | Invia un messaggio in async (senza wait) | body: same as `/session/:id/message`, returns `204 No Content` |
| `POST` | `/session/:id/command` | Esegue un comando slash | body: `{ messageID?, agent?, model?, command, arguments }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
| `POST` | `/session/:id/shell` | Esegue un comando shell | body: `{ agent, model?, command }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
---
### Comandi
| Metodo | Path | Descrizione | Response |
| ------ | ---------- | ---------------- | --------------------------------------------- |
| `GET` | `/command` | Elenca i comandi | <a href={typesUrl}><code>Command[]</code></a> |
---
### File
| Metodo | Path | Descrizione | Response |
| ------ | ------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------- |
| `GET` | `/find?pattern=<pat>` | Cerca testo nei file | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
| `GET` | `/find/file?query=<q>` | Trova file e directory per nome | `string[]` (paths) |
| `GET` | `/find/symbol?query=<q>` | Trova simboli workspace | <a href={typesUrl}><code>Symbol[]</code></a> |
| `GET` | `/file?path=<path>` | Elenca file e directory | <a href={typesUrl}><code>FileNode[]</code></a> |
| `GET` | `/file/content?path=<p>` | Legge un file | <a href={typesUrl}><code>FileContent</code></a> |
| `GET` | `/file/status` | Stato dei file tracciati | <a href={typesUrl}><code>File[]</code></a> |
#### `/find/file` query parameters
- `query` (required) — stringa di ricerca (fuzzy match)
- `type` (optional) — limita i risultati a `"file"` o `"directory"`
- `directory` (optional) — sovrascrive la root del progetto per la ricerca
- `limit` (optional) — massimo risultati (1–200)
- `dirs` (optional) — flag legacy (`"false"` restituisce solo file)
---
### Strumenti (sperimentale)
| Metodo | Path | Descrizione | Response |
| ------ | ------------------------------------------- | ------------------------------------------ | -------------------------------------------- |
| `GET` | `/experimental/tool/ids` | Elenca tutti i tool ID | <a href={typesUrl}><code>ToolIDs</code></a> |
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | Elenca tool con JSON schema per un modello | <a href={typesUrl}><code>ToolList</code></a> |
---
### LSP, formatter e MCP
| Metodo | Path | Descrizione | Response |
| ------ | ------------ | --------------------------- | -------------------------------------------------------- |
| `GET` | `/lsp` | Stato server LSP | <a href={typesUrl}><code>LSPStatus[]</code></a> |
| `GET` | `/formatter` | Stato formatter | <a href={typesUrl}><code>FormatterStatus[]</code></a> |
| `GET` | `/mcp` | Stato server MCP | `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` |
| `POST` | `/mcp` | Aggiunge server MCP runtime | body: `{ name, config }`, returns MCP status object |
---
### Agenti
| Metodo | Path | Descrizione | Response |
| ------ | -------- | ----------------------- | ------------------------------------------- |
| `GET` | `/agent` | Elenca tutti gli agenti | <a href={typesUrl}><code>Agent[]</code></a> |
---
### Log
| Metodo | Path | Descrizione | Response |
| ------ | ------ | ------------------------------------------------------------------- | --------- |
| `POST` | `/log` | Scrive una voce di log. Body: `{ service, level, message, extra? }` | `boolean` |
---
### TUI
| Metodo | Path | Descrizione | Response |
| ------ | ----------------------- | -------------------------------------------------- | ---------------------- |
| `POST` | `/tui/append-prompt` | Aggiunge testo al prompt | `boolean` |
| `POST` | `/tui/open-help` | Apre il dialog help | `boolean` |
| `POST` | `/tui/open-sessions` | Apre il selettore sessioni | `boolean` |
| `POST` | `/tui/open-themes` | Apre il selettore temi | `boolean` |
| `POST` | `/tui/open-models` | Apre il selettore modelli | `boolean` |
| `POST` | `/tui/submit-prompt` | Invia il prompt corrente | `boolean` |
| `POST` | `/tui/clear-prompt` | Pulisce il prompt | `boolean` |
| `POST` | `/tui/execute-command` | Esegue un comando (`{ command }`) | `boolean` |
| `POST` | `/tui/show-toast` | Mostra toast (`{ title?, message, variant }`) | `boolean` |
| `GET` | `/tui/control/next` | Attende la prossima richiesta di controllo | Control request object |
| `POST` | `/tui/control/response` | Risponde a una richiesta di controllo (`{ body }`) | `boolean` |
---
### Autenticazione
| Metodo | Path | Descrizione | Response |
| ------ | ----------- | -------------------------------------------------------------------- | --------- |
| `PUT` | `/auth/:id` | Imposta credenziali auth. Il body deve rispettare lo schema provider | `boolean` |
---
### Eventi
| Metodo | Path | Descrizione | Response |
| ------ | -------- | ----------------------------------------------------------- | ------------------------- |
| `GET` | `/event` | Stream SSE. Primo evento `server.connected`, poi eventi bus | Server-sent events stream |
---
### Documentazione
| Metodo | Path | Descrizione | Response |
| ------ | ------ | --------------------- | ---------------------------- |
| `GET` | `/doc` | Specifica OpenAPI 3.1 | Pagina HTML con spec OpenAPI |
|
