Skip to content

Clients

Opencode 

Opencode(
    base_url: str | URL | None = None,
    *,
    password: str | None = None,
    username: str = DEFAULT_USERNAME,
    directory: str | PathLike[str] | None = None,
    timeout: Timeout = DEFAULT_TIMEOUT,
    max_retries: int = DEFAULT_MAX_RETRIES,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    http_client: Client | None = None,
    transport: BaseTransport | None = None,
)

Synchronous client for an OpenCode server.

Parameters:

Name Type Description Default
base_url str | URL | None

Server URL, for example http://127.0.0.1:4096. Defaults to OPENCODE_BASE_URL.

 None
password str | None

Server password. Defaults to OPENCODE_PASSWORD, then OPENCODE_SERVER_PASSWORD. Pass "" to send no credentials.

 None
username str

Basic auth user name. The OpenCode server uses opencode.

 DEFAULT_USERNAME
directory str | PathLike[str] | None

Default project directory. Sent as the location of every request that accepts one, unless the call passes its own location.

 None
timeout Timeout

Default timeout in seconds, or an httpx.Timeout. Event streams only apply the connect timeout.

 DEFAULT_TIMEOUT
max_retries int

Retries for connection failures and transient statuses. Requests that may have changed state on the server are only retried when the server refused them before acting (429 and 503).

 DEFAULT_MAX_RETRIES
default_headers Mapping[str, str] | None

Headers sent with every request.

 None
default_query Mapping[str, object] | None

Query parameters sent with every request.

 None
http_client Client | None

A preconfigured httpx.Client (proxies, custom transports, event hooks). The caller keeps ownership and must close it.

 None
transport BaseTransport | None

An httpx transport for the client's own connection pool, such as :class:opencode.testing.FakeServer. Cannot be combined with http_client.

 None

Example::

from opencode import Opencode

with Opencode("http://127.0.0.1:4096", password="...") as client:
    for agent in client.agent.list():
        print(agent.id)

copy class-attribute instance-attribute 

copy = with_options

with_options 

with_options(
    *,
    base_url: str | URL | None = None,
    password: str | NotGiven | None = NOT_GIVEN,
    directory: str
    | PathLike[str]
    | NotGiven
    | None = NOT_GIVEN,
    timeout: Timeout | NotGiven = NOT_GIVEN,
    max_retries: int | None = None,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
) -> Self

Returns a client with some options changed. It shares this client's connection pool.

default_headers and default_query are merged over the current values. Closing the copy leaves the pool open; it closes with this client. Also available as copy.

wait_until_ready 

wait_until_ready(
    *,
    agents: Iterable[str] = (),
    mcp_servers: Iterable[str] = (),
    timeout: float = 60,
) -> None

Blocks until the server answers, the named agents are listed and the named mcp_servers are connected.

Agents load asynchronously after the server starts, so call this before creating sessions on a freshly booted server. Connection errors and 503s while the server boots count as not ready yet.

Raises:

Type Description
TimeoutError

Something was still missing after timeout seconds. The message names it.

fake classmethod 

fake(
    server: FakeServer | None = None, **kwargs: Any
) -> Self

Returns a client wired to an in-process :class:opencode.testing.FakeServer, for tests.

Pass your own server to configure replies and inspect requests; other arguments go to the constructor.

AsyncOpencode 

AsyncOpencode(
    base_url: str | URL | None = None,
    *,
    password: str | None = None,
    username: str = DEFAULT_USERNAME,
    directory: str | PathLike[str] | None = None,
    timeout: Timeout = DEFAULT_TIMEOUT,
    max_retries: int = DEFAULT_MAX_RETRIES,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    http_client: AsyncClient | None = None,
    transport: AsyncBaseTransport | None = None,
)

Asynchronous client for an OpenCode server. Works with asyncio and trio.

Takes the same arguments as :class:Opencode; http_client is an httpx.AsyncClient.

Example::

from opencode import AsyncOpencode

async with AsyncOpencode("http://127.0.0.1:4096", password="...") as client:
    for agent in await client.agent.list():
        print(agent.id)

copy class-attribute instance-attribute 

copy = with_options

with_options 

with_options(
    *,
    base_url: str | URL | None = None,
    password: str | NotGiven | None = NOT_GIVEN,
    directory: str
    | PathLike[str]
    | NotGiven
    | None = NOT_GIVEN,
    timeout: Timeout | NotGiven = NOT_GIVEN,
    max_retries: int | None = None,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
) -> Self

Returns a client with some options changed. It shares this client's connection pool.

default_headers and default_query are merged over the current values. Closing the copy leaves the pool open; it closes with this client. Also available as copy.

wait_until_ready async 

wait_until_ready(
    *,
    agents: Iterable[str] = (),
    mcp_servers: Iterable[str] = (),
    timeout: float = 60,
) -> None

Blocks until the server answers, the named agents are listed and the named mcp_servers are connected.

Agents load asynchronously after the server starts, so call this before creating sessions on a freshly booted server. Connection errors and 503s while the server boots count as not ready yet.

Raises:

Type Description
TimeoutError

Something was still missing after timeout seconds. The message names it.

fake classmethod 

fake(
    server: FakeServer | None = None, **kwargs: Any
) -> Self

Returns a client wired to an in-process :class:opencode.testing.FakeServer, for tests.

Pass your own server to configure replies and inspect requests; other arguments go to the constructor.

DefaultAioHttpClient 

DefaultAioHttpClient(**kwargs: Any)

aiohttp-backed httpx.AsyncClient with the SDK's default connection limits and redirect handling.

Pass it to AsyncOpencode as http_client. Keyword arguments go to httpx.AsyncClient. The SDK does not close a client it was given, so close it yourself (async with it) when you are done. Creating one without the aiohttp extra installed raises RuntimeError.

Module constants

API_VERSION module-attribute 

API_VERSION = '2.1.2'

The OpenCode server version this client was generated from.

NOT_GIVEN module-attribute 

NOT_GIVEN: Final = NotGiven()

NotGiven

Marks an argument that was not passed, as opposed to one passed as None.

The OpenCode API distinguishes a field that is absent from a field set to null, so optional arguments default to NOT_GIVEN and are left out of the request entirely.

BaseModel

Bases: BaseModel

Base class for OpenCode API models.

Attributes use snake_case while the wire format uses OpenCode's camelCase names. Models accept either spelling on input and always serialize to the wire names.

Unknown fields are kept rather than rejected, so a client keeps working against a newer server. They are available through model_extra and attribute access.

to_dict 

to_dict(*, exclude_unset: bool = True) -> dict[str, Any]

Returns the model as a JSON-compatible dict using wire field names.

to_json 

to_json(
    *, indent: int | None = None, exclude_unset: bool = True
) -> str

Returns the model as JSON text using wire field names.