Opencode Server

OpenCode Server

📚 Official Docs: For the latest information, always refer to the official documentation: https://opencode.ai/docs/server/

OpenCode exposes a headless HTTP server that implements a full REST API and publishes an OpenAPI 3.1 specification. The TUI is a client that talks to this server. The server enables multiple clients (TUI, web, IDE plugins, custom integrations) to control OpenCode programmatically.

Usage

Start a standalone HTTP server:

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

Flags

The --cors flag can be passed multiple times:

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

When you run opencode normally (without serve), it starts both a TUI and an internal server. The TUI is the client that talks to this server. Running opencode serve starts a standalone headless server without launching the TUI.

Authentication

Protect the server with HTTP basic auth using environment variables:

OPENCODE_SERVER_PASSWORD=your-password opencode serve

Authentication applies to both opencode serve and opencode web. If OPENCODE_SERVER_PASSWORD is not set, the server is unsecured — acceptable for local use, but should be set for network access.

Architecture

The architecture separates the TUI (client) from the server:

• Server — Headless HTTP process that exposes the full OpenCode API.
• TUI — A client that connects to the server and renders the terminal UI.
• Web — A browser-based client that connects to the server.
• SDK — A type-safe JavaScript/TypeScript client generated from the server's OpenAPI spec.

The server publishes an OpenAPI 3.1 specification at /doc. The SDK (@opencode-ai/sdk) is generated from this spec, providing fully typed request/response objects for every endpoint.

This separation allows multiple clients to attach simultaneously — a terminal TUI, a browser tab, and custom integrations can all share the same sessions and state.

Connect to an Existing Server

When you start the TUI, it randomly assigns a port and hostname. You can instead pass --hostname and --port flags to control the binding:

opencode --hostname 127.0.0.1 --port 4096

Then connect other clients to the same server:

# Connect the TUI to an existing server
opencode attach http://localhost:4096

# Or use the SDK
import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({ baseUrl: "http://localhost:4096" })

TUI Endpoint for IDE Plugins

The /tui endpoint allows IDE plugins to drive the TUI through the server — prefill prompts, submit prompts, execute commands, open dialogs, and show notifications. This is the primary integration point for OpenCode IDE plugins.

OpenAPI Spec

The server publishes an OpenAPI 3.1 spec at:

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

For example: http://localhost:4096/doc

Use the spec to:

• Generate clients in any language
• Inspect request/response types in a Swagger explorer
• Build custom integrations with full type safety

API Reference

All endpoints are relative to http://<hostname>:<port>.

Global

GET /global/health

Returns server health status and version string. Useful for health checks and monitoring.

{ "healthy": true, "version": "1.0.0" }

GET /global/event

Server-Sent Events stream of global events. First event is server.connected, then bus events stream continuously.

Project

The Project type contains project metadata including name, path, and configuration information.

Path & VCS

/path returns the current working directory and project root. /vcs returns version control system information (branch, status, etc.).

Instance

Shuts down the current OpenCode instance. Use with caution — this terminates the server process.

Config

GET /config

Returns the full configuration object for the current instance.

PATCH /config

Partially updates the configuration. Only the provided fields are modified; omitted fields remain unchanged.

GET /config/providers

Returns all configured providers and their default model mappings. The default map keys are provider IDs and values are model IDs.

Provider

GET /provider

Returns:

• all — All configured providers
• default — Default model for each provider
• connected — List of connected (authenticated) provider IDs

GET /provider/auth

Returns available authentication methods for each provider. Useful for building OAuth flows in custom clients.

POST /provider/{id}/oauth/authorize

Initiates an OAuth authorization flow for the specified provider. Returns authorization URL and state.

POST /provider/{id}/oauth/callback

Handles the OAuth callback after the user authorizes. Returns true if authentication succeeded.

Sessions

POST /session

Create a new session. Body:

{
  "parentID": "optional-parent-session-id",
  "title": "Optional session title"
}

Returns the created Session object.

PATCH /session/:id

Update session properties. Body:

{
  "title": "New title"
}

POST /session/:id/init

Analyze the application and generate an AGENTS.md file. Body:

{
  "messageID": "message-to-respond-to",
  "providerID": "anthropic",
  "modelID": "claude-3-5-sonnet-20241022"
}

POST /session/:id/fork

Fork an existing session, optionally at a specific message. Body:

