OpenCode: External Server Backend via REST

The OpenCode backend connects to an external OpenCode server via REST API. It’s a lightweight option for teams that already run OpenCode as a separate service.

Overview

• Status: Beta
• Provider support: External server (model managed by OpenCode)
• Built-in tools: Server-managed (no PocketPaw-side tool definitions)
• MCP support: No
• Architecture: HTTP client — communicates with a running OpenCode server

Prerequisites

Install and start the OpenCode server:

# Install the OpenCode Go binary
go install github.com/opencode-ai/opencode@latest

# Start in server mode
opencode --server

The server runs on http://localhost:4096 by default.

Configuration

export POCKETPAW_AGENT_BACKEND="opencode"

Backend-Specific Settings

How It Works

1. PocketPaw creates a session via POST /session → receives a session ID
2. Messages are sent via POST /session/{id}/message
3. Responses stream as NDJSON (newline-delimited JSON)
4. PocketPaw parses the NDJSON stream into AgentEvent objects
5. A health check (GET /) verifies the server is reachable before each request

API Endpoints Used

When to Use

Choose OpenCode when:

• You already run OpenCode as a separate service
• You want a backend where the model and tools are managed externally
• You prefer a thin client architecture with PocketPaw as the frontend

Related