SDK and Embedded Hosting

OpenCode v2 offers two ways to integrate programmatically: the network client and the embedded SDK.

Network Client

@opencode-ai/client is a generated TypeScript client for the OpenCode HTTP API. Use it when connecting to a running OpenCode server over the network.

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

const client = OpenCode.make({
  baseUrl: "http://localhost:4096",
  headers: { Authorization: `Bearer ${token}` },
})

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

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

Warning: The V2 API and client are currently in beta. Method names, inputs, and outputs may change before the stable release.

Effect-Native Client

For Effect applications, use @opencode-ai/client/effect:

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),
  ),
)

Embedded SDK

@opencode-ai/sdk-next hosts OpenCode in-process. It assembles the server and routes API calls through the HTTP router in memory - no HTTP listener, no network hop.

Warning: The V2 SDK is beta and currently private to the OpenCode workspace. It is not published for external installation yet.

Create a Host

import { AbsolutePath, Location, OpenCode } from "@opencode-ai/sdk-next"
import { Effect } from "effect"

const program = Effect.scoped(
  Effect.gen(function* () {
    const opencode = yield* OpenCode.create()

    const session = yield* opencode.sessions.create({
      location: Location.Ref.make({
        directory: AbsolutePath.make("/workspace"),
      }),
    })

    return yield* opencode.sessions.get({ sessionID: session.id })
  }),
)

const session = await Effect.runPromise(program)

Use as a Service

import { OpenCode } from "@opencode-ai/sdk-next"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const opencode = yield* OpenCode.Service
  return yield* opencode.sessions.active()
})

const active = await Effect.runPromise(
  program.pipe(Effect.provide(OpenCode.layer)),
)

Register Plugins

const opencode = yield* OpenCode.create()
yield* opencode.plugin(myPlugin)

Embedded plugins use the same discovery and location-scoped activation path as configured plugins.