Top-Level Functions

The most common entry points. Import with import mitk_workbench_remote as mw.

mitk_workbench_remote.connect(url='http://localhost:8080', *, token=None, timeout=30.0, transfer_mode=None, trust_env=None)

Connect to a running MITK Workbench REST server.

No HTTP call is made during construction — the connection is established lazily on first use.

Parameters:

url (str (default: 'http://localhost:8080')) – Base URL of the Workbench REST server.
token (str | None (default: None)) – Optional API token (Authorization: Bearer header).
timeout (float (default: 30.0)) – Request timeout in seconds.
transfer_mode (str | None (default: None)) – Override transfer mode ("direct" or "file-reference"). When None the mode is auto-detected from server capabilities on first data request.
trust_env (bool | None (default: None)) – Whether to honor environment proxy settings. When None (default) env proxies are bypassed for loopback URLs and honored for remote hosts — a forward/corporate proxy cannot reach the caller’s own machine, so proxying a localhost request would fail. Pass True to always honor env proxies or False to never.

Return type:

Workbench

Returns:

A Workbench handle ready for use.

mitk_workbench_remote.discover(ports=range(8080, 8100), *, timeout=0.5)

Probe localhost ports for running MITK Workbench instances.

Probes are executed concurrently. Any port that responds to GET /api/v1/health with a 2xx status is included in the result.

Parameters:

ports (Iterable[int] (default: range(8080, 8100))) – Iterable of port numbers to probe. Defaults to 8080-8099.
timeout (float (default: 0.5)) – Per-probe connection timeout in seconds.

Return type:

list[Workbench]

Returns:

List of Workbench handles, sorted by port number (ascending).

mitk_workbench_remote.launch(executable=None, *, port=None, token=None, timeout=30.0, extra_args=None)

Start a new MITK Workbench process with the REST API enabled.

Spawns the process, waits for the REST server to become healthy, and returns a connected Workbench handle.

On Windows the shipped launcher is a .bat wrapper that start /B detaches the real MitkWorkbench.exe; the tracked cmd.exe then exits 0 within ~0.1 s, long before the REST server is up. launch() therefore tolerates an exit code of 0 and keeps polling /health; only a non-zero exit is treated as an immediate failure. The trade-off: a direct executable that genuinely exits 0 right away (e.g. --help) is not detected until the timeout deadline rather than instantly.

The child’s stderr is redirected to a temp file (never an inherited PIPE, which the detached exe would hold open and deadlock on). On success the file is removed by shutdown(); on a failed launch it is removed before raising. Any failure also kills the process listening on port (the detached exe), since a raised launch() returns no handle for the caller to clean up later.

Parameters:

executable (str | Path | None (default: None)) – Path to the MITK Workbench executable. When None, the MITK_WORKBENCH environment variable is used. Pass either this argument or set the env var.
port (int | None (default: None)) – Port for the REST server. When None, the first free port in 8080-8099 is chosen automatically.
token (str | None (default: None)) – API token for the new server. When None, a secure random 32-character hex token is generated.
timeout (float (default: 30.0)) – Maximum seconds to wait for the server to become healthy before giving up.
extra_args (list[str] | None (default: None)) – Additional command-line arguments appended after the preference patch XML file reference.

Return type:

Workbench

Returns:

A Workbench handle backed by the newly started process.

Raises:

MitkError – If executable is None and MITK_WORKBENCH is not set, if no free port is available, or if the Workbench process exits immediately with a preference-patch failure.
FileNotFoundError – If the resolved executable path does not exist.
MitkConnectionError – If the server does not become healthy within timeout seconds.