Skip to main content

​
Overview

The serve command starts a headless HTTP server that provides API access to OpenCode functionality without the TUI interface. This is ideal for:
  • Programmatic API access
  • Running on remote servers
  • Integrating with other tools
  • Avoiding MCP server cold boot times

​
Usage

opencode serve
The server starts on 127.0.0.1:0 (random port) by default. Use flags to customize the network settings.

​
Options

​
--port
number
default:"0"
Port to listen on. Default is 0 (random available port).
​
--hostname
string
default:"127.0.0.1"
Hostname to listen on. Use 0.0.0.0 to allow external connections.
​
--mdns
boolean
default:"false"
Enable mDNS service discovery. When enabled, defaults hostname to 0.0.0.0.
​
--mdns-domain
string
default:"opencode.local"
Custom domain name for mDNS service.
​
--cors
string[]
default:"[]"
Additional browser origins to allow for CORS. Can be specified multiple times.

​
Examples

​
Basic Server

Start a local server on a random port: 
opencode serve

​
Fixed Port

Start server on port 4096: 
opencode serve --port 4096

​
Network-Accessible Server

Allow connections from other machines: 
opencode serve --port 4096 --hostname 0.0.0.0

​
With mDNS Discovery

Enable service discovery on local network: 
opencode serve --mdns

​
Custom CORS Origins

Allow specific origins for web access: 
opencode serve --cors https://example.com --cors https://app.example.com

​
Authentication

By default, the server runs without authentication. Always set OPENCODE_SERVER_PASSWORD in production environments.
Enable HTTP basic authentication by setting environment variables: 
export OPENCODE_SERVER_PASSWORD="your-secure-password"
opencode serve
Optionally customize the username (defaults to opencode): 
export OPENCODE_SERVER_USERNAME="admin"
export OPENCODE_SERVER_PASSWORD="your-secure-password"
opencode serve

​
Using with Run Command

You can attach to a running serve instance to avoid MCP server cold boot times: 
# Terminal 1: Start the server
opencode serve --port 4096

# Terminal 2: Run commands that attach to it
opencode run --attach http://localhost:4096 "Explain async/await"
opencode run --attach http://localhost:4096 "Fix the bug in app.ts"

​
API Access

The server exposes a full HTTP API. See the Server API documentation for details on available endpoints. Basic example using the JavaScript SDK: 
import { createOpencodeClient } from '@opencode-ai/sdk/v2'

const client = createOpencodeClient({
  baseUrl: 'http://localhost:4096',
  auth: {
    username: 'opencode',
    password: process.env.OPENCODE_SERVER_PASSWORD
  }
})

// Create a session and send a message
const session = await client.session.create({})
await client.session.prompt({
  sessionID: session.data.id,
  parts: [{ type: 'text', text: 'Hello!' }]
})

​
Configuration

You can set default server options in your global configuration file (~/.config/opencode/config.json): 
{
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1",
    "mdns": false,
    "mdnsDomain": "opencode.local",
    "cors": ["https://example.com"]
  }
}
Command-line flags always override configuration file settings.

web

Start server with web interface

attach

Attach TUI to running server

run

Run commands non-interactively

Server API

View full HTTP API documentation