diff --git a/packages/www/openapi.json b/packages/www/openapi.json
index faaeb1a9bca..5ad90dab6b3 100644
--- a/packages/www/openapi.json
+++ b/packages/www/openapi.json
@@ -10614,6 +10614,104 @@
"summary": "Refresh worktrees"
}
},
+ "/api/workspace": {
+ "post": {
+ "tags": ["workspace"],
+ "operationId": "v2.workspace.create",
+ "parameters": [],
+ "security": [],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "string",
+ "pattern": "^wrk"
+ }
+ },
+ "required": ["data"],
+ "additionalProperties": false
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "InvalidRequestError",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "UnauthorizedError",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "ProviderNotFoundError",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ProviderNotFoundErrorEncoded"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "ConflictError",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ConflictErrorEncoded"
+ }
+ }
+ }
+ }
+ },
+ "description": "Create a logical workspace. A caller-supplied ID is idempotent when retried with the same provider; reusing it with another provider returns a conflict.",
+ "summary": "Create workspace",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "pattern": "^wrk"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "provider": {
+ "type": "string"
+ }
+ },
+ "required": ["provider"],
+ "additionalProperties": false
+ }
+ }
+ },
+ "required": true
+ }
+ }
+ },
"/api/workspace/{workspaceID}": {
"delete": {
"tags": ["workspace"],
diff --git a/packages/www/public/openapi.json b/packages/www/public/openapi.json
index faaeb1a9bca..5ad90dab6b3 100644
--- a/packages/www/public/openapi.json
+++ b/packages/www/public/openapi.json
@@ -10614,6 +10614,104 @@
"summary": "Refresh worktrees"
}
},
+ "/api/workspace": {
+ "post": {
+ "tags": ["workspace"],
+ "operationId": "v2.workspace.create",
+ "parameters": [],
+ "security": [],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "string",
+ "pattern": "^wrk"
+ }
+ },
+ "required": ["data"],
+ "additionalProperties": false
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "InvalidRequestError",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "UnauthorizedError",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "ProviderNotFoundError",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ProviderNotFoundErrorEncoded"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "ConflictError",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ConflictErrorEncoded"
+ }
+ }
+ }
+ }
+ },
+ "description": "Create a logical workspace. A caller-supplied ID is idempotent when retried with the same provider; reusing it with another provider returns a conflict.",
+ "summary": "Create workspace",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "pattern": "^wrk"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "provider": {
+ "type": "string"
+ }
+ },
+ "required": ["provider"],
+ "additionalProperties": false
+ }
+ }
+ },
+ "required": true
+ }
+ }
+ },
"/api/workspace/{workspaceID}": {
"delete": {
"tags": ["workspace"],
diff --git a/packages/www/src/docs/content/build/client/effect.mdx b/packages/www/src/docs/content/build/client/effect.mdx
new file mode 100644
index 00000000000..1d6d96b785e
--- /dev/null
+++ b/packages/www/src/docs/content/build/client/effect.mdx
@@ -0,0 +1,101 @@
+---
+title: "Effect"
+---
+
+`@opencode-ai/client/effect` is the Effect-native client for the OpenCode HTTP API. It returns typed Effects and Streams
+and decodes responses into OpenCode schema values.
+
+```sh
+bun add @opencode-ai/client@beta effect
+```
+
+## Create a client
+
+Create a client with the server URL, then call methods grouped by API resource.
+
+```ts
+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") }),
+ })
+ yield* client.session.prompt({
+ sessionID: session.id,
+ text: "Review the current changes",
+ })
+ return session
+})
+
+const session = await Effect.runPromise(program.pipe(Effect.provide(FetchHttpClient.layer)))
+```
+
+## Headers and requests
+
+Pass default headers to `OpenCode.make`. Each operation also accepts request options for cancellation or per-request
+headers.
+
+```ts
+const client = yield* OpenCode.make({
+ baseUrl: "https://opencode.example.com",
+ headers: { authorization: `Bearer ${process.env.OPENCODE_TOKEN}` },
+})
+
+const sessions = yield* client.session.list(undefined, {
+ signal: AbortSignal.timeout(10_000),
+})
+```
+
+## Stream events
+
+Streaming operations such as `event.subscribe()` and `session.log()` return Effect Streams.
+
+```ts
+import { Effect, Stream } from "effect"
+
+yield* client.event.subscribe().pipe(
+ Stream.runForEach((event) => Effect.logInfo("OpenCode event", { type: event.type })),
+)
+```
+
+## Local background service
+
+The Node-only `@opencode-ai/client/effect/service` entrypoint discovers, starts, authenticates, and stops the local
+background service as Effects.
+
+```sh
+bun add @effect/platform-node
+```
+
+Create an authenticated client for the ensured service.
+
+```ts
+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)),
+)
+```
+
+Discover without starting, or stop the exact registered service.
+
+```ts
+const endpoint = yield* Service.discover()
+yield* Service.stop()
+```
diff --git a/packages/www/src/docs/content/build/client.mdx b/packages/www/src/docs/content/build/client/index.mdx
similarity index 60%
rename from packages/www/src/docs/content/build/client.mdx
rename to packages/www/src/docs/content/build/client/index.mdx
index b741b5692a5..233c9ff07e4 100644
--- a/packages/www/src/docs/content/build/client.mdx
+++ b/packages/www/src/docs/content/build/client/index.mdx
@@ -1,5 +1,5 @@
---
-title: "Client"
+title: "JavaScript"
---
`@opencode-ai/client` is the generated TypeScript client for the OpenCode HTTP
@@ -110,68 +110,3 @@ const endpoint = await Service.ensure({
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.
-
-```sh
-bun add @opencode-ai/client@beta effect
-```
-
-### Create a client
-
-```ts
-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.
-
-```sh
-bun add @effect/platform-node
-```
-
-```ts
-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)),
-)
-```
diff --git a/packages/www/src/docs/content/build/sdk.mdx b/packages/www/src/docs/content/build/sdk.mdx
deleted file mode 100644
index 8d4f605057b..00000000000
--- a/packages/www/src/docs/content/build/sdk.mdx
+++ /dev/null
@@ -1,148 +0,0 @@
----
-title: "SDK"
----
-
-`@opencode-ai/sdk` hosts OpenCode directly inside your application. Unlike the
-[network client](/build/client), it assembles the OpenCode server and routes API
-calls through its HTTP router in memory. It opens no HTTP listener and adds no
-network hop between the client and server.
-
-
- The V2 SDK is beta. Install the current preview with `bun add @opencode-ai/sdk@dev`; its API may change before a
- stable release.
-
-
-## Create a host
-
-`OpenCode.create()` returns an explicitly owned host. Use `await using` to
-release its router, Location services, fibers, and scoped plugin registrations:
-
-```ts
-import { OpenCode } from "@opencode-ai/sdk"
-
-await using opencode = await OpenCode.create()
-const session = await opencode.sessions.create({
- location: { directory: "/workspace" },
-})
-
-await opencode.sessions.prompt({
- sessionID: session.id,
- text: "Review the current changes",
-})
-```
-
-Call `await opencode.close()` explicitly when explicit resource management is
-not available.
-
-The embedded host uses the same Promise values, declared errors, request
-options, and `AsyncIterable` streams as `@opencode-ai/client`. It exposes the
-full generated client and adds the convenience aliases `sessions` and `events`
-for the session and event groups.
-
-## Stream events
-
-```ts
-for await (const event of opencode.events.subscribe()) {
- console.log(event.type)
-}
-```
-
-Pass an `AbortSignal` through the generated request options, or leave an
-iteration to cancel its response body.
-
-## Register plugins
-
-Pass initial Promise plugins to `OpenCode.create()`. Embedded plugins use the
-same discovery and Location-scoped activation path as configured plugins.
-
-```ts
-const plugin = {
- id: "example",
- async setup(ctx) {
- await ctx.agent.transform((agents) => {
- // Modify the Location's agent catalog.
- })
- },
-}
-
-await using opencode = await OpenCode.create({ plugins: [plugin] })
-```
-
-Call `await opencode.plugin(plugin)` to register another plugin after startup.
-
-See the [Plugins guide](/build/plugins) for the plugin context and available
-hooks.
-
-## Workerd
-
-Use `@opencode-ai/sdk/workerd` inside a Cloudflare Durable Object. This profile
-uses the object's SQLite storage, persists durable events for eviction recovery,
-and replaces unavailable local filesystem and process services.
-
-Hold one host for the lifetime of the Durable Object instance instead of
-creating one for every request:
-
-```ts
-import { OpenCodeWorkerd } from "@opencode-ai/sdk/workerd"
-import myPlugin from "./my-plugin"
-
-export class OpenCodeDO {
- private readonly opencode: Promise
-
- constructor(state: DurableObjectState) {
- this.opencode = state.blockConcurrencyWhile(() =>
- OpenCodeWorkerd.create({
- storage: state.storage,
- config: { default_agent: "build" },
- plugins: [myPlugin],
- }),
- )
- }
-
- async fetch() {
- const opencode = await this.opencode
- return Response.json(await opencode.health.get())
- }
-}
-```
-
-`blockConcurrencyWhile` keeps every Durable Object event out until the host is
-ready and resets the object if initialization fails. The retained Promise gives
-request handlers direct access to the same host after startup. Configuration is
-a typed JavaScript object, and plugins are imported values bundled with the
-Worker.
-
-Wrangler selects OpenCode's Workerd-safe low-level implementations through the
-`workerd` package condition. Cloudflare may evict a Durable Object without
-running cleanup, so correctness does not depend on `close()` being called.
-
-## Effect
-
-Import the Effect-native API from `@opencode-ai/sdk/effect`. Closing its Effect
-Scope releases the embedded host:
-
-```ts
-import { AbsolutePath, Location, OpenCode } from "@opencode-ai/sdk/effect"
-import { Effect } from "effect"
-
-const program = Effect.scoped(
- Effect.gen(function* () {
- const opencode = yield* OpenCode.create()
- return yield* opencode.sessions.create({
- location: Location.Ref.make({
- directory: AbsolutePath.make("/workspace"),
- }),
- })
- }),
-)
-
-const session = await Effect.runPromise(program)
-```
-
-Effect applications can contribute plugins from ordinary registration layers.
-The registration layer may depend on `OpenCode.Service` and any other services
-needed to construct the plugin; `OpenCode.layer()` remains unaware of those
-features.
-
-Use `OpenCode.layer()` for dependency injection. The Effect-native Workerd
-entrypoint is `@opencode-ai/sdk/workerd/effect`.
diff --git a/packages/www/src/docs/content/build/sdk/cloudflare.mdx b/packages/www/src/docs/content/build/sdk/cloudflare.mdx
new file mode 100644
index 00000000000..61085ab9a9f
--- /dev/null
+++ b/packages/www/src/docs/content/build/sdk/cloudflare.mdx
@@ -0,0 +1,81 @@
+---
+title: "Cloudflare"
+---
+
+Use `@opencode-ai/sdk/workerd` inside a Cloudflare Durable Object. This profile uses the object's SQLite storage,
+persists durable events for eviction recovery, and replaces unavailable local filesystem and process services.
+
+```sh
+bun add @opencode-ai/sdk@dev
+```
+
+Hold one host for the lifetime of the Durable Object instance instead of creating one for every request.
+
+```ts
+import { OpenCodeWorkerd } from "@opencode-ai/sdk/workerd"
+import myPlugin from "./my-plugin"
+
+export class OpenCodeDO {
+ private readonly opencode: Promise
+
+ constructor(state: DurableObjectState) {
+ this.opencode = state.blockConcurrencyWhile(() =>
+ OpenCodeWorkerd.create({
+ storage: state.storage,
+ config: { default_agent: "build" },
+ plugins: [myPlugin],
+ }),
+ )
+ }
+
+ async fetch() {
+ const opencode = await this.opencode
+ return Response.json(await opencode.health.get())
+ }
+}
+```
+
+`blockConcurrencyWhile` keeps every Durable Object event out until the host is ready and resets the object if
+initialization fails. The retained Promise gives request handlers direct access to the same host after startup.
+
+```ts
+constructor(state: DurableObjectState) {
+ this.opencode = state.blockConcurrencyWhile(() =>
+ OpenCodeWorkerd.create({ storage: state.storage }),
+ )
+}
+```
+
+Configuration is a typed JavaScript object, and plugins are imported values bundled with the Worker.
+
+```ts
+await OpenCodeWorkerd.create({
+ storage: state.storage,
+ config: { default_agent: "build" },
+ plugins: [myPlugin],
+})
+```
+
+Wrangler selects OpenCode's Workerd-safe implementations through the `workerd` package condition. Cloudflare may evict
+a Durable Object without running cleanup, so correctness does not depend on `close()` being called.
+
+```jsonc title="wrangler.jsonc"
+{
+ "compatibility_flags": ["nodejs_compat"]
+}
+```
+
+## Effect
+
+Use the Effect-native entrypoint from `@opencode-ai/sdk/workerd/effect`.
+
+```ts
+import { OpenCodeWorkerd } from "@opencode-ai/sdk/workerd/effect"
+import { Effect } from "effect"
+
+const program = Effect.scoped(
+ Effect.gen(function* () {
+ return yield* OpenCodeWorkerd.create({ storage: state.storage })
+ }),
+)
+```
diff --git a/packages/www/src/docs/content/build/sdk/effect.mdx b/packages/www/src/docs/content/build/sdk/effect.mdx
new file mode 100644
index 00000000000..56377722ee0
--- /dev/null
+++ b/packages/www/src/docs/content/build/sdk/effect.mdx
@@ -0,0 +1,99 @@
+---
+title: "Effect"
+---
+
+`@opencode-ai/sdk/effect` is the Effect-native embedded SDK. Operations return typed Effects and Streams, and closing
+the owning Scope releases the router, Location services, fibers, and plugin registrations.
+
+```sh
+bun add @opencode-ai/sdk@dev effect
+```
+
+## Create a host
+
+Create the host inside `Effect.scoped`, then use its generated API groups or the `sessions` alias.
+
+```ts
+import { AbsolutePath, Location, OpenCode } from "@opencode-ai/sdk/effect"
+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") }),
+ })
+ yield* opencode.sessions.prompt({
+ sessionID: session.id,
+ text: "Review the current changes",
+ })
+ return session
+ }),
+)
+
+const session = await Effect.runPromise(program)
+```
+
+The embedded host uses the same schema values, declared errors, request options, and Streams as
+`@opencode-ai/client/effect`.
+
+```ts
+const health = yield* opencode.health.get()
+const sessions = yield* opencode.sessions.list()
+```
+
+## Stream events
+
+Streaming endpoints return Effect `Stream` values. Fork consumers in the host Scope when they should run in the
+background.
+
+```ts
+import { Effect, Stream } from "effect"
+
+yield* opencode.events.subscribe().pipe(
+ Stream.runForEach((event) => Effect.logInfo("OpenCode event", { type: event.type })),
+ Effect.forkScoped,
+)
+```
+
+## Register plugins
+
+Register Effect plugins through the embedded host. Their registrations remain scoped to the host.
+
+```ts
+import { Plugin } from "@opencode-ai/plugin/effect"
+import { Effect } from "effect"
+
+const plugin = Plugin.define({
+ id: "example",
+ effect: (ctx) =>
+ Effect.gen(function* () {
+ const storage = ctx.storage
+ yield* storage.set("embedded", true)
+ }),
+})
+
+yield* opencode.plugin(plugin)
+```
+
+See the [Effect plugins guide](/build/plugins/effect) for the complete plugin context.
+
+```ts
+yield* opencode.plugin.list()
+```
+
+## Layer
+
+Use `OpenCode.layer()` when the embedded host should be an application service.
+
+```ts
+import { OpenCode } from "@opencode-ai/sdk/effect"
+import { Effect } from "effect"
+
+const program = Effect.gen(function* () {
+ const opencode = yield* OpenCode.Service
+ return yield* opencode.health.get()
+})
+
+const health = await Effect.runPromise(program.pipe(Effect.provide(OpenCode.layer())))
+```
diff --git a/packages/www/src/docs/content/build/sdk/index.mdx b/packages/www/src/docs/content/build/sdk/index.mdx
new file mode 100644
index 00000000000..d27e72b28ea
--- /dev/null
+++ b/packages/www/src/docs/content/build/sdk/index.mdx
@@ -0,0 +1,74 @@
+---
+title: "Overview"
+---
+
+`@opencode-ai/sdk` hosts OpenCode directly inside your application. Unlike the
+[network client](/build/client), it assembles the OpenCode server and routes API
+calls through its HTTP router in memory. It opens no HTTP listener and adds no
+network hop between the client and server.
+
+
+ The V2 SDK is beta. Install the current preview with `bun add @opencode-ai/sdk@dev`; its API may change before a
+ stable release.
+
+
+## Create a host
+
+`OpenCode.create()` returns an explicitly owned host. Use `await using` to
+release its router, Location services, fibers, and scoped plugin registrations:
+
+```ts
+import { OpenCode } from "@opencode-ai/sdk"
+
+await using opencode = await OpenCode.create()
+const session = await opencode.sessions.create({
+ location: { directory: "/workspace" },
+})
+
+await opencode.sessions.prompt({
+ sessionID: session.id,
+ text: "Review the current changes",
+})
+```
+
+Call `await opencode.close()` explicitly when explicit resource management is
+not available.
+
+The embedded host uses the same Promise values, declared errors, request
+options, and `AsyncIterable` streams as `@opencode-ai/client`. It exposes the
+full generated client and adds the convenience aliases `sessions` and `events`
+for the session and event groups.
+
+## Stream events
+
+```ts
+for await (const event of opencode.events.subscribe()) {
+ console.log(event.type)
+}
+```
+
+Pass an `AbortSignal` through the generated request options, or leave an
+iteration to cancel its response body.
+
+## Register plugins
+
+Pass initial Promise plugins to `OpenCode.create()`. Embedded plugins use the
+same discovery and Location-scoped activation path as configured plugins.
+
+```ts
+const plugin = {
+ id: "example",
+ async setup(ctx) {
+ await ctx.agent.transform((agents) => {
+ // Modify the Location's agent catalog.
+ })
+ },
+}
+
+await using opencode = await OpenCode.create({ plugins: [plugin] })
+```
+
+Call `await opencode.plugin(plugin)` to register another plugin after startup.
+
+See the [Plugins guide](/build/plugins) for the plugin context and available
+hooks.
diff --git a/packages/www/src/docs/lib/navigation.ts b/packages/www/src/docs/lib/navigation.ts
index 2c5587c4ee8..5e42664d587 100644
--- a/packages/www/src/docs/lib/navigation.ts
+++ b/packages/www/src/docs/lib/navigation.ts
@@ -99,9 +99,18 @@ export const docsSections: DocsSection[] = [
],
},
{
+ title: "Client",
items: [
- { title: "Client", slug: "build/client" },
- { title: "SDK", slug: "build/sdk" },
+ { title: "JavaScript", slug: "build/client" },
+ { title: "Effect", slug: "build/client/effect" },
+ ],
+ },
+ {
+ title: "SDK",
+ items: [
+ { title: "Overview", slug: "build/sdk" },
+ { title: "Effect", slug: "build/sdk/effect" },
+ { title: "Cloudflare", slug: "build/sdk/cloudflare" },
],
},
],