DSH plugin whale pet widget: DeepSeek Harness setup

The DSH plugin whale pet widget is the community 3D desktop pet dsh-whale-pet: it lives in the DeepSeek Harness interface, swims around, reacts to session state and can chat with you (source). It is a different plugin from the balance whale widget — one is a pet, the other a data panel — so do not treat them as one thing. To find similar widgets, search the market on DSH Plugin Hub by whale and pet keywords.

What the DSH plugin whale pet widget is, and how it differs from the balance widget

The whale pet widget is the "pet" kind of interface component: the point is company and reactions to session state, not displaying balance data (source). What it does:

1. Resident and swimming. It stays near the edge of the viewport, patrols at random over time, looks toward the pointer and pops hearts when hovered.
2. Live reactions. It switches expressions with session state — thinking, working, focused, celebrating, erroring, sleepy, waiting for your approval — and circles in celebration when a long task finishes.
3. Interactive. It can be dragged, snapped to a corner, renamed by right-click, resized (50%–150%) and hidden, with a shortcut to show or hide it.
4. Chatty. The right-click "chat with the whale" entry talks to a large model and remembers a small amount of long-term information about you.

The difference from the balance widget is plain: the balance whale widget is a data panel showing DeepSeek account balance and usage; the whale pet widget is a desktop pet centred on interaction and mood — they are not the same plugin.

What it does: states, expressions and interactions at a glance

Everything the pet shows is a reaction to session state, so reading it as a status indicator is often more useful than reading it as decoration (source).

Two practical consequences: a glance at the pet tells you whether a turn is still running, and an "erroring" face usually means a failed turn is waiting — not that the pet itself is broken.

Where the chat key comes from: three levels of priority

Chat is the only part that needs a key, and it resolves one from three places in order (source).

If none of the three is present, chat reports not configured and the pet shows an error face for an unavailable agent. The fix is to supply any one of the three and restart — you do not need all of them.

Install and enable the DSH plugin: from downloading the repo to restarting the Web UI

The whale pet widget does not use the usual dsh plugin add; it uses the repo's own installer, node install-profile.mjs web (source). Four steps in order:

1. Download the repo. Grab it with a GitHub ZIP or git clone; this step needs Node.js 22+ locally. Expected: the repo directory is on disk and node -v shows 22 or higher.
2. Run the installer. From the repo directory run node install-profile.mjs web. It copies the package to $DSH_HOME/profiles/web/plugins/ui-whale-pet, adds it to the profile manifest and node_modules, and appends the ui-whale-pet Cordis line to that profile's cordis.patch.yml. The script applies to Node-based CLI and Web profiles only. Expected: ui-whale-pet appears under $DSH_HOME/profiles/web/plugins/, with matching entries in the profile manifest and cordis.patch.yml.
3. Configure the chat key. To let the whale chat, give its agent an API key, otherwise chat reports not configured; it reads the plugin config, DSH_WHALE_API_KEY, or falls back to DEEPSEEK_API_KEY in the DeepSeek Harness credentials. Expected: chat stops reporting not configured once the key is set.
4. Restart and hard-refresh. Restart dsh web, then hard-refresh the browser and the pet appears.

One note: the official desktop client reads its reserved desktop profile and cannot use this script or a normal CLI install — install the packaged bundle from its Plugins page instead.

Whale pet widget vs balance whale widget: five dimensions

The two get confused because both are whales in the corner; on every dimension that matters they are opposites (source).

If you only want one, decide by the purpose row first — everything else follows from it.

DSH plugin common issues: not loading, coexisting with the balance widget, switching widgets

The whale pet's common issues fall into two groups: "it never made it into the profile" and "it is fighting another widget for the corner".

1. Not loading. First confirm the installer really succeeded and ui-whale-pet appears in the profile manifest; then restart dsh web and hard-refresh the browser to rule out a stale cache.
2. Installed alongside the balance widget. They are independent plugins and generally coexist, but both take the lower-right corner and can crowd each other; hide or uninstall one if you want only one.
3. Switching to another similar widget. Pets and data panels are two different lines — decide whether you want company or data, then pick by keyword on DSH Plugin Hub instead of installing the two as if they were one.

Verifying the DSH plugin whale pet widget after install

The script touches three places; the fastest check is to confirm all three, rather than only looking at the browser.

# 1) Did the installer copy the package into the profile?
ls "$DSH_HOME/profiles/web/plugins/ui-whale-pet"
# the package directory should exist

# 2) Was the Cordis line appended to that profile?
grep -n "ui-whale-pet" "$DSH_HOME/profiles/web/cordis.patch.yml"
# a matching line should be present

Expected: the package directory exists and the Cordis line is present. If the directory is missing, the installer never ran against the profile you are using; if the line is missing, the profile will not load the pet even though the files are there — restore the line and restart.

Notes on the DSH plugin whale pet widget

Remember two things — it is a pet, not a balance panel, and it installs by script, not by plugin add — and that is enough.

1. Do not confuse the plugins: whale pet (pet) and balance whale (data) are different.
2. Use the right install route: node install-profile.mjs web, not the usual dsh plugin add.
3. Have the Node version ready: the installer requires Node.js 22+.
4. Chat needs a key: without one it reports not configured; add it and restart.
5. Desktop takes another route: the desktop profile is reserved, so install the bundle from its Plugins page.
6. Hard-refresh after installing: restart dsh web, then hard-refresh the browser.
7. The balance widget is in balance whale widget install, and similar plugins are on DSH Plugin Hub.

Common misconceptions about the DSH plugin whale pet widget

Five assumptions that lead to the wrong fix:

1. "It installs with dsh plugin add like everything else." No — it uses the repo's own install-profile.mjs script.
2. "It needs the same API key as the balance widget." No — only chat needs a key; the balance widget reads a credential or the login state.
3. "A pet that shows an error face is broken." Usually not — the face is mirroring a failed turn or an unconfigured chat agent.
4. "After installing, a normal refresh is enough." Not reliably — restart dsh web and hard-refresh to clear a cached bundle.
5. "The desktop client can run the same script." No — the desktop profile is reserved; use its Plugins page instead.

Source: Community plugin repo - dsh-whale-pet, DeepSeek Harness CLI README.