PyPSA · FBumann · May 19, 2026 · May 19, 2026 · May 19, 2026 · May 19, 2026
diff --git a/.github/workflows/test-notebooks.yml b/.github/workflows/test-notebooks.yml
@@ -40,8 +40,8 @@ jobs:
 
           # Skip notebooks that require credentials or special setup
           case "$name" in
-            solve-on-oetc.ipynb|solve-on-remote.ipynb)
-              echo "Skipping $name (requires credentials or special setup)"
+            remote-machines.ipynb)
+              echo "Skipping $name (requires credentials or remote machine)"
               continue
               ;;
           esac

diff --git a/doc/api.rst b/doc/api.rst
@@ -519,10 +519,19 @@ Solvers
 Remote solving
 ==============
 
+Solve a model on a remote machine via SSH or on the OET Cloud (OETC).
+See :doc:`remote-machines` for usage.
+
 .. autosummary::
    :toctree: generated/
 
+   remote.SSH
+   remote.SshSettings
+   remote.Oetc
+   remote.OetcSettings
    remote.RemoteHandler
+   remote.OetcHandler
+   remote.OetcCredentials
 
 
 Solver status and result types

diff --git a/doc/index.rst b/doc/index.rst
@@ -136,8 +136,7 @@ This package is published under MIT license.
    :maxdepth: 2
    :caption: Solving
 
-   solve-on-remote
-   solve-on-oetc
+   remote-machines
    gpu-acceleration
 
 .. toctree::

diff --git a/doc/release_notes.rst b/doc/release_notes.rst
@@ -46,9 +46,39 @@ Most users should keep calling ``model.solve(...)``. If you want more control, y
 * Xpress now supports ``io_api="direct"``: the linopy model is loaded via the native ``loadproblem`` array API instead of being serialised through an LP/MPS file, with SOS constraints attached in-place. Adds ``model.to_xpress()`` matching the existing ``to_gurobipy`` / ``to_highspy`` / ``to_mosek`` helpers.
 * Writing the solution back to the model after solving is faster: it no longer rebuilds the constraint matrix, and now uses positional (rather than label-based) indexing — roughly 2× faster overall.
 
+*Remote solves*
+
+* Pass ``remote=`` to ``Model.solve`` to run the solver on a remote worker:
+
+  .. code-block:: python
+
+      m.solve("gurobi", remote=OetcSettings(...), Method=2)
+      m.solve("highs", remote=SshSettings(hostname=...), presolve="on")
+
+  ``solver_name`` and ``**solver_options`` work the same as for local solves; ``remote=`` selects *where* to run. After the call, ``model.remote`` holds the remote instance (mirrors :attr:`Model.solver`).
+* ``SshSettings.setup_commands: list[str]`` — shell commands run on the remote before the solve, e.g. ``setup_commands=["conda activate linopy-env"]``.
+
 **Deprecations**
 
 * ``Solver.solve_problem``, ``Solver.solve_problem_from_model``, and ``Solver.solve_problem_from_file`` still work but emit a ``DeprecationWarning``. Use ``Solver.from_name(...).solve()`` (or simply ``model.solve(...)``) instead. They will be removed in a future release.
+* ``linopy.remote.OetcHandler`` and ``linopy.remote.RemoteHandler`` are deprecated. Construction emits a ``DeprecationWarning``; the ``solve_on_oetc`` / ``solve_on_remote`` return contracts are unchanged. Migrate:
+
+  .. code-block:: python
+
+      # Before
+      handler = OetcHandler(
+          OetcSettings(credentials=OetcCredentials(email=..., password=...), ...)
+      )
+      solved = handler.solve_on_oetc(m, TimeLimit=100)
+
+      # After
+      m.solve(
+          "gurobi", remote=OetcSettings(email=..., password=..., ...), TimeLimit=100
+      )
+
+  Passing an existing handler via ``Model.solve(remote=handler, ...)`` is also deprecated — pass the settings dataclass instead.
+* ``linopy.remote.OetcCredentials`` is deprecated. Pass ``email`` and ``password`` directly to :class:`OetcSettings` instead of wrapping them. The ``OetcSettings(credentials=OetcCredentials(...))`` shape still works for one deprecation cycle and emits a ``DeprecationWarning``.
+* :class:`linopy.remote.SSH` only exposes ``solve(model)``. For env activation use ``SshSettings.setup_commands``; for arbitrary remote shell commands, drop to :class:`RemoteHandler` (during deprecation) or paramiko directly.
 
 **Bug Fixes**
 
