Calling OpenCode from Another Harness: CLI run, serve, SDK, and ACP

Running opencode in the terminal is already powerful, but many workflows call for automation: triggering it from a CI pipeline, embedding it in another application, or using it inside an editor.

OpenCode supports four integration patterns for this purpose, and all of them accept -m for model selection and –dir for the working directory.

1. CLI run — The simplest non-interactive mode

Best for shell scripts, cron jobs, and CI/CD pipelines where you just want to fire a prompt and get the result.

opencode run "Explain how closures work in JavaScript" -m anthropic/claude-sonnet-4-5 --dir /myproject

opencode run executes the prompt, streams the AI response to stdout, and exits. The return value is the text output.

Key options

Use cases

• CI/CD pipeline code generation and review
• Batch processing (daily reports, etc.)
• Cron-based scheduled tasks
• One-shot scripting tasks

2. serve + REST API — Persistent server mode

Start an HTTP server and interact with OpenCode through a REST API.

# Start the server (keep running in background)
opencode serve --port 4096

The server exposes endpoints at http://localhost:4096, with an OpenAPI 3.1 spec available at /doc.

Key endpoints

# Create a session
curl -X POST http://localhost:4096/session -H "Content-Type: application/json" -d '{"title":"test"}'

# Send a message and wait for response
curl -X POST http://localhost:4096/session/{id}/message -H "Content-Type: application/json" `
  -d '{"parts":[{"type":"text","text":"Hello"}],"model":{"providerID":"anthropic","modelID":"claude-sonnet-4-5"}}'

Security

Set OPENCODE_SERVER_PASSWORD to enable HTTP Basic auth. Essential for production deployments.

Use cases

• Web application backends
• Chatbot server-side logic
• Multi-session management dashboards
• Centralized remote management

3. JS/TS SDK — The most full-featured

The official @opencode-ai/sdk package provides type-safe programmatic access from Node.js.

npm install @opencode-ai/sdk

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

const { client } = await createOpencode({
  config: { model: "anthropic/claude-sonnet-4-5" }
});

const session = await client.session.create({
  body: { title: "Code review" }
});

const result = await client.session.prompt({
  path: { id: session.data.id! },
  body: {
    parts: [{ type: "text", text: "Review src/index.ts for bugs" }]
  }
});

console.log(result.data.info.title);

Structured output

You can request validated JSON output by specifying a JSON schema:

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "List all bugs in this code" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          bugs: {
            type: "array",
            items: {
              type: "object",
              properties: {
                file: { type: "string" },
                line: { type: "number" },
                description: { type: "string" },
                severity: { type: "string", enum: ["low", "medium", "high"] }
              },
              required: ["file", "description", "severity"]
            }
          }
        },
        required: ["bugs"]
      }
    }
  }
});

Use cases

• Deep Node.js application integration
• Structured data extraction and analysis
• Multi-agent orchestration
• Custom tool integration

4. ACP (Agent Client Protocol) — Editor and stdin integration

ACP is a standardized protocol for communication between editors and AI agents. Running opencode acp starts a JSON-RPC session over stdin/stdout.

opencode acp --cwd /path/to/project

Editor configuration examples

Zed (~/.config/zed/settings.json):

{
  "agent_servers": {
    "OpenCode": {
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

JetBrains IDE (acp.json):

{
  "agent_servers": {
    "OpenCode": {
      "command": "/absolute/path/bin/opencode",
      "args": ["acp"]
    }
  }
}

Use cases

• Zed, JetBrains, Neovim editor integration
• Custom IDE plugin development
• Inter-process communication (IPC) tool integration

Comparison summary