Skip to content

terminals

Client for the Terminals endpoints.

Reverse proxy for admin-configured terminal servers. Provides access to terminal server listings and HTTP proxy forwarding.

The WebSocket proxy endpoint (/{server_id}/api/terminals/{session_id}) is not supported by this HTTP client — WebSocket connections cannot be wrapped by httpx.

Classes

TerminalsClient 

TerminalsClient(client: OWUIClientBase)

Bases: ResourceBase

Client for the Terminals endpoints.

Terminals is a reverse-proxy feature that forwards HTTP requests to admin-configured terminal servers. Only the HTTP endpoints are implemented; the interactive WebSocket proxy is not supported.

Used by:
Source code in src/owui_client/client_base.py 
175
176
def __init__(self, client: OWUIClientBase):
    self._client = client

Functions

list_servers 
list_servers() -> list[dict[str, Any]]

List terminal servers the authenticated user has access to.

Returns only servers that are enabled and for which the user's group membership grants access. Each entry contains id, url, and name.

Returns:

Type Description
list[dict[str, Any]]

List of terminal server dicts, each with keys id, url,
list[dict[str, Any]]

name.
Source code in src/owui_client/routers/terminals.py 
25
26
27
28
29
30
31
32
33
34
35
36
async def list_servers(self) -> list[dict[str, Any]]:
    """List terminal servers the authenticated user has access to.

    Returns only servers that are enabled and for which the user's
    group membership grants access. Each entry contains ``id``,
    ``url``, and ``name``.

    Returns:
        List of terminal server dicts, each with keys ``id``, ``url``,
        ``name``.
    """
    return await self._request("GET", "/v1/terminals/")
proxy 
proxy(
    server_id: str,
    path: str,
    method: str = "GET",
    json: Optional[Any] = None,
    data: Optional[Any] = None,
    params: Optional[dict[str, Any]] = None,
) -> Any

Proxy a request to a terminal server.

Forwards an HTTP request through the Open WebUI backend to the terminal server identified by server_id. The backend handles authentication, path sanitization, and access control.

Parameters:

Name Type Description Default
server_id str

ID of the terminal server to proxy to.

 required
path str

URL path to append after the server base URL.

 required
method str

HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). Defaults to "GET".

 'GET'
json Optional[Any]

JSON body to forward with the request.

 None
data Optional[Any]

Form or raw body to forward with the request.

 None
params Optional[dict[str, Any]]

Query parameters to forward with the request.

 None

Returns:

Type Description
Any

The proxied response from the terminal server. May be a dict,
Any

list, bytes, or other type depending on the upstream response.

Raises:

Type Description
HTTPStatusError

If the backend returns 403 (access denied), 404 (server not found), 400 (invalid path), 502 (proxy error), or 503 (server URL not configured).
Source code in src/owui_client/routers/terminals.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
async def proxy(
    self,
    server_id: str,
    path: str,
    method: str = "GET",
    json: Optional[Any] = None,
    data: Optional[Any] = None,
    params: Optional[dict[str, Any]] = None,
) -> Any:
    """Proxy a request to a terminal server.

    Forwards an HTTP request through the Open WebUI backend to the
    terminal server identified by *server_id*. The backend handles
    authentication, path sanitization, and access control.

    Args:
        server_id: ID of the terminal server to proxy to.
        path: URL path to append after the server base URL.
        method: HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD,
            OPTIONS). Defaults to ``"GET"``.
        json: JSON body to forward with the request.
        data: Form or raw body to forward with the request.
        params: Query parameters to forward with the request.

    Returns:
        The proxied response from the terminal server. May be a dict,
        list, bytes, or other type depending on the upstream response.

    Raises:
        HTTPStatusError: If the backend returns 403 (access denied),
            404 (server not found), 400 (invalid path), 502 (proxy
            error), or 503 (server URL not configured).
    """
    kwargs: dict[str, Any] = {}
    if json is not None:
        kwargs["json"] = json
    if data is not None:
        kwargs["data"] = data
    if params is not None:
        kwargs["params"] = params

    return await self._request(
        method,
        f"/v1/terminals/{server_id}/{path}",
        **kwargs,
    )