@@ -60,6 +90,7 @@ Most users should keep calling ``model.solve(...)``. If you want more control, y
 * ``available_solvers`` now lists all *installed* solvers, even ones without a working license. If you used it to decide "can I actually solve with X?", switch to ``linopy.licensed_solvers`` or ``SolverClass.license_status()``.
 * ``Model.solver_model`` and ``Model.solver_name`` are now read-only properties that delegate to ``model.solver``. You can't reassign them (only ``= None`` is allowed, which closes the solver), and ``solver_name`` is ``None`` before the first solve.
 * ``result.solution.primal`` and ``result.solution.dual`` are now ``numpy`` arrays indexed by linopy's integer labels (with ``NaN`` for slots without a value), instead of pandas Series keyed by variable/constraint name. If you accessed them by name, use ``model.variables[name].solution`` (or ``model.constraints[name].dual``) instead.
+* The pip extra ``linopy[remote]`` has been renamed to ``linopy[ssh]`` to match what it installs (only ``paramiko``, for SSH transport — OETC has its own ``linopy[oetc]`` extra). ``linopy[remote]`` no longer exists; update your install commands.
 
 **Internal**
 

diff --git a/doc/remote-machines.nblink b/doc/remote-machines.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../examples/remote-machines.ipynb"
+}
diff --git a/doc/solve-on-oetc.nblink b/doc/solve-on-oetc.nblink
diff --git a/doc/solve-on-remote.nblink b/doc/solve-on-remote.nblink
diff --git a/doc/user-guide.rst b/doc/user-guide.rst
@@ -53,8 +53,8 @@ Where to go next
   :doc:`piecewise-linear-constraints`, and the
   :doc:`testing-framework` for asserting structural properties of a
   model.
-- **Solving** — :doc:`solve-on-remote` (SSH),
-  :doc:`solve-on-oetc` (OET Cloud), :doc:`gpu-acceleration` (cuPDLPx).
+- **Solving** — :doc:`remote-machines` (SSH or OET Cloud),
+  :doc:`gpu-acceleration` (cuPDLPx).
 - **Troubleshooting** — :doc:`infeasible-model` (diagnosing infeasible
   problems), :doc:`gurobi-double-logging` (and other solver quirks).
 - **Reference** — the full :doc:`api` listing.
diff --git a/examples/remote-machines.ipynb b/examples/remote-machines.ipynb
@@ -0,0 +1,238 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Remote machines\n",
+    "\n",
+    "linopy can ship your model to a remote machine, run a solver there, and pull the solved model back. Two transports are supported:\n",
+    "\n",
+    "- **SSH** — connect to a server you own (or have access to) over SSH.\n",
+    "- **OETC** — submit jobs to [OET Cloud](https://open-energy-transition.org/), a managed optimization service.\n",
+    "\n",
+    "Both share the same entry point on `Model.solve`:\n",
+    "\n",
+    "```python\n",
+    "m.solve(\"gurobi\", remote=<Settings>, **solver_options)\n",
+    "```\n",
+    "\n",
+    "`solver_name` and `**solver_options` work exactly like a local solve; `remote=` selects *where* to run. After the call, `model.remote` holds the transport instance for post-solve introspection (mirrors `model.solver`)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "> **Note:** This notebook is not executed during the documentation build — it requires either SSH access to a remote server or OETC credentials."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
+   "source": [
+    "## Create a model\n",
+    "\n",
+    "Build the model locally as usual:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from numpy import arange\n",
+    "from xarray import DataArray\n",
+    "\n",
+    "from linopy import Model\n",
+    "\n",
+    "N = 10\n",
+    "m = Model()\n",
+    "coords = [arange(N), arange(N)]\n",
+    "x = m.add_variables(coords=coords, name=\"x\")\n",
+    "y = m.add_variables(coords=coords, name=\"y\")\n",
+    "m.add_constraints(x - y >= DataArray(arange(N)))\n",
+    "m.add_constraints(x + y >= 0)\n",
+    "m.add_objective((2 * x + y).sum())\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "## SSH\n",
+    "\n",
+    "**What you need**\n",
+    "\n",
+    "- `uv pip install \"linopy[ssh]\"` locally (pulls in `paramiko`).\n",
+    "- A remote server with linopy and a solver installed (e.g. in a conda environment).\n",
+    "- SSH access to that machine (key-based auth recommended).\n",
+    "\n",
+    "Build an `SshSettings` and pass it as `remote=`. Use `setup_commands` to activate environments or export variables on the remote shell before the solve."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from linopy.remote import SshSettings\n",
+    "\n",
+    "ssh_settings = SshSettings(\n",
+    "    hostname=\"your.host.de\",\n",
+    "    username=\"username\",\n",
+    "    # password=\"...\",  # not needed when SSH keys are autodetected\n",
+    "    setup_commands=[\"conda activate linopy-env\"],\n",
+    ")\n",
+    "\n",
+    "m.solve(\"gurobi\", remote=ssh_settings)\n",
+    "m.solution"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "## OETC\n",
+    "\n",
+    "**What you need**\n",
+    "\n",
+    "- `uv pip install \"linopy[oetc]\"` locally (pulls in `google-cloud-storage` and `requests`).\n",
+    "- An OETC account with valid credentials.\n",
+    "- The OETC authentication and orchestrator server URLs.\n",
+    "\n",
+    "Build an `OetcSettings`. Two construction styles:\n",
+    "\n",
+    "1. **Manually** — pass `email`, `password`, `name`, and the server URLs.\n",
+    "2. **`OetcSettings.from_env()`** — resolve everything from environment variables (`OETC_EMAIL`, `OETC_PASSWORD`, `OETC_NAME`, `OETC_AUTH_URL`, `OETC_ORCHESTRATOR_URL`). Recommended for CI/CD. Keyword arguments override the environment.\n",
+    "\n",
+    "linopy uploads the model to OETC, submits a compute job, polls until it finishes, and downloads the solution — all behind one call."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from linopy.remote import OetcSettings\n",
+    "\n",
+    "# Option 1: pass credentials directly\n",
+    "oetc_settings = OetcSettings(\n",
+    "    email=\"your-email@example.com\",\n",
+    "    password=\"your-password\",\n",
+    "    name=\"linopy-example-job\",\n",
+    "    authentication_server_url=\"https://auth.oetcloud.com\",\n",
+    "    orchestrator_server_url=\"https://orchestrator.oetcloud.com\",\n",
+    "    cpu_cores=4,\n",
+    "    disk_space_gb=20,\n",
+    ")\n",
+    "\n",
+    "# Option 2: load from environment (with optional overrides)\n",
+    "oetc_settings = OetcSettings.from_env(cpu_cores=4, disk_space_gb=20)\n",
+    "\n",
+    "m.solve(\"gurobi\", remote=oetc_settings, TimeLimit=600, MIPGap=0.01)\n",
+    "\n",
+    "print(f\"Status: {m.status}\")\n",
+    "print(f\"Objective: {m.objective.value:.4f}\")\n",
+    "m.solution"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "## Advanced: drive the transport directly\n",
+    "\n",
+    "For finer control — inspecting the round-tripped solved model, splitting submit from collect for async workflows — use the `Oetc` or `SSH` class directly. `Model.solve(remote=...)` runs the same path internally and then writes the result back onto the local model in place.\n",
+    "\n",
+    "### SSH"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from linopy.remote import SSH\n",
+    "\n",
+    "ssh = SSH(\n",
+    "    settings=ssh_settings,\n",
+    "    solver_name=\"gurobi\",\n",
+    "    options={\"presolve\": \"on\"},\n",
+    ")\n",
+    "result = ssh.solve(m)\n",
+    "m.assign_result(result)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10",
+   "metadata": {},
+   "source": [
+    "### OETC\n",
+    "\n",
+    "`Oetc` exposes the three steps `Model.solve(remote=...)` does internally:\n",
+    "\n",
+    "1. `upload(model)` — serialize and push the netcdf to OETC.\n",
+    "2. `submit()` — submit the compute job; returns the job uuid.\n",
+    "3. `collect(model)` — wait for completion, download, build the `Result`.\n",
+    "\n",
+    "Splitting them lets you fire off a job, do other work, and come back to collect later — useful for long-running jobs or async-style workflows."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from linopy.remote import Oetc\n",
+    "\n",
+    "oetc = Oetc(\n",
+    "    settings=oetc_settings,\n",
+    "    solver_name=\"gurobi\",\n",
+    "    options={\"TimeLimit\": 600, \"MIPGap\": 0.01},\n",
+    ")\n",
+    "\n",
+    "oetc.upload(m)\n",
+    "job_uuid = oetc.submit()\n",
+    "print(f\"Submitted job {job_uuid} — do other work here ...\")\n",
+    "\n",
+    "# Later (or in another process holding `oetc`):\n",
+    "result = oetc.collect(m)\n",
+    "m.assign_result(result)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  },
+  "nbsphinx": {
+   "execute": "never"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}