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, new_instance=False)

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.

Single-instance behavior. MITK Workbench is single-instance: starting it while an instance is already running makes the new process hand off to the running one and exit without bringing up a REST server on the requested port. launch() detects a running instance up front (Windows) and, by default, raises MitkError with guidance to connect()/discover() instead. Pass new_instance=True to force a genuinely separate, isolated instance (see below).

Authentication token. The token is passed to the process through the MITK_REST_API_TOKEN environment variable, which the server prefers over the stored preference. The token is therefore never written to disk — not to the preferences file this call generates, nor to any prefs.xml the server persists — while requireAuth=true still enforces it.

``new_instance=True``. When another Workbench is already running, this forces a separate instance via --BlueBerry.newInstance. That instance runs from a fresh MITK-managed temporary storage directory (its REST preferences are seeded with --MITK.preferences-patch; no token is written there). Note that MITK does not remove this temporary directory afterward, so forced instances leave behind (secret-free) temp directories. When no instance is running, new_instance has no effect — the normal launch already yields a fresh instance without a throwaway storage directory. This flag is only acted on where a running instance can be detected (Windows).

The forced instance only gets its own throwaway storage if MITK actually starts a separate instance — i.e. the already-running Workbench is the single-instance owner. In the unusual case where a Workbench process exists but is not that owner (e.g. it is itself a forced instance), MITK does not fork and the seeded REST preferences (enabled/autoStart/port, never the token) are written to the normal preferences store instead.

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 file reference.
new_instance (bool (default: False)) – Force a separate, isolated instance when a Workbench is already running, instead of raising. See the note above.

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, if a Workbench is already running and new_instance is False, or if the Workbench process exits immediately with a preference failure.
FileNotFoundError – If the resolved executable path does not exist.
MitkConnectionError – If the server does not become healthy within timeout seconds.