# ashish16052/opencode-runtime architecture

> Architecture diagram of the GitHub repository ashish16052/opencode-runtime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashish16052/opencode-runtime
- Repository: https://github.com/ashish16052/opencode-runtime

## Overview

opencode-runtime embeds OpenCode as a managed Python service: an application requests an isolated runtime session, sends prompts, and receives a complete response or streamed events. Runtime orchestration keys servers by workspace, user, and project, starts or reuses OpenCode processes, and tracks them in a shared registry. Sessions use an HTTP/SSE client for conversation operations; a separate CLI manages and inspects the server fleet. The graph reflects README capabilities and sampled call paths; unsampled implementation details are represented only where the tree or documentation supports them.

Main entry points: [`src/opencode_runtime/session.py`](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/session.py) (Conversation session), [`src/opencode_runtime/server.py`](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/server.py) (Server manager), [`src/opencode_runtime/client.py`](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/client.py) (HTTP / SSE client), [`src/opencode_runtime/runtime.py`](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/runtime.py) (Runtime factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python API"]
  node_runtime["Runtime factory<br/>[runtime.py]"]
  node_session["Conversation session<br/>[session.py]"]
  node_response["Collected response<br/>[response.py]"]
  node_event["Stream event<br/>[event.py]"]
end

subgraph group_lifecycle["Runtime Lifecycle"]
  node_manager["Server manager<br/>[server.py]"]
  node_process["Process primitives<br/>[process.py]"]
  node_registry[("Instance registry<br/>[registry.py]")]
end

subgraph group_conversation["Conversation"]
  node_client["HTTP / SSE client<br/>[client.py]"]
end

subgraph group_management["Fleet Management"]
  node_cli["Management CLI<br/>[cli.py]"]
end

node_app(("Embedding application"))
node_opencode["OpenCode server"]
node_cliuser(("Fleet operator"))

node_app -->|"creates runtime"| node_runtime
node_runtime -->|"gets or starts server"| node_manager
node_manager -->|"claims and tracks"| node_registry
node_manager -->|"spawns and stops"| node_process
node_process -->|"launches process"| node_opencode
node_manager -->|"checks health"| node_client
node_client -->|"sends HTTP requests"| node_opencode
node_opencode -->|"streams SSE events"| node_client
node_runtime -->|"creates session"| node_session
node_session -->|"creates and prompts"| node_client
node_session -->|"consumes event stream"| node_client
node_session -->|"collects answer"| node_response
node_session -->|"yields events"| node_event
node_app -->|"asks or streams"| node_session
node_cliuser -->|"runs commands"| node_cli
node_cli -->|"starts, checks, stops"| node_manager
node_cli -->|"lists instances"| node_registry

click node_runtime "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/runtime.py"
click node_session "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/session.py"
click node_response "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/response.py"
click node_event "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/event.py"
click node_manager "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/server.py"
click node_process "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/process.py"
click node_registry "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/registry.py"
click node_client "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/client.py"
click node_cli "https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/cli.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime,node_session,node_response,node_event toneBlue
class node_manager,node_process,node_registry toneAmber
class node_client,node_opencode toneMint
class node_cli toneRose
class node_app,node_cliuser toneIndigo
```

## Components

### Python API

- [Runtime factory](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/runtime.py): `src/opencode_runtime/runtime.py`
- [Conversation session](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/session.py): `src/opencode_runtime/session.py`
- [Collected response](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/response.py): `src/opencode_runtime/response.py`
- [Stream event](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/event.py): `src/opencode_runtime/event.py`

### Runtime Lifecycle

- [Server manager](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/server.py): `src/opencode_runtime/server.py`
- [Process primitives](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/process.py): `src/opencode_runtime/process.py`
- [Instance registry](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/registry.py): `src/opencode_runtime/registry.py`

### Conversation

- [HTTP / SSE client](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/client.py): `src/opencode_runtime/client.py`

### Fleet Management

- [Management CLI](https://github.com/ashish16052/opencode-runtime/blob/main/src/opencode_runtime/cli.py): `src/opencode_runtime/cli.py`

### Other components

- **Embedding application**
- **OpenCode server**
- **Fleet operator**

## Connections

- Embedding application → Runtime factory: creates runtime
- Runtime factory → Server manager: gets or starts server
- Server manager → Instance registry: claims and tracks
- Server manager → Process primitives: spawns and stops
- Process primitives → OpenCode server: launches process
- Server manager → HTTP / SSE client: checks health
- HTTP / SSE client → OpenCode server: sends HTTP requests
- OpenCode server → HTTP / SSE client: streams SSE events
- Runtime factory → Conversation session: creates session
- Conversation session → HTTP / SSE client: creates and prompts
- Conversation session → HTTP / SSE client: consumes event stream
- Conversation session → Collected response: collects answer
- Conversation session → Stream event: yields events
- Embedding application → Conversation session: asks or streams
- Fleet operator → Management CLI: runs commands
- Management CLI → Server manager: starts, checks, stops
- Management CLI → Instance registry: lists instances