Server launcher

OpencodeServer

OpencodeServer(
    *,
    cwd: str | PathLike[str] | None = None,
    config: Mapping[str, Any] | None = None,
    isolated: bool = False,
    env: Mapping[str, str] | None = None,
    hostname: str = "127.0.0.1",
    port: int = 0,
    password: str | None = None,
    binary: str | PathLike[str] = "opencode",
    startup_timeout: float = 60.0,
)

Runs opencode serve as a child process for the lifetime of a with block.

The server listens on a free local port and requires a random password, which is passed to clients created with :meth:client. It runs in --stdio mode, so it also exits if this process dies.

Parameters:

Name	Type	Description	Default
cwd	str | PathLike[str] | None	Directory the server runs in, which is its default project location.	None
config	Mapping[str, Any] | None	OpenCode configuration as a mapping, passed through OPENCODE_CONFIG_CONTENT.	None
isolated	bool	Ignore project and Claude Code configuration found on disk, for reproducible embedded use.	False
env	Mapping[str, str] | None	Extra environment variables for the server.	None
hostname	str	Interface to bind. Keep 127.0.0.1 unless the server must be reachable from other hosts.	'127.0.0.1'
port	int	Port to bind. 0 picks a free port.	0
password	str | None	Server password. A random one is generated by default.	None
binary	str | PathLike[str]	The opencode executable, looked up on PATH by default.	'opencode'
startup_timeout	float	Seconds to wait for the server to report its address.	60.0

Example::

with OpencodeServer(cwd="/path/to/repo", isolated=True) as server:
    client = server.client()
    print(client.server.info().version)

cwd instance-attribute

cwd = Path(cwd) if cwd is not None else None

config instance-attribute

config = dict(config) if config is not None else None

isolated instance-attribute

isolated = isolated

env instance-attribute

env = dict(env or {})

hostname instance-attribute

hostname = hostname

port instance-attribute

port = port

password instance-attribute

password = (
    password
    if password is not None
    else secrets.token_urlsafe(32)
)

binary instance-attribute

binary = os.fspath(binary)

startup_timeout instance-attribute

startup_timeout = startup_timeout

url property

url: str

The server's base URL. Available once started.

process property

process: Popen[str] | None

The opencode serve child process, or None before it starts.

running property

running: bool

Whether the server process is alive.

output property

output: str

The last lines the server wrote, for diagnostics.

client

client(
    *,
    directory: str | PathLike[str] | None = None,
    timeout: Timeout | None = None,
) -> Opencode

Returns a sync client connected to this server.

async_client

async_client(
    *,
    directory: str | PathLike[str] | None = None,
    timeout: Timeout | None = None,
) -> AsyncOpencode

Returns an async client connected to this server.

start

start() -> Self

Starts the server and waits until it reports its address.

stop

stop(timeout: float = 10.0) -> None

Stops the server: closes its stdin, then terminates it if it has not exited within timeout.

AsyncOpencodeServer

AsyncOpencodeServer(**kwargs: Any)

Async wrapper around :class:OpencodeServer; takes the same arguments.

Example::

async with AsyncOpencodeServer(isolated=True) as server:
    async with server.client() as client:
        info = await client.server.info()

url property

url: str

The server's base URL. Available once started.

password property

password: str

The server password clients authenticate with.

running property

running: bool

Whether the server process is alive.

output property

output: str

The last lines the server wrote, for diagnostics.

client

client(
    *,
    directory: str | PathLike[str] | None = None,
    timeout: Timeout | None = None,
) -> AsyncOpencode

Returns an async client connected to this server.

start async

start() -> Self

Starts the server and waits until it reports its address.

stop async

stop(timeout: float = 10.0) -> None

Stops the server: closes its stdin, then terminates it if it has not exited within timeout.

ServerStartError

ServerStartError(message: str, *, output: str = '')

Bases: OpencodeError

opencode serve could not be started or did not report its address in time.

output instance-attribute

output = output