{
  "messageID": "optional-message-id-to-fork-at"
}

Returns a new Session object that is a copy of the original.

POST /session/:id/share

Makes the session publicly accessible. Returns the updated session with sharing metadata.

DELETE /session/:id/share

Revokes public sharing for the session.

GET /session/:id/diff

Get file changes for the session. Optional query parameter messageID to get diff up to a specific message.

Returns FileDiff[] — an array of file diffs showing added, removed, and modified content.

POST /session/:id/summarize

Generate a summary of the session. Body:

{
  "providerID": "anthropic",
  "modelID": "claude-3-5-sonnet-20241022"
}

POST /session/:id/revert

Revert a specific message (and optionally a specific part within it). Body:

{
  "messageID": "message-to-revert",
  "partID": "optional-specific-part"
}

POST /session/:id/unrevert

Restores all reverted messages in the session. No body required.

POST /session/:id/permissions/:permissionID

Respond to a pending permission request. Body:

{
  "response": "allow",
  "remember": true
}

Messages

GET /session/:id/message

List messages in a session. Optional query parameter limit to restrict the number of messages returned.

Each message contains:

• info — The Message object (role, content, metadata)
• parts — Array of Part objects (text chunks, tool calls, tool results)

POST /session/:id/message

Send a message and wait for the AI response. Body:

{
  "messageID": "optional-message-id",
  "model": { "providerID": "anthropic", "modelID": "claude-3-5-sonnet-20241022" },
  "agent": "optional-agent-name",
  "noReply": false,
  "system": "optional-system-prompt",
  "tools": ["optional-tool-whitelist"],
  "parts": [
    { "type": "text", "text": "Hello!" }
  ]
}

• noReply: true — Injects context without triggering an AI response (returns a UserMessage)
• model — Optionally override the model for this message
• agent — Optionally specify an agent
• tools — Optionally restrict which tools the model can use
• parts — Message content parts (text, images, etc.)

POST /session/:id/prompt_async

Same body as /session/:id/message but returns immediately with 204 No Content. The response is processed asynchronously; listen to events to know when it completes.

POST /session/:id/command

Execute a slash command. Body:

{
  "messageID": "optional-message-id",
  "agent": "optional-agent",
  "model": { "providerID": "...", "modelID": "..." },
  "command": "/compact",
  "arguments": "optional arguments string"
}

POST /session/:id/shell

Run a shell command within the session context. Body:

{
  "agent": "optional-agent",
  "model": { "providerID": "...", "modelID": "..." },
  "command": "ls -la"
}

Returns the assistant message with tool call results.

DELETE /session/:id/message/:messageID

Delete a specific message from a session. This permanently removes the message and all its parts.

DELETE /session/:id/message/:messageID/part/:partID

Delete a specific part within a message. Removes only the specified part (e.g., a single tool call or text chunk).

PATCH /session/:id/message/:messageID/part/:partID

Update a specific message part. Body:

{
  "text": "Updated text content"
}

Allows modifying the content of a specific part within a message.

Commands

Returns all registered slash commands (e.g., /compact, /init, /clear).

Files

GET /find?pattern=<pat>

Search for text in files using a regex pattern. Returns an array of match objects:

[
  {
    "path": "src/index.ts",
    "lines": ["matching line content"],
    "line_number": 42,
    "absolute_offset": 1234,
    "submatches": [{ "match": "matched text", "start": 0, "end": 12 }]
  }
]

GET /find/file?query=<q>

Find files and directories by name using fuzzy matching.

Query Parameters:

Returns string[] — array of matching file/directory paths.

GET /find/symbol?query=<q>

Find workspace symbols (functions, classes, variables, etc.).

GET /file?path=<path>

List files and directories at the given path. Returns FileNode[] with file metadata.

GET /file/content?path=<p>

Read the content of a file. Returns FileContent with the file's raw content.

GET /file/status

Get status for all tracked (VCS-tracked) files. Returns File[] with file status information.

Tools (Experimental)

GET /experimental/tool

Query parameters:

• provider — Provider ID
• model — Model ID

Returns the full tool definitions with JSON schemas for the specified model, showing which tools are available and their argument schemas.

LSP, Formatters & MCP

GET /lsp

Returns the status of all configured LSP (Language Server Protocol) servers — running, stopped, error states.

GET /formatter

Returns the status of all configured code formatters.

GET /mcp

