vunknown for OpenCode server 2.1.2
# Drive OpenCode from Python,
fully typed.
All 142 operations of the OpenCode server API, sync and async, with pydantic models for every
request, response and event. Generated from the same contract as the official TypeScript client.
```bash
pip install opencode-python-sdk
```
[](https://pypi.org/project/opencode-python-sdk/)
[](https://pypi.org/project/opencode-python-sdk/)
[](https://github.com/shrijayan/opencode-python-sdk/actions/workflows/ci.yml)
[Get started](getting-started/index.md){ .md-button .md-button--primary }
[API reference](reference/index.md){ .md-button }
=== "Sync"
```python
from opencode import OpencodeServer
with OpencodeServer(cwd="/path/to/repo") as server: # (1)!
client = server.client()
session = client.session.create(title="Review")
client.session.prompt(session.id, text="Summarize the open TODOs")
client.session.wait(session.id)
for message in client.message.list(session.id): # (2)!
print(message.type)
```
1. Starts `opencode serve` on a free port with a random password, and stops it on exit.
2. Iterating a page fetches the following pages as needed.
=== "Async"
```python
import asyncio
from opencode import AsyncOpencode
async def main() -> None:
async with AsyncOpencode("http://127.0.0.1:4096") as client:
session = await client.session.create(title="Review")
await client.session.prompt(session.id, text="Hello")
async for message in client.message.list(session.id):
print(message.type)
asyncio.run(main()) # (1)!
```
1. Works with asyncio and trio.
01
### Complete
Every operation of the OpenCode 2.1 API, on `Opencode` and `AsyncOpencode`, with 96 typed event classes.
02
### Generated from the source
The contract is exported from OpenCode's own Effect `HttpApi`, so names and shapes match the TypeScript client.
03
### Safe retries
Only retries when a request cannot have changed server state. A prompt is never sent twice.
04
### Forward compatible
New fields, enum values, union variants and events from newer servers are kept, not rejected.
05
### Typed errors
Every error the server declares is its own exception class with a typed body.
06
### Batteries included
Launch `opencode serve`, paginate lists, and stream server-sent events with one call each.
## Where to next { .oc-section-title }
- [Connect to a server](getting-started/connect.md) you already run, or [start one from Python](getting-started/server.md).
- Read the [sessions and prompts guide](guides/sessions.md) for the core workflow.
- Browse the [API reference](reference/index.md), or search it with ++slash++.
- Using an LLM? Point it at [`llms.txt`](https://shrijayan.github.io/opencode-python-sdk/llms.txt) or [`llms-full.txt`](https://shrijayan.github.io/opencode-python-sdk/llms-full.txt).
!!! note "Unofficial"
This package is community-maintained and not affiliated with or endorsed by the OpenCode team. If the OpenCode
maintainers want to take it over, the repository and the PyPI name will be transferred.
---
Source: https://shrijayan.github.io/opencode-python-sdk/getting-started/
# Install
```bash
pip install opencode-python-sdk
```
=== "uv"
```bash
uv add opencode-python-sdk
```
=== "poetry"
```bash
poetry add opencode-python-sdk
```
The distribution is called `opencode-python-sdk`; the package imports as `opencode`. It needs Python 3.10 or newer
and depends only on `httpx`, `pydantic`, `anyio` and `typing-extensions`.
```python
import opencode
print(opencode.__version__) # this package
print(opencode.API_VERSION) # the OpenCode server version it was generated from
```
To start a server from Python with [`OpencodeServer`](server.md), install the [OpenCode CLI](https://opencode.ai)
as well, so that `opencode` is on `PATH`.
## Next
- [Connect to a server](connect.md) that is already running.
- [Run a server from Python](server.md) for scripts, tests and embedded use.
- [Use the background service](service.md) to share one `opencode serve --service` between programs.
---
Source: https://shrijayan.github.io/opencode-python-sdk/getting-started/connect/
# Connect to a server
Start a server with the CLI, then point a client at it:
```bash
OPENCODE_PASSWORD=secret opencode serve --port 4096
```
```python
from opencode import Opencode
client = Opencode("http://127.0.0.1:4096", password="secret")
print(client.server.info().version)
```
## Environment variables
`base_url` and `password` fall back to environment variables, so the shortest form is `Opencode()`.
| Argument | Variable |
| --- | --- |
| `base_url` | `OPENCODE_BASE_URL` |
| `password` | `OPENCODE_PASSWORD`, then `OPENCODE_SERVER_PASSWORD` |
`OPENCODE_PASSWORD` is the same variable the OpenCode CLI reads. Pass `password=""` to send no credentials.
## Closing the client
The client owns an `httpx.Client` connection pool. Use it as a context manager, or call `close()`:
```python
with Opencode() as client:
client.agent.list()
```
## Calling the API
Methods mirror the official TypeScript client: `client.