Vai al contenuto
Utilizzo

Server

Il comando opencode serve avvia un server HTTP headless che espone un endpoint OpenAPI utilizzabile da un client opencode.

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

Opzioni

FlagDescrizionePredefinito
--portPorta su cui ascoltare4096
--hostnameHostname su cui ascoltare127.0.0.1
--mdnsAbilita la scoperta mDNSfalse
--mdns-domainNome di dominio personalizzato mDNSopencode.local
--corsOrigin browser aggiuntive da permettere[]

--cors puo essere passato piu volte:

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

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.

Terminale
OPENCODE_SERVER_PASSWORD=your-password opencode serve

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.

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 --hostname e --port e poi usare questi valori per connetterti al suo server.

L’endpoint /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 di OpenCode.

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.

Il server opencode espone le seguenti API.

MetodoPathDescrizioneResponse
GET/global/healthStato di salute e versione{ healthy: true, version: string }
GET/global/eventEventi globali (stream SSE)Event stream

MetodoPathDescrizioneResponse
GET/projectElenca tutti i progettiProject[]
GET/project/currentProgetto correnteProject

MetodoPathDescrizioneResponse
GET/pathPercorso correntePath
GET/vcsInfo VCS per il progetto correnteVcsInfo

MetodoPathDescrizioneResponse
POST/instance/disposeRilascia l’istanza correnteboolean

MetodoPathDescrizioneResponse
GET/configInfo sulla configConfig
PATCH/configAggiorna la configConfig
GET/config/providersElenca provider e modelli default{ providers: Provider[], default: { [key: string]: string } }

MetodoPathDescrizioneResponse
GET/providerElenca tutti i provider{ all: Provider[], default: {...}, connected: string[] }
GET/provider/authMetodi auth dei provider{ [providerID: string]: ProviderAuthMethod[] }
POST/provider/{id}/oauth/authorizeAutorizza un provider via OAuthProviderAuthAuthorization
POST/provider/{id}/oauth/callbackGestisce callback OAuthboolean

MetodoPathDescrizioneNote
GET/sessionElenca tutte le sessioniReturns Session[]
POST/sessionCrea una nuova sessionebody: { parentID?, title? }, returns Session
GET/session/statusStato di tutte le sessioniReturns { [sessionID: string]: SessionStatus }
GET/session/:idDettagli di sessioneReturns Session
DELETE/session/:idElimina una sessione e i suoi datiReturns boolean
PATCH/session/:idAggiorna proprieta sessionebody: { title? }, returns Session
GET/session/:id/childrenSessioni figlieReturns Session[]
POST/session/:id/initAnalizza app e crea AGENTS.mdbody: { messageID, providerID, modelID }, returns boolean
POST/session/:id/forkFork di sessione su un messaggiobody: { messageID? }, returns Session
POST/session/:id/abortInterrompe una sessione in esecuzioneReturns boolean
GET/session/:id/diffDiff della sessionequery: messageID?, returns FileDiff[]
POST/session/:id/summarizeRiassume la sessionebody: { providerID, modelID }, returns boolean
POST/session/:id/revertRipristina un messaggiobody: { messageID, partID? }, returns boolean
POST/session/:id/unrevertRipristina tutti i messaggi revertitiReturns boolean
POST/session/:id/permissions/:permissionIDRisponde a una richiesta permessibody: { response, remember? }, returns boolean

MetodoPathDescrizioneNote
GET/session/:id/messageElenca messaggi in una sessionequery: limit?, returns { info: Message, parts: Part[]}[]
POST/session/:id/messageInvia un messaggio e attende rispostabody: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, returns { info: Message, parts: Part[]}
GET/session/:id/message/:messageIDDettagli messaggioReturns { info: Message, parts: Part[]}
POST/session/:id/prompt_asyncInvia un messaggio in async (senza wait)body: same as /session/:id/message, returns 204 No Content
POST/session/:id/commandEsegue un comando slashbody: { messageID?, agent?, model?, command, arguments }, returns { info: Message, parts: Part[]}
POST/session/:id/shellEsegue un comando shellbody: { agent, model?, command }, returns { info: Message, parts: Part[]}

MetodoPathDescrizioneResponse
GET/commandElenca i comandiCommand[]

MetodoPathDescrizioneResponse
GET/find?pattern=<pat>Cerca testo nei fileArray of match objects with path, lines, line_number, absolute_offset, submatches
GET/find/file?query=<q>Trova file e directory per nomestring[] (paths)
GET/find/symbol?query=<q>Trova simboli workspaceSymbol[]
GET/file?path=<path>Elenca file e directoryFileNode[]
GET/file/content?path=<p>Legge un fileFileContent
GET/file/statusStato dei file tracciatiFile[]

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

MetodoPathDescrizioneResponse
GET/experimental/tool/idsElenca tutti i tool IDToolIDs
GET/experimental/tool?provider=<p>&model=<m>Elenca tool con JSON schema per un modelloToolList

MetodoPathDescrizioneResponse
GET/lspStato server LSPLSPStatus[]
GET/formatterStato formatterFormatterStatus[]
GET/mcpStato server MCP{ [name: string]: MCPStatus }
POST/mcpAggiunge server MCP runtimebody: { name, config }, returns MCP status object

MetodoPathDescrizioneResponse
GET/agentElenca tutti gli agentiAgent[]

MetodoPathDescrizioneResponse
POST/logScrive una voce di log. Body: { service, level, message, extra? }boolean

MetodoPathDescrizioneResponse
POST/tui/append-promptAggiunge testo al promptboolean
POST/tui/open-helpApre il dialog helpboolean
POST/tui/open-sessionsApre il selettore sessioniboolean
POST/tui/open-themesApre il selettore temiboolean
POST/tui/open-modelsApre il selettore modelliboolean
POST/tui/submit-promptInvia il prompt correnteboolean
POST/tui/clear-promptPulisce il promptboolean
POST/tui/execute-commandEsegue un comando ({ command })boolean
POST/tui/show-toastMostra toast ({ title?, message, variant })boolean
GET/tui/control/nextAttende la prossima richiesta di controlloControl request object
POST/tui/control/responseRisponde a una richiesta di controllo ({ body })boolean

MetodoPathDescrizioneResponse
PUT/auth/:idImposta credenziali auth. Il body deve rispettare lo schema providerboolean

MetodoPathDescrizioneResponse
GET/eventStream SSE. Primo evento server.connected, poi eventi busServer-sent events stream

MetodoPathDescrizioneResponse
GET/docSpecifica OpenAPI 3.1Pagina HTML con spec OpenAPI