# Open My Data API Dashboard

Preferred request: **“Open my SentimenTrader Data API Dashboard.”**

Primary entry: [Open My Data API Dashboard](https://st-tools.sentimentrader.com/indicator-workbench).
Return that hosted link first; it opens immediately and offers the guided
setup. Use the local launch steps below when the user wants the dashboard
itself.

Use this guide only when the user explicitly asks to open or set up the local
Data API Dashboard. Requests using the former “Indicator Workbench” name and
the `/indicator-workbench` slash command remain valid. Connected agents should
call the MCP tool
`get_indicator_workbench` first; this guide is its canonical launch and
recovery contract. My Data API Dashboard is an early-access, read-only view of
the SentimenTrader indicators included in the signed-in account's subscription.
It is not the website Favorites list and does not include account-owned custom
indicators. Technical paths, service identities, and MCP tool names retain
their existing `indicator-workbench` and `workbench` identifiers for
compatibility.

## Current requirements

- The agent must be running on the user's computer and have local command
  access. A cloud-only chat cannot install or start a service on the user's
  computer; explain that limitation and stop.
- The first-stage native installer provisions its own **private CPython 3.14**
  runtime (the pinned CPython 3.14.10 build) inside the dashboard's data
  directory. It does not install or modify system Python, PATH, shell profiles,
  or a package manager.
- If the native installer cannot run, the fallback launcher requires an
  existing **CPython 3.11–3.14**.
- The user completes browser OAuth personally. Never ask for, receive, copy,
  display, or persist a password, token, or Authorization header.

The user's explicit request to open the dashboard authorizes the bounded setup
below. It does not authorize installing a global Python runtime, changing
system package managers, weakening verification, or scanning the disk.

## 1. Check the running service

Probe `http://127.0.0.1:4174/_health`. The default local service is the
dashboard only when the response is exactly:

```json
{"service":"sentiment-workbench","status":"ok"}
```

Do not treat any other service on that port as the dashboard. Even when it
matches, continue with step 3: `ensure` reuses a current running dashboard
and replaces one that is out of date. If the launcher cannot run, return [Open
the local Data API Dashboard](http://127.0.0.1:4174/) for the matching
service.

## 2. Check only the fixed installation path

Do not search the user's disk. Check only the applicable runtime directory:

- Windows: `%LOCALAPPDATA%\sentimentrader\indicator-workbench\runtime\`, then
  `%APPDATA%\sentimentrader\indicator-workbench\runtime\`, then the user's
  local AppData directory.
- macOS: `~/Library/Application Support/sentimentrader/indicator-workbench/runtime/`.
- Linux: an absolute `$XDG_DATA_HOME/sentimentrader/indicator-workbench/runtime/`,
  otherwise `~/.local/share/sentimentrader/indicator-workbench/runtime/`.

Remember whether `workbench-bootstrap.py` exists there, but do not run it until
the native installer or the fallback preflight below has produced a supported
interpreter.

## 3. Run the verified native installer

This is the normal path, including on a computer with no Python at all. Download
the installer and its companion checksum into a new temporary directory, verify
the checksum, then run it.

macOS and Linux:

```sh
curl -fsSL --proto '=https' --tlsv1.2 -o workbench-install.sh \
  https://st-tools.sentimentrader.com/skills/mcp-server/templates/workbench-install.sh
curl -fsSL --proto '=https' --tlsv1.2 -o workbench-install.sh.sha256 \
  https://st-tools.sentimentrader.com/skills/mcp-server/templates/workbench-install.sh.sha256
shasum -a 256 -c workbench-install.sh.sha256   # Linux: sha256sum -c
sh workbench-install.sh
```

Windows PowerShell:

```powershell
curl.exe -fsSL -o workbench-install.ps1 https://st-tools.sentimentrader.com/skills/mcp-server/templates/workbench-install.ps1
curl.exe -fsSL -o workbench-install.ps1.sha256 https://st-tools.sentimentrader.com/skills/mcp-server/templates/workbench-install.ps1.sha256
$expected = (Get-Content .\workbench-install.ps1.sha256 -TotalCount 1).Split(" ")[0]
if ((Get-FileHash .\workbench-install.ps1 -Algorithm SHA256).Hash.ToLowerInvariant() -ne $expected) { throw "checksum mismatch" }
powershell -NoProfile -ExecutionPolicy Bypass -File .\workbench-install.ps1
```

The installer:

- selects the pinned CPython 3.14.10 build for the detected operating system
  and processor architecture;
- downloads it from the official `python-build-standalone` release and verifies
  its SHA-256 before extracting anything;
- installs it only under the fixed private directory and reuses an already
  valid private runtime;
- downloads the official `workbench-bootstrap.py` and verifies its `.sha256`;
- runs `workbench-bootstrap.py ensure --json` with the private interpreter.

Always run the launcher, even when the dashboard is already open: `ensure`
replaces the runtime when a newer bundle is published and restarts a running
dashboard. Parse the installer's single JSON result. A ready response contains the actual
`oauth_url` and `url`; never guess the port.

Do not manually extract the runtime, use `sudo`, pipe a download into a shell,
or fall back to a system package manager. If the download is blocked by company
policy or the network, continue with the fallback below.

## 4. Fallback: use an existing CPython 3.11–3.14

Use this section only when step 3 reports `unsupported_platform` or
`download_tool_missing`, or when company policy or the network blocks the
native installer. Do not silently install or upgrade global Python with
Winget, Homebrew, apt, a downloaded installer, or any other system package
manager.

Choose an interpreter without changing the machine. Verify both
`sys.implementation.name == "cpython"` and a version in the inclusive range
3.11–3.14 before running any launcher.

- On Windows, try the Python launcher selections in this order: `py -3.14`,
  `py -3.13`, `py -3.12`, `py -3.11`; then check `python` and `python3` if
  present.
- On macOS and Linux, try `python3.14`, `python3.13`, `python3.12`,
  `python3.11`; then check `python3` and `python` if present.

Run a small version probe with each candidate rather than trusting its command
name. Ignore aliases that open an app store instead of returning a version.

If no supported interpreter exists, say plainly:

> My Data API Dashboard currently requires CPython 3.11–3.14, and I did not find
> a supported version on this computer. The setup has paused before making any
> dashboard changes.

Then give exactly the recovery path for the detected operating system:

- **Windows:** Open the official
  [Python 3.14.10 release page](https://www.python.org/downloads/release/python-31410/),
  go to **Files**, and choose **Windows installer (64-bit)** for most PCs (or
  **Windows installer (ARM64)** only for a Windows-on-ARM computer). Run the
  installer, select **Add Python to PATH** if that option is shown, choose
  **Install Now**, and finish the installation.
- **macOS:** Open the official
  [Python 3.14.10 release page](https://www.python.org/downloads/release/python-31410/),
  go to **Files**, choose **macOS installer**, open the downloaded package, and
  accept its default installation steps.
- **Linux:** Do not direct a nontechnical user to compile Python or run an
  unreviewed package-manager command. Say that Linux has no single official
  graphical installer and ask the user's IT administrator to install CPython
  3.14 for that computer.

On Windows or macOS, tell the user to fully quit and reopen the desktop agent
after installation, then send **“Continue Data API Dashboard setup.”** On Linux, wait
for the user or their IT administrator to confirm that CPython 3.14 is ready.
Do not send the user to the generic Python download button: it may offer a
newer version that this preview does not support.

If a supported interpreter was found, run the official launcher with it. If the
fixed runtime from step 2 exists, use its `workbench-bootstrap.py`; otherwise
download the official launcher and verify its `.sha256` first:

`https://st-tools.sentimentrader.com/skills/mcp-server/templates/workbench-bootstrap.py`

Run `workbench-bootstrap.py ensure --json`. The launcher automatically
downloads the fixed runtime archive and companion checksum from the official
HTTPS origin:

`https://st-tools.sentimentrader.com/skills/mcp-server/templates/sentiment-workbench.zip`

It verifies the checksum before safe extraction, rejects unexpected archive
entries, installs to the fixed private directory, creates an isolated private
environment, starts browser-OAuth mode on an available loopback port, and waits
for the exact health identity. Do not manually download or extract the ZIP,
skip checksum verification, use global pip, or add a Basic Authorization value.

## 5. Return the two real links

For a ready response, return the actual browser OAuth link first and the actual
dashboard link second. The user signs in in the browser; do not open the login
page, inspect the operating-system credential store, or complete login for the
user. A saved dashboard OAuth session may be reused by the dashboard itself.

After browser sign-in, the callback opens the dashboard. If the OAuth flow was
cancelled or expired, return the new sign-in link supplied by the running
dashboard. Subscription and per-indicator access messages belong in the
dashboard and must not be misreported as installation failures.

## Safe recovery by error code

Retry at most once where this table says to retry. Never bypass an integrity or
path failure.

| Code | Agent response |
|---|---|
| `install_busy` | Say another launch is still in progress, wait briefly, then retry once. A lock left by a stopped launch is cleared automatically, so this means a launch is really running. |
| `unsupported_platform` | Stop. Say this operating system or processor is not supported by the private runtime, then use the section 4 fallback only if a supported interpreter already exists. |
| `download_tool_missing` | Stop the native installer path and use the section 4 fallback. Do not install curl, wget, tar, or a Python runtime with a system package manager. |
| `runtime_download`, `launcher_download` | Check connectivity and retry once. If it still fails, report that the official artifact could not be downloaded. |
| `bundle_download` | Check connectivity and retry once. If it still fails, report that the official bundle could not be downloaded. |
| `runtime_checksum`, `launcher_checksum`, `bundle_checksum` | Stop. Do not weaken or skip verification; give the code and a short plain-language explanation for support. |
| `python_runtime_invalid`, `runtime_invalid`, `bundle_invalid` | Stop. The installer already replaces a damaged private runtime and the launcher rebuilds a half-created private environment by themselves, so this means the downloaded artifact is unusable or the damaged runtime could not be removed. Do not retry with a different artifact. |
| `startup_failed`, `startup_timeout` | Retry once. If it still fails, provide a sanitized diagnostic summary. |
| `python_version` | Return to the section 4 CPython preflight and give the single official installation action. |
| `install_path`, `invalid_runtime`, `runtime_unverified`, `install_failed`, `venv_invalid`, `venv_failed`, `dependencies_failed` | Stop. Do not weaken validation or overwrite an unexpected path. Give the code and a short plain-language explanation for support. |

A diagnostic summary may include the error code, operating-system family,
detected Python version, and failed stage. It must not include a username,
home-directory path, environment dump, full log, password, token,
Authorization header, OAuth code, PKCE verifier, or credential-store contents.

## Completion contract

Setup is complete only when the launcher's JSON status is `ready`, its returned
loopback URL passes the exact dashboard health check, and the user has received
the actual sign-in and dashboard links. Otherwise, report the current stage and
one next action; never present a guessed `127.0.0.1` URL as success.