Returns the status of all configured MCP (Model Context Protocol) servers. Each entry is keyed by server name.

POST /mcp

Dynamically add an MCP server at runtime. Body:

{
  "name": "my-mcp-server",
  "config": {
    "command": "node",
    "args": ["server.js"]
  }
}

Agents

Returns all registered agents (built-in and custom) with their configurations.

Logging

Body:

{
  "service": "my-app",
  "level": "info",
  "message": "Operation completed",
  "extra": { "key": "value" }
}

Log levels: debug, info, warn, error.

TUI Control

These endpoints control the Terminal UI through the server. Used primarily by IDE plugins.

POST /tui/append-prompt

Body: { "text": "text to append" }

Appends text to the current prompt input without submitting.

POST /tui/execute-command

Body: { "command": "/compact" }

Executes a slash command through the TUI.

POST /tui/show-toast

Body: { "title": "Optional title", "message": "Toast message", "variant": "success" }

Variants: info, success, warning, error.

GET /tui/control/next

Long-polling endpoint that waits for the next control request from the TUI. Returns a control request object that represents a pending user interaction (e.g., permission prompt, input request).

POST /tui/control/response

Body: { "body": "response content" }

Responds to a pending control request obtained from /tui/control/next.

PTY (Terminal Pseudoterminal)

POST /pty

Create a new PTY session. Body:

{
  "shell": "/bin/zsh",
  "cols": 80,
  "rows": 24
}

GET /pty/:ptyID/connect

Server-Sent Events stream for bidirectional terminal I/O. Use the connection token from /pty/:ptyID/connect-token to authenticate.

POST /pty/:ptyID/connect-token

Generate a short-lived token for connecting to the PTY session. Returns a token object with expiry.

Permission

GET /permission

Returns all pending permission requests that require user approval (e.g., file writes, shell commands).

POST /permission/:requestID/reply

Reply to a pending permission request. Body:

{
  "response": "allow",
  "remember": true
}

Response values: allow, deny. The remember flag persists the decision for future requests of the same type.

Question

GET /question

Returns all pending questions from the AI that require user input.

POST /question/:requestID/reply

Reply to a pending question. Body:

{
  "response": "Your answer here"
}

POST /question/:requestID/reject

Reject or dismiss a pending question without answering.

Skill

Returns all registered skills with their metadata and descriptions.

Sync

POST /sync/history

Synchronize conversation history between clients. Used when a new client connects and needs to catch up.

POST /sync/replay

Replay stored events to bring a client up to date with the current server state.

POST /sync/steal

Take control of a session from another connected client. The other client receives a disconnect notification.

Workspace (Experimental)

POST /experimental/workspace

Create a new workspace. Body:

{
  "name": "my-workspace",
  "path": "/path/to/workspace"
}

POST /experimental/workspace/warp

Navigate to a specific location within the workspace. Body:

{
  "path": "src/index.ts",
  "line": 42
}

Worktree (Experimental)

POST /experimental/worktree

Create a new git worktree. Body:

{
  "branch": "feature/my-branch",
  "path": "/path/to/worktree"
}

POST /experimental/worktree/reset

Reset a worktree to a clean state, discarding all uncommitted changes.

Auth

Body must match the provider's auth schema. Example:

{
  "type": "api",
  "key": "your-api-key"
}

For OAuth providers, use the /provider/{id}/oauth/authorize and /provider/{id}/oauth/callback endpoints instead.

Events

The SSE stream sends events in real-time. The first event is server.connected, followed by bus events as they occur.

Event types include:

• server.connected — Server connection established
• session.created — New session created
• session.updated — Session properties changed
• session.idle — AI finished responding
• session.error — Session encountered an error
• session.compacted — Context was compacted
• session.deleted — Session was deleted
• message.updated — Message was updated
• message.removed — Message was removed
• message.part.updated — Message part (text chunk, tool call) updated
• message.part.removed — Message part removed
• file.edited — File was edited
• permission.asked — Permission request
• permission.replied — Permission response
• lsp.updated — LSP state change
• todo.updated — Todo item changed
• command.executed — Command was executed

Connect to the SSE stream:

curl -N http://localhost:4096/event

Docs

Returns an HTML page with the full OpenAPI 3.1 specification rendered in a Swagger UI explorer. Accessible at http://localhost:4096/doc.

Web Interface

Start the browser-based web interface:

