mirror of
https://github.com/aljazceru/opencode.git
synced 2025-12-23 10:44:21 +01:00
181 lines
12 KiB
Plaintext
181 lines
12 KiB
Plaintext
---
|
|
title: Server
|
|
description: Interact with opencode server over HTTP.
|
|
---
|
|
|
|
import config from "../../../config.mjs"
|
|
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
|
|
|
|
The `opencode serve` command runs a headless HTTP server that exposes an OpenAPI endpoint that an opencode client can use.
|
|
|
|
---
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
opencode serve [--port <number>] [--hostname <string>]
|
|
```
|
|
|
|
#### Options
|
|
|
|
| Flag | Short | Description | Default |
|
|
| ------------ | ----- | --------------------- | ----------- |
|
|
| `--port` | `-p` | Port to listen on | `4096` |
|
|
| `--hostname` | `-h` | Hostname to listen on | `127.0.0.1` |
|
|
|
|
---
|
|
|
|
### How it works
|
|
|
|
When you run `opencode` it starts a TUI and a server. Where the TUI is the
|
|
client that talks to the server. The server exposes an OpenAPI 3.1 spec
|
|
endpoint. This endpoint is also used to generate an [SDK](/docs/sdk).
|
|
|
|
:::tip
|
|
Use the opencode server to interact with opencode programmatically.
|
|
:::
|
|
|
|
This architecture lets opencode support multiple clients and allows you to interact with opencode programmatically.
|
|
|
|
You can run `opencode serve` to start a standalone server. If you have the
|
|
opencode TUI running, `opencode serve` will start a new server.
|
|
|
|
---
|
|
|
|
#### Connect to an existing server
|
|
|
|
When you start the TUI it randomly assigns a port and hostname. You can instead pass in the `--hostname` and `--port` [flags](/docs/cli). Then use this to connect to its server.
|
|
|
|
The [`/tui`](#tui) endpoint can be used to drive the TUI through the server. For example, you can prefill or run a prompt. This setup is used by the opencode [IDE](/docs/ide) plugins.
|
|
|
|
---
|
|
|
|
## Spec
|
|
|
|
The server publishes an OpenAPI 3.1 spec that can be viewed at:
|
|
|
|
```
|
|
http://<hostname>:<port>/doc
|
|
```
|
|
|
|
For example, `http://localhost:4096/doc`. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.
|
|
|
|
---
|
|
|
|
## APIs
|
|
|
|
The opencode server exposes the following APIs.
|
|
|
|
---
|
|
|
|
### App
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | ----------- | ------------------ | --------------------------------------- |
|
|
| `GET` | `/app` | Get app info | <a href={typesUrl}><code>App</code></a> |
|
|
| `POST` | `/app/init` | Initialize the app | `boolean` |
|
|
|
|
---
|
|
|
|
### Config
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | ------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
| `GET` | `/config` | Get config info | <a href={typesUrl}><code>Config</code></a> |
|
|
| `GET` | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
|
|
|
|
---
|
|
|
|
### Sessions
|
|
|
|
| Method | Path | Description | Notes |
|
|
| -------- | ---------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `GET` | `/session` | List sessions | Returns <a href={typesUrl}><code>Session[]</code></a> |
|
|
| `GET` | `/session/:id` | Get session | Returns <a href={typesUrl}><code>Session</code></a> |
|
|
| `GET` | `/session/:id/children` | List child sessions | Returns <a href={typesUrl}><code>Session[]</code></a> |
|
|
| `POST` | `/session` | Create session | body: `{ parentID?, title? }`, returns <a href={typesUrl}><code>Session</code></a> |
|
|
| `DELETE` | `/session/:id` | Delete session | |
|
|
| `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns <a href={typesUrl}><code>Session</code></a> |
|
|
| `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }` |
|
|
| `POST` | `/session/:id/abort` | Abort a running session | |
|
|
| `POST` | `/session/:id/share` | Share session | Returns <a href={typesUrl}><code>Session</code></a> |
|
|
| `DELETE` | `/session/:id/share` | Unshare session | Returns <a href={typesUrl}><code>Session</code></a> |
|
|
| `POST` | `/session/:id/summarize` | Summarize session | |
|
|
| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
|
|
| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
|
|
| `POST` | `/session/:id/message` | Send chat message | body matches [`ChatInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L358), returns <a href={typesUrl}><code>Message</code></a> |
|
|
| `POST` | `/session/:id/shell` | Run a shell command | body matches [`CommandInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L1007), returns <a href={typesUrl}><code>Message</code></a> |
|
|
| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` |
|
|
| `POST` | `/session/:id/unrevert` | Restore reverted messages | |
|
|
| `POST` | `/session/:id/permissions/:permissionID` | Respond to a permission request | body: `{ response }` |
|
|
|
|
---
|
|
|
|
### Files
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------- |
|
|
| `GET` | `/find?pattern=<pat>` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
|
|
| `GET` | `/find/file?query=<q>` | Find files by name | `string[]` (file paths) |
|
|
| `GET` | `/find/symbol?query=<q>` | Find workspace symbols | <a href={typesUrl}><code>Symbol[]</code></a> |
|
|
| `GET` | `/file?path=<path>` | Read a file | `{ type: "raw" \| "patch", content: string }` |
|
|
| `GET` | `/file/status` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> |
|
|
|
|
---
|
|
|
|
### Logging
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | ------ | ------------------------------------------------------------ | --------- |
|
|
| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` |
|
|
|
|
---
|
|
|
|
### Agents
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | -------- | ------------------------- | ------------------------------------------- |
|
|
| `GET` | `/agent` | List all available agents | <a href={typesUrl}><code>Agent[]</code></a> |
|
|
|
|
---
|
|
|
|
### TUI
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | ----------------------- | ------------------------------------------- | ---------------------- |
|
|
| `POST` | `/tui/append-prompt` | Append text to the prompt | `boolean` |
|
|
| `POST` | `/tui/open-help` | Open the help dialog | `boolean` |
|
|
| `POST` | `/tui/open-sessions` | Open the session selector | `boolean` |
|
|
| `POST` | `/tui/open-themes` | Open the theme selector | `boolean` |
|
|
| `POST` | `/tui/open-models` | Open the model selector | `boolean` |
|
|
| `POST` | `/tui/submit-prompt` | Submit the current prompt | `boolean` |
|
|
| `POST` | `/tui/clear-prompt` | Clear the prompt | `boolean` |
|
|
| `POST` | `/tui/execute-command` | Execute a command (`{ command }`) | `boolean` |
|
|
| `POST` | `/tui/show-toast` | Show toast (`{ title?, message, variant }`) | `boolean` |
|
|
| `GET` | `/tui/control/next` | Wait for the next control request | Control request object |
|
|
| `POST` | `/tui/control/response` | Respond to a control request (`{ body }`) | `boolean` |
|
|
|
|
---
|
|
|
|
### Auth
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | ----------- | --------------------------------------------------------------- | --------- |
|
|
| `PUT` | `/auth/:id` | Set authentication credentials. Body must match provider schema | `boolean` |
|
|
|
|
---
|
|
|
|
### Events
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | -------- | ----------------------------------------------------------------------------- | ------------------------- |
|
|
| `GET` | `/event` | Server-sent events stream. First event is `server.connected`, then bus events | Server-sent events stream |
|
|
|
|
---
|
|
|
|
### Docs
|
|
|
|
| Method | Path | Description | Response |
|
|
| ------ | ------ | ------------------------- | --------------------------- |
|
|
| `GET` | `/doc` | OpenAPI 3.1 specification | HTML page with OpenAPI spec |
|