Client

Connect an application to the OpenCode HTTP API.

@opencode-ai/client is the generated TypeScript client for the OpenCode HTTP API. Use it when your application connects to an OpenCode server over the network. Its types and methods are generated from the same contract as the API reference.

Install

bun add @opencode-ai/client@next

Create a client

Create a client with the server URL, then call methods grouped by API resource:

import { OpenCode } from "@opencode-ai/client"

const client = OpenCode.make({
  baseUrl: "http://localhost:4096",
})

const session = await client.session.create({
  location: { directory: "/workspace" },
})

await client.session.prompt({
  sessionID: session.id,
  text: "Review the current changes",
})

Headers and requests

Pass default authentication or application headers to OpenCode.make with headers. You can also supply a custom fetch implementation. Each operation accepts request options as its final argument for an AbortSignal or per-request headers.

const client = OpenCode.make({
  baseUrl: "https://opencode.example.com",
  headers: {
    authorization: `Bearer ${process.env.OPENCODE_TOKEN}`,
  },
})

await client.session.list(undefined, {
  signal: AbortSignal.timeout(10_000),
})

Stream events

Streaming endpoints return async iterables:

for await (const event of client.event.subscribe()) {
  console.log(event.type)
}

Local background service

The main client entrypoints are browser-compatible and do not include local process management. In a Node application, import the native Promise service API from @opencode-ai/client/service.

• Service.discover() returns a healthy registered endpoint without starting a process.
• Service.ensure() returns a compatible service, starting one when needed.
• Service.stop() stops the exact registered service instance.
• Service.headers(endpoint) creates the authentication headers for a client.

import { OpenCode } from "@opencode-ai/client"
import { Service } from "@opencode-ai/client/service"

const endpoint = await Service.ensure()
const client = OpenCode.make({
  baseUrl: endpoint.url,
  headers: Service.headers(endpoint),
})

const health = await client.health.get()

Service.ensure() accepts an optional registration file, required version, service command, and onStart callback:

const endpoint = await Service.ensure({
  file: "/var/run/opencode/service.json",
  version: "2.0.0",
  command: ["opencode", "serve", "--service"],
  onStart(reason, previousVersion) {
    console.log(reason, previousVersion)
  },
})

Omit these options to use the standard registration path and opencode serve --service command.

Effect

OpenCode provides a first-class Effect client through the @opencode-ai/client/effect entrypoint. It returns typed Effects and Streams and decodes responses into OpenCode schema values.

bun add @opencode-ai/client@next effect

Create a client

import { AbsolutePath, Location, OpenCode } from "@opencode-ai/client/effect"
import { Effect } from "effect"
import { FetchHttpClient } from "effect/unstable/http"

const program = Effect.gen(function* () {
  const client = yield* OpenCode.make({ baseUrl: "http://localhost:4096" })
  const session = yield* client.session.create({
    location: Location.Ref.make({
      directory: AbsolutePath.make("/workspace"),
    }),
  })

  return yield* client.session.get({ sessionID: session.id })
})

const session = await Effect.runPromise(
  program.pipe(Effect.provide(FetchHttpClient.layer)),
)

Streaming operations, including client.event.subscribe() and client.session.log(...), return Effect Stream values.

Local background service

The Node-only @opencode-ai/client/effect/service entrypoint exposes the same operations as Effect values. Add @effect/platform-node and provide its filesystem layer when running them.

bun add @effect/platform-node

import { NodeFileSystem } from "@effect/platform-node"
import { OpenCode } from "@opencode-ai/client/effect"
import { Service } from "@opencode-ai/client/effect/service"
import { Effect } from "effect"
import { FetchHttpClient } from "effect/unstable/http"

const program = Effect.gen(function* () {
  const endpoint = yield* Service.ensure()
  const client = yield* OpenCode.make({
    baseUrl: endpoint.url,
    headers: Service.headers(endpoint),
  })
  return yield* client.health.get()
})

const health = await Effect.runPromise(
  program.pipe(
    Effect.provide(FetchHttpClient.layer),
    Effect.provide(NodeFileSystem.layer),
  ),
)