opencode web [--port <number>] [--hostname <string>] [--mdns] [--mdns-domain <string>] [--cors <origin>]

Configuration

All opencode serve flags apply to opencode web as well:

# Fixed port
opencode web --port 4096

# Accessible on network
opencode web --hostname 0.0.0.0

# With authentication
OPENCODE_SERVER_PASSWORD=secret opencode web

# With mDNS
opencode web --mdns

# With custom mDNS domain
opencode web --mdns --mdns-domain myproject.local

When using 0.0.0.0, OpenCode displays both local and network addresses:

Local access:     http://localhost:4096
Network access:   http://192.168.1.100:4096

Config File

Server settings can also be configured in opencode.json:

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["https://example.com"]
  }
}

Command line flags take precedence over config file settings.

Attaching a Terminal

Attach a terminal TUI to a running web server:

# Start the web server
opencode web --port 4096

# In another terminal, attach the TUI
opencode attach http://localhost:4096

Both the web interface and terminal share the same sessions and state. You can use both simultaneously.

Web Interface Features

• Sessions — View and manage sessions from the homepage. See active sessions and start new ones.
• Server Status — Click "See Servers" to view connected servers and their status.

mDNS Discovery

Enable mDNS to advertise the server on the local network:

opencode serve --mdns
# or
opencode web --mdns

This automatically sets the hostname to 0.0.0.0 and advertises the server as opencode.local.

Custom Domain Names

Run multiple instances on the same network by customizing the mDNS domain:

opencode serve --mdns --mdns-domain project-a.local
opencode serve --mdns --mdns-domain project-b.local

Clients can then discover instances by browsing for _opencode._tcp services, or connect directly:

opencode attach http://project-a.local:4096

How mDNS Works

• The server registers a DNS-SD service under _opencode._tcp
• Default instance name: opencode (becomes opencode.local)
• Custom domain names: --mdns-domain myapp.local becomes the service address
• Clients on the same network can discover the server without knowing its IP address

SDK Integration

The OpenCode JS/TS SDK (@opencode-ai/sdk) is generated from the server's OpenAPI spec. It provides two modes:

Full Lifecycle (Server + Client)

import { createOpencode } from "@opencode-ai/sdk"

const { client, server } = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  timeout: 5000,
  config: { model: "anthropic/claude-3-5-sonnet-20241022" },
})

console.log(`Server running at ${server.url}`)

// Use the client...

server.close()

Client Only

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
  throwOnError: true,
  responseStyle: "data",
})

Key SDK Methods

See the SDK skill for full SDK documentation.

Complete Workflow Example

1. Start the server

opencode serve --port 4096

2. Check health

curl http://localhost:4096/global/health
# {"healthy":true,"version":"1.0.0"}

3. Create a session

curl -X POST http://localhost:4096/session \
  -H "Content-Type: application/json" \
  -d '{"title": "Code Review"}'

4. Send a prompt

curl -X POST http://localhost:4096/session/<session-id>/message \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [{"type": "text", "text": "Review this codebase for issues"}],
    "model": {"providerID": "anthropic", "modelID": "claude-3-5-sonnet-20241022"}
  }'

5. Stream events

curl -N http://localhost:4096/event

6. View the spec

Open http://localhost:4096/doc in a browser.

Troubleshooting

Server won't start

• Check if the port is already in use: lsof -i :4096
• Try a different port: opencode serve --port 5000

Authentication fails

• Ensure OPENCODE_SERVER_PASSWORD is set before starting the server
• The default username is opencode; override with OPENCODE_SERVER_USERNAME
• Both serve and web commands use the same auth environment variables

CORS errors in browser

• Add the frontend origin to --cors: opencode serve --cors http://localhost:5173
• Multiple --cors flags are allowed
• The server automatically includes localhost origins for development

mDNS not discoverable

• Ensure --mdns flag is passed
• Check that the hostname is 0.0.0.0 (mDNS sets this automatically)
• Verify mDNS is enabled on the client machine
• Try connecting directly by IP instead of .local domain

TUI connection refused

• Verify the server is running: curl http://localhost:4096/global/health
• Check the correct port and hostname
• Use opencode attach http://localhost:4096 to connect the TUI

SDK types not available

• Install the SDK: npm install @opencode-ai/sdk
• Types are auto-generated from the OpenAPI spec at /doc
• Import types: import type { Session, Message } from "@opencode-ai/sdk"