docs: add Coder SSH-tunnel guide for reaching adk web

README.md

@@ -107,6 +107,8 @@ When you open a **Coder workspace**, startup runs automatically in the backgroun
 
 **Your next step:** run [`00_environment_check.ipynb`](implementations/getting_started/00_environment_check.ipynb) top to bottom. That notebook will confirm that startup succeeded.
 
+**ADK web UI.** `adk web` binds to `localhost` *inside* the workspace, so a browser on your laptop cannot reach it until you tunnel. [Guide 5](guides/05-access-adk-web-via-ssh-tunnel.md) walks through that on macOS, Windows, and Linux. Skip it if you are running the repo locally.
+
 On first boot, keys are verified against live services and your onboarding status is recorded. Workspace restarts reload keys without re-running the full test suite.
 
 **Local machine or troubleshooting** — fetch and verify keys manually:
@@ -203,7 +205,7 @@ uv run pre-commit run --all-files
 ## Documentation
 
 - Per-implementation READMEs under [`implementations/`](implementations/) — the primary user surface.
-- [`guides/`](guides/) — self-contained, step-by-step strategy guides for the most common build-phase tasks: onboarding a dataset, creating an experiment, customizing an agent's strategy, and auditing a result before you believe it.
+- [`guides/`](guides/) — self-contained, step-by-step strategy guides for the most common build-phase tasks: onboarding a dataset, creating an experiment, customizing an agent's strategy, and auditing a result before you believe it. [Guide 5](guides/05-access-adk-web-via-ssh-tunnel.md) is the Coder companion for reaching `adk web` from your laptop.
 - [Architecture atlas](https://vectorinstitute.github.io/agentic-forecasting/architecture-atlas.html) ([source](docs/architecture-atlas.html)) — a self-contained visual atlas of the system architecture: the loop, the temporal fence, predictor families, the harness, agent anatomy, and how each reference implementation instantiates them.
 - [`aieng-forecasting/README.md`](aieng-forecasting/README.md) and [`aieng-forecasting/aieng/forecasting/methods/README.md`](aieng-forecasting/aieng/forecasting/methods/README.md) — the library and the method catalog.
 - [`planning-docs/roadmap.md`](planning-docs/roadmap.md) — architecture principles and extension ideas.

docs/architecture-atlas.html

@@ -349,7 +349,7 @@ <h1>Agentic Forecasting Atlas</h1>
       <li><a href="#s04"><span class="n">04</span><span><span class="rt">The harness</span> <span class="rd">— backtest to develop, evaluate to commit</span></span></a></li>
       <li><a href="#s05"><span class="n">05</span><span><span class="rt">The agent</span> <span class="rd">— anatomy of an analyst</span></span></a></li>
       <li><a href="#s06"><span class="n">06</span><span><span class="rt">The implementations</span> <span class="rd">— five instantiations, one architecture</span></span></a></li>
-      <li><a href="#s07"><span class="n">07</span><span><span class="rt">Build your own</span> <span class="rd">— two paths, four guides</span></span></a></li>
+      <li><a href="#s07"><span class="n">07</span><span><span class="rt">Build your own</span> <span class="rd">— two paths, then the worksheets</span></span></a></li>
     </ol>
   </nav>
 </header>
@@ -850,6 +850,10 @@ <h3 class="sub">Where do you land?</h3>
           <td>Want covariates / report-grounded prompting / judged categorical</td>
           <td><a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/implementations/sp500_forecasting/README.md">sp500</a> / <a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/implementations/food_price_forecasting/README.md">food_price</a> / <a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/implementations/boc_rate_decisions/README.md">boc</a> README respectively, then Path A on that starter (toggles; guide 3's levers are the same <code class="chip">AgentConfig</code> fields).</td>
         </tr>
+        <tr>
+          <td>On Coder and want <code class="chip">adk web</code> in a local browser</td>
+          <td><a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/guides/05-access-adk-web-via-ssh-tunnel.md">guide 5</a> — tunnel <code class="chip">localhost:8000</code> from the workspace to your laptop. Skip it if you are running locally.</td>
+        </tr>
       </tbody>
     </table>
     </div>

guides/05-access-adk-web-via-ssh-tunnel.md

@@ -0,0 +1,158 @@
+# Guide 5 — Accessing the ADK Web UI via SSH tunneling
+
+**By the end of this guide** you will have your local browser talking to an ADK agent that is running inside your Coder workspace. The same steps work on **macOS, Windows, and Linux** — where a step differs, look for the OS callout.
+
+This is a Coder-environment companion, not a step on Path A or Path B. Skip it if you are running the repo on your own machine: `adk web` already binds to `localhost` there, and you can open the UI directly.
+
+**Prerequisites:** a Coder workspace with the repo ready (`uv sync` already done — the bootcamp image does this for you). You will also install the Coder CLI on your **personal computer**, not inside the workspace.
+
+---
+
+## Prerequisites (inside your Coder workspace)
+
+1. Open your Coder workspace terminal.
+
+2. Start an ADK agent on port `8000`. From the **repository root**, for example:
+
+```bash
+uv run adk web implementations/energy_oil_forecasting/
+```
+
+   Other common targets, also from the repo root:
+
+```bash
+uv run adk web implementations/getting_started/concierge_agent
+uv run adk web implementations/energy_oil_forecasting/starter_agent
+```
+
+   From `implementations/energy_oil_forecasting/` the adaptive-agent notebooks use the shorter `uv run adk web adaptive_agent/`. Any of these is fine — the tunnel does not care which agent is serving.
+
+3. Keep this workspace terminal tab open and running.
+
+---
+
+## Step 1 — Install the Coder CLI locally
+
+Install the Coder CLI on your **personal computer** (not inside the VM). Follow the official instructions, which cover macOS, Windows, and Linux: [https://coder.com/docs/install/cli](https://coder.com/docs/install/cli)
+
+Verify the install in a **fresh** terminal:
+
+```bash
+coder version
+```
+
+---
+
+## Step 2 — Authenticate and configure SSH
+
+Open a **new terminal** on your local computer.
+
+> **Windows:** Use **PowerShell** (or Windows Terminal), not the legacy `cmd` prompt. All commands below work unchanged in PowerShell.
+
+1. Log in to the platform:
+
+```bash
+coder login https://platform.vectorinstitute.ai/
+```
+
+   Follow the prompt to paste your **access token** from the browser. The token is per-user and is shown on the login page that opens.
+
+2. Configure your local SSH settings:
+
+```bash
+coder config-ssh
+```
+
+   This links your local SSH client to Coder by adding host entries to your SSH config:
+
+   - macOS / Linux: `~/.ssh/config`
+   - Windows: `%USERPROFILE%\.ssh\config`
+
+   The dashboard shows a workspace name such as `ethan-fc-dev`. After `coder config-ssh`, the matching SSH host is `coder.ethan-fc-dev`. Option A below uses the SSH host (`coder.<name>`); Option B uses the dashboard name (`<name>`, no `coder.` prefix).
+
+---
+
+## Step 3 — Create the SSH tunnel
+
+You have two options. Option A is a raw `ssh` port-forward; Option B is simpler and identical across platforms.
+
+### Requirement: an SSH client
+
+- **macOS / Linux:** OpenSSH is preinstalled — nothing to do.
+- **Windows:** Windows 10/11 ship an OpenSSH client, but it is occasionally not enabled. If `ssh` is "not recognized," enable it via **Settings → Apps → Optional Features → Add a feature → OpenSSH Client**, or use the `ssh` bundled with [Git for Windows](https://git-scm.com/download/win). Option B does not need a working `ssh` on your `PATH`.
+
+### Option A — Manual port forward with `ssh`
+
+Run in your local terminal, substituting your workspace name (the dashboard name, with the `coder.` prefix):
+
+```bash
+ssh -L 8000:localhost:8000 coder.<YOUR_WORKSPACE_NAME> -N
+```
+
+Example: if the dashboard shows `ethan-fc-dev`, the host is `coder.ethan-fc-dev`.
+
+- The terminal will look **frozen or paused** — that means the tunnel is active. This is the same on PowerShell, macOS Terminal, and Linux.
+- **Do not close this terminal window.**
+
+### Option B — Let Coder do it (recommended)
+
+Skip writing the `ssh -L` command by hand. Use the dashboard workspace name (no `coder.` prefix):
+
+```bash
+coder port-forward <YOUR_WORKSPACE_NAME> --tcp 8000:8000
+```
+
+This behaves identically on macOS, Windows, and Linux, and does not depend on your local SSH client. Leave it running.
+
+---
+
+## Step 4 — Access the UI
+
+1. Open your local web browser.
+2. Navigate to [http://localhost:8000](http://localhost:8000).
+3. You can now fully interact with the ADK web interface.
+
+---
+
+## Troubleshooting
+
+**"Address already in use" / port 8000 is taken.** Something else on your machine is using `8000`. Remap the *local* side of the tunnel to a free port, then browse to that port:
+
+```bash
+# Option A
+ssh -L 8080:localhost:8000 coder.<YOUR_WORKSPACE_NAME> -N
+# Option B
+coder port-forward <YOUR_WORKSPACE_NAME> --tcp 8080:8000
+```
+
+Then open [http://localhost:8080](http://localhost:8080). The format is `LOCAL_PORT:localhost:REMOTE_PORT` (Option A) or `LOCAL_PORT:REMOTE_PORT` (Option B) — only change the first number. The agent in the workspace stays on `8000`.
+
+**`ssh: command not found` (Windows).** Enable the OpenSSH Client optional feature or use Git Bash (see Step 3), or switch to Option B.
+
+**`coder: command not found` after install.** Open a new terminal so the updated PATH is picked up, then re-run `coder version`.
+
+**Can't find your workspace name.** It's listed in the Coder dashboard, and `coder config-ssh` writes matching `Host coder.<name>` entries into your SSH config (`~/.ssh/config` or `%USERPROFILE%\.ssh\config`).
+
+**Firewall prompt on first connect (Windows/macOS).** Allow access for the SSH/Coder client when prompted — it only opens a local loopback tunnel.
+
+**Page won't load / connection refused in the browser.** Confirm the ADK agent is still running in the workspace terminal (Prerequisites, step 2) and that the tunnel terminal is still open and "frozen."
+
+---
+
+## Quick reference
+
+| Task | macOS / Linux | Windows |
+| --- | --- | --- |
+| Install CLI | See [official instructions](https://coder.com/docs/install/cli) | See [official instructions](https://coder.com/docs/install/cli) |
+| Terminal to use | Terminal / any shell | PowerShell / Windows Terminal |
+| SSH client | Preinstalled | OpenSSH Client feature or Git Bash |
+| SSH config path | `~/.ssh/config` | `%USERPROFILE%\.ssh\config` |
+| Tunnel (manual) | `ssh -L 8000:localhost:8000 coder.<name> -N` | same |
+| Tunnel (simple) | `coder port-forward <name> --tcp 8000:8000` | same |
+| Access URL | [http://localhost:8000](http://localhost:8000) | same |
+
+---
+
+## Where to go next
+
+If you tunneled the energy starter or adaptive agent, **[guide 3](03-customize-agent-strategy.md)** is the lever map for changing how it thinks. The [repo concierge](../implementations/getting_started/99_repo_concierge.ipynb) is the other common `adk web` target — useful when you want to ask how the repo is put together rather than drive a forecaster.

guides/README.md

@@ -1,8 +1,8 @@
 # Bootcamp strategy guides
 
-Step-by-step worksheets for the tasks you are most likely to take on during the build phase. Each one is self-contained: it states what you will have at the end, walks there in numbered steps with runnable code, and ends with a verification check and extension ideas. Every code snippet in these guides has been run against the repo as written.
+Step-by-step worksheets for the tasks you are most likely to take on during the build phase. Each one is self-contained: it states what you will have at the end, walks there in numbered steps with runnable code, and ends with a verification check and extension ideas. Every code snippet in guides 1–4 has been run against the repo as written; guide 5 is Coder CLI / SSH setup on your laptop.
 
-These are **guides, not reference implementations**. The reference implementations under [`implementations/`](../implementations/) show finished forecasting systems; these guides show you the *moves* — how to bring in data, stand up an experiment, and reshape an agent — using only machinery that already exists in the repo.
+These are **guides, not reference implementations**. The reference implementations under [`implementations/`](../implementations/) show finished forecasting systems; these guides show you the *moves* — how to bring in data, stand up an experiment, and reshape an agent — using only machinery that already exists in the repo. [Guide 5](05-access-adk-web-via-ssh-tunnel.md) is the exception: it is Coder-environment setup (reaching `adk web` from your laptop), not a forecasting move.
 
 **Start with the [architecture atlas](https://vectorinstitute.github.io/agentic-forecasting/architecture-atlas.html)** — it's the map. Read it first if you're lost about how the pieces fit; then come back and pick a worksheet by path, not by number.
 
@@ -18,7 +18,10 @@ These are **guides, not reference implementations**. The reference implementatio
 | 2 | [Creating a new experiment](02-create-an-experiment.md) | A backtest + evaluation setup on that series: a YAML spec, a predictor lineup in code, and a scored leaderboard |
 | 3 | [Customizing an analyst agent's strategy](03-customize-agent-strategy.md) | A map of every lever that changes how an agent behaves — persona, toolbelt, skills, search strategy — with a worked change for each |
 | 4 | [Auditing a result before you believe it](04-audit-your-results.md) | A finished backtest interrogated at four altitudes — inputs, model behaviour, score decomposition, noise floor — ending in a claim you can defend in a writeup |
+| 5 | [Accessing the ADK Web UI via SSH tunneling](05-access-adk-web-via-ssh-tunnel.md) | Your local browser talking to `adk web` running inside a Coder workspace (macOS, Windows, Linux) |
 
-**Prerequisites.** A working environment (`uv sync --dev` from the repo root — see the [main README](../README.md#setup)). Guides 1, 2, and 4 need nothing else; all three onboard, score, and audit against a small sample dataset (committed at [`assets/harbourview_lumber_spot.csv`](assets/harbourview_lumber_spot.csv)), entirely offline. Guide 3 exercises the agent stack, so run [`00_environment_check.ipynb`](../implementations/getting_started/00_environment_check.ipynb) first if you haven't.
+**Coder / `adk web`.** Guides 1–4 assume you can already reach the repo. If you are on a Coder workspace and want the ADK browser UI on your laptop, that is [guide 5](05-access-adk-web-via-ssh-tunnel.md) — skip it on a local machine.
+
+**Prerequisites.** A working environment (`uv sync --dev` from the repo root — see the [main README](../README.md#setup)). Guides 1, 2, and 4 need nothing else; all three onboard, score, and audit against a small sample dataset (committed at [`assets/harbourview_lumber_spot.csv`](assets/harbourview_lumber_spot.csv)), entirely offline. Guide 3 exercises the agent stack, so run [`00_environment_check.ipynb`](../implementations/getting_started/00_environment_check.ipynb) first if you haven't. Guide 5 is Coder-only: it needs the [Coder CLI](https://coder.com/docs/install/cli) on your personal computer, not inside the workspace.
 
 **Conventions.** Guide 3 anchors on the [energy / WTI implementation](../implementations/energy_oil_forecasting/) — the most complete agent stack in the repo, built as a ToolSpec toolbelt — and guide 4 borrows its analysis helpers and committed artifacts. The sp500/food/BoC starters aren't built the same way: they expose `enable_search`/`enable_code_exec` toggles on the same underlying `AgentConfig` fields instead of a toolbelt. [Guide 3's opening section](03-customize-agent-strategy.md#which-starter-are-you-on) maps between the two, so guide 3's other patterns still transfer to whichever starter you're on. Paths in code are shown relative to the repo root; run snippets from the repo root unless a step says otherwise.

implementations/README.md

@@ -28,7 +28,7 @@ implementations/
 `-- pyproject.toml            # local workspace packaging
 ```
 
-YAML backtest and eval specs live under each use case in `specs/`. Each directory is independent; see its `README.md` for the walkthrough. For the build-phase moves — onboarding data, standing up an experiment, customizing an agent, auditing a result — see [`guides/`](../guides/).
+YAML backtest and eval specs live under each use case in `specs/`. Each directory is independent; see its `README.md` for the walkthrough. For the build-phase moves — onboarding data, standing up an experiment, customizing an agent, auditing a result — see [`guides/`](../guides/). On a Coder workspace, [`guides/05-access-adk-web-via-ssh-tunnel.md`](../guides/05-access-adk-web-via-ssh-tunnel.md) is how you open `adk web` in a browser on your laptop.
 
 Every domain use case (all except `getting_started`) also ships a `starter_agent/` module and a `99_starter_agent.ipynb` — a fresh, hackable **starter agent** that is the consistent "build your own" entry point for that use case (toggleable news search + code execution, two lightweight tool-usage skills, an interactive cell, and one scored forecast).
 

implementations/energy_oil_forecasting/05_adaptive_agent_training.ipynb

@@ -460,7 +460,9 @@
     "```\n",
     "\n",
     "Open `http://localhost:8000` in your browser. The agent has its full skill  \n",
-    "set available: code execution, web search, and mutation tools.\n",
+    "set available: code execution, web search, and mutation tools. On a **Coder  \n",
+    "workspace** that URL is inside the VM — [guide 5](../../guides/05-access-adk-web-via-ssh-tunnel.md)  \n",
+    "tunnels it to your laptop.\n",
     "\n",
     "**Suggested conversation starters:**\n",
     "\n",

implementations/energy_oil_forecasting/06_protected_eval.ipynb

@@ -538,7 +538,7 @@
         "    uv run adk web adaptive_agent/\n",
         "```\n",
         "\n",
-        "Open `http://localhost:8000`. See Notebook 5 for suggested conversation starters."
+        "Open `http://localhost:8000`. See Notebook 5 for suggested conversation starters. On a **Coder workspace** that URL is inside the VM — [guide 5](../../guides/05-access-adk-web-via-ssh-tunnel.md) tunnels it to your laptop."
       ],
       "id": "be42fd1a"
     }

implementations/energy_oil_forecasting/analyst_agent/agent.py

@@ -534,9 +534,7 @@ def build_wti_code_exec_config(
     return AgentConfig(
         name="wti_analyst_code",
         model=model,
-        instruction=(
-            _WTI_ANALYST_INSTRUCTION + _CONTEXT_RETRIEVAL_SUPPLEMENT + _CODE_EXEC_SKILLS_SUPPLEMENT
-        ),
+        instruction=(_WTI_ANALYST_INSTRUCTION + _CONTEXT_RETRIEVAL_SUPPLEMENT + _CODE_EXEC_SKILLS_SUPPLEMENT),
         max_output_tokens=max_output_tokens,
         context_retrieval=ContextRetrievalConfig(
             enabled=True,
@@ -611,9 +609,7 @@ def build_wti_tool_config(
     return AgentConfig(
         name="wti_analyst_tool",
         model=model,
-        instruction=(
-            _WTI_ANALYST_INSTRUCTION + _CONTEXT_RETRIEVAL_SUPPLEMENT + _FORECAST_TOOL_SUPPLEMENT
-        ),
+        instruction=(_WTI_ANALYST_INSTRUCTION + _CONTEXT_RETRIEVAL_SUPPLEMENT + _FORECAST_TOOL_SUPPLEMENT),
         context_retrieval=ContextRetrievalConfig(
             enabled=True,
             instruction=_WTI_CONTEXT_RETRIEVAL_INSTRUCTION,

implementations/getting_started/99_repo_concierge.ipynb

@@ -206,7 +206,9 @@
         "\n",
         "**Alternative:** `uv run adk web implementations/getting_started/concierge_agent`\n",
         "opens a browser UI (same agent). From `implementations/getting_started/`, you can\n",
-        "also use the shorter `uv run adk run concierge_agent`.\n",
+        "also use the shorter `uv run adk run concierge_agent`. On a **Coder workspace**,\n",
+        "that UI is inside the VM — [guide 5](../../guides/05-access-adk-web-via-ssh-tunnel.md)\n",
+        "tunnels it to your laptop.\n",
         "\n",
         "---\n",
         "\n",