opencode-server-api

OpenCode Server API

This skill gives you access to the OpenCode server REST API for self-introspection — checking your own health, session state, message history, todos, configuration, skills, MCP status, and performing lightweight config updates.

Authentication

The server port is provided in your system prompt inside the <server-access> block. The basic-auth password is already present in your shell environment as OPENCODE_SERVER_PASSWORD — your shell expands it locally when you run a command. All requests require HTTP basic auth:

curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/<endpoint>

Replace $PORT with the port from your system prompt. Use $OPENCODE_SERVER_PASSWORD exactly as written (PowerShell: $env:OPENCODE_SERVER_PASSWORD).

NEVER print, echo, log, or write the password's value anywhere — not to the chat, not to files, not to command output. Only reference it as a shell variable inside commands.

IMPORTANT: Fetch the API Spec First

Before calling ANY specific endpoint, you MUST first fetch and parse the live OpenAPI specification. The spec is the source of truth for all available endpoints, request/response schemas, and query parameters. The endpoint summaries in this skill are a convenient reference, but the server's own spec may be newer or more complete.

curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/doc

This returns the full OpenAPI JSON spec. Parse it to understand the exact request format, required parameters, and response shapes before invoking any endpoint. Do not guess or rely solely on the examples below — always verify against /doc first.

Endpoint Reference

GET /global/health

Check server health and get the OpenCode version.

curl -s -u "opencode:$OPENCODE_SERVER_PASSWORD" http://localhost:$PORT/global/health

Response:

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

GET /config

Read the current server configuration (model, agents, permissions, MCP servers, etc.).