Background service

The opencode.service module, and the from_service constructors on Opencode and AsyncOpencode.

Find, start and stop the local OpenCode background service.

Example::

from opencode import Opencode, service

endpoint = service.ensure()  # or service.discover(), which never starts one
print(endpoint.url)

with Opencode.from_service() as client:
    print(client.server.info().version)

See :mod:opencode._service for how this follows the TypeScript client.

discover

discover(
    file: str | PathLike[str] | None = None,
    version: Version | None = None,
) -> Endpoint | None

Find a healthy, compatible local service without starting one.

Parameters:

Name	Type	Description	Default
file	str | PathLike[str] | None	Registration file. Defaults to :func:default_file.	None
version	Version | None	Required exact version, or a predicate on the service version.	None

Returns:

Type	Description
Endpoint | None	The service endpoint, or None when no ready service with a matching version is registered.

ensure

ensure(
    file: str | PathLike[str] | None = None,
    version: Version | None = None,
    *,
    command: Sequence[str] | None = None,
    env: Mapping[str, str] | None = None,
    on_start: Callable[[EnsureReason, str | None], None]
    | None = None,
) -> Endpoint

Return a healthy local service, starting opencode serve --service when none is running.

A registered service whose version does not satisfy version is stopped and replaced; its persistent terminals are handed off to the replacement when it is ready. Several processes may call this at once: each starts at most two attempts, the service's own lock picks one winner, and the losers exit cleanly. Gives up after 120 seconds.

Parameters:

Name	Type	Description	Default
file	str | PathLike[str] | None	Registration file. Defaults to :func:default_file.	None
version	Version | None	Required exact version, or a predicate on the service version.	None
command	Sequence[str] | None	Service command and arguments. Defaults to opencode serve --service.	None
env	Mapping[str, str] | None	Variables added to the inherited environment of a started service.	None
on_start	Callable[[EnsureReason, str | None], None] | None	Called once, before the first process is started, with the reason and, for "version-mismatch", the version being replaced.	None

Raises:

Type	Description
ServiceError	The service failed to start, uses an incompatible protocol, or did not answer in time.

stop

stop(
    file: str | PathLike[str] | None = None,
    *,
    pty: PtyMode = "clear",
) -> None

Stop the registered local service and remove its registration.

Parameters:

Name	Type	Description	Default
file	str | PathLike[str] | None	Registration file. Defaults to :func:default_file.	None
pty	PtyMode	"clear" shuts persistent terminals down with the service. "handoff" first asks the service for a handoff ticket that the next service started by :func:ensure adopts. The handoff is best effort and never keeps the old service running.	'clear'

Raises:

Type	Description
ServiceError	The process was still running after SIGTERM and SIGKILL.

headers

headers(endpoint: Endpoint) -> dict[str, str] | None

The Authorization header for endpoint, or None when it needs no credentials.

default_file

default_file() -> Path

The default registration file, $XDG_STATE_HOME/opencode/service.json.

XDG_STATE_HOME defaults to ~/.local/state on every platform, as in OpenCode itself.

async_discover async

async_discover(
    file: str | PathLike[str] | None = None,
    version: Version | None = None,
) -> Endpoint | None

Async version of :func:discover.

async_ensure async

async_ensure(
    file: str | PathLike[str] | None = None,
    version: Version | None = None,
    *,
    command: Sequence[str] | None = None,
    env: Mapping[str, str] | None = None,
    on_start: Callable[[EnsureReason, str | None], None]
    | None = None,
) -> Endpoint

Async version of :func:ensure.

async_stop async

async_stop(
    file: str | PathLike[str] | None = None,
    *,
    pty: PtyMode = "clear",
) -> None

Async version of :func:stop.

Endpoint dataclass

Endpoint(url: str, auth: BasicAuth | None = None)

Connection details of a local OpenCode service.

Pass it to :meth:opencode.Opencode.from_service, or use url and :func:headers with any HTTP client.

url instance-attribute

url: str

Base URL of the service.

auth class-attribute instance-attribute

auth: BasicAuth | None = None

Credentials the service requires, or None when it runs without a password.

BasicAuth dataclass

BasicAuth(username: str, password: str)

HTTP basic credentials of a local service.

username instance-attribute

username: str

Basic auth user name, always opencode.

password class-attribute instance-attribute

password: str = field(repr=False)

The service's private password. Hidden from repr so it stays out of logs.

ServiceError

Bases: OpencodeError

The local service could not be found, started or stopped.