dsh-tinyfish

Free web search and fetch for the DeepSeek Harness.
Give your agent the live web — at $0 per call.

Your agent can already reason. This gives it something to reason about: live search results and clean page content, wired straight into the harness's own web_search and web_fetch tools. Powered by TinyFish — both endpoints are free, so the web path on your host stops costing money per call.

Before	After
Search bills per call	$0, forever
Fetched pages arrive as HTML, converted clumsily	Clean Markdown, straight from a browser-grade extractor
Switching providers means reinstalling	Two words in a config file, no reinstall

🚀 Quick start

Method 1: Direct from Web UI (Recommended)

DeepSeek Harness allows installing plugins directly through the Web interface without touching a terminal:

Open DSH Web → Settings → Plugins (设置 → 插件).
Click Install Plugin (添加插件).
Search or enter dsh-tinyfish (or @viztor/dsh-tinyfish).
Click Install — DSH automatically fetches the package from npm, builds the bundle patch, and activates it live without restarting!
In Settings → Plugins → TinyFish, select your channel (direct or monid), enter the key for that channel, and hit Save!

Method 2: Terminal / Profile `package.json`

For headless environments, servers, or version-controlled dotfiles:

cd ~/.dsh/profiles/web
npm install dsh-tinyfish   # or: npm install @viztor/dsh-tinyfish — same thing

Pick one name and install it once. Both tarballs carry byte-identical code and read the same settings (providers register as tinyfish, configuration lives under the row id dsh-tinyfish, credentials under the same two refs) — so switching names later loses nothing, but mounting both loads the bundle twice. dsh-tinyfish is the name DSH convention and these docs use.

📦 Installing from GitHub Packages instead

Every release mirrors @viztor/dsh-tinyfish to GitHub Packages — a second source if npmjs.org is unreachable, and what populates the repository sidebar. Only the scoped name mirrors: GitHub links packages to repositories by owner scope. Unlike npmjs, GitHub Packages requires authentication even for public packages: an unauthenticated request 404s without saying whether the package exists. With a token carrying read:packages:

# project-local .npmrc is better than global for a token
@viztor:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_xxx

then npm install @viztor/dsh-tinyfish resolves from the mirror. Unless npmjs is down, prefer it: no token, no extra configuration.

Mount it — add to that profile's package.json, then restart DSH:

{
  "dependencies": { "dsh-tinyfish": "^0.5.0" },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-tinyfish",
      ],
    },
  },
}

Bundles resolve at boot, so a restart picks it up — reloading the patch alone won't.

Add a key — pick a channel below, save the key, and ask your agent to search for something. That's the whole install.

🔑 Two channels, one plugin

	Direct (default)	Via Monid
What's behind it	TinyFish's own API	The same TinyFish endpoints, through your Monid wallet
You need	A free key from tinyfish.ai	A platform key from app.monid.ai
Fastest setup	`tinyfish auth login`	`monid keys add`
Costs	$0	$0

The default is direct, because the package is named for TinyFish — a fresh install asks for the credential its own name implies. Prefer Monid (it reuses a platform key your Monid MCP mount may already hold)? Pin it in your profile patch:

- id: dsh-tinyfish
  config:
    channel: monid

Both keys can live side by side — saving one never overwrites the other, and switching channels loses nothing.

⚙️ Settings page

Settings → Plugins → TinyFish. Everything editable lives here: whether TinyFish answers search and fetch, the channel picker, your keys, what the search ranks on, and retries. Changes stage and save together; a key you type is stored by the harness, never in your profile.

Both key fields are on the page at once, each labelled with the service it authenticates and each hint naming the reference the save lands on — so you can set the Monid key while Direct is selected, and tell which of the two exists without switching back and forth.

Going back is two words: set searchProvider/fetchProvider to deepseek-official and http. The bundle stays mounted and idle.

📖 Full configuration reference

Everything lives in one row, dsh-tinyfish. The row is validated, so an out-of-range value is rejected with a message rather than silently clamped.

key	default	meaning
`channel`	`direct`	`monid` or `direct`
`apiKey`	(unset)	literal credential for either channel; prefer a ref
`apiKeyEnv`	`TINYFISH_API_KEY`	credential reference, or env var, for `direct`
`monidKeyEnv`	`MONID_API_KEY`	credential reference, or env var, for `monid`
`purpose`	(unset)	goal statement; TinyFish ranks on it
`attempts`	`3`	retries for a transient failure or an empty search (1–5)
`filters.domainType`	(unset)	`web` \| `news` \| `research_paper` — patch file only
`filters.language` / `.location`	(unset)	geo targeting — patch file only
`filters.includeDomains` / `.excludeDomains`	(unset)	comma-separated — patch file only
`monidBase` / `searchBase` / `fetchBase`	upstream	endpoint override, for staging
`search` / `fetch`	`true`	provide this kind; `false` reports it unavailable without unregistering

Turning one off reports unavailable rather than missing — the harness tells those apart, and only the second means "the install is broken". But unavailable is not a silent fall-through: if searchProvider/fetchProvider still names TinyFish, the call fails. Point that tool at another provider to use one.

- id: dsh-tinyfish
  config:
    search: true
    fetch: false # TinyFish stays registered but unavailable for fetch; point fetchProvider elsewhere to use another fetch

Filters live in the patch file

filters is a nested object, and the settings form addresses one flat key per field — so search tuning stays operator-level:

- id: dsh-tinyfish
  config:
    channel: monid
    filters:
      domainType: research_paper
      language: zh
      includeDomains: arxiv.org,openreview.net

Where a credential comes from

Resolved per call — a rotated key takes effect on the next search, no restart. First match wins:

the apiKey literal in the row (a secret in config; prefer 2–3)
the credentials service — apiKeyEnv (direct) or monidKeyEnv (monid), saved from the settings UI
the launch environment (exported before DSH started)
the live environment (MONID_API_KEY / TINYFISH_API_KEY)
the channel's CLI store (monid keys add / tinyfish auth login)

A failing service falls through to the next source rather than failing the search.

Where an endpoint comes from

Row, then environment, then built-in default — so staging can retarget without a patch:

setting	environment variable
`monidBase`	`TINYFISH_MONID_BASE_URL`
`searchBase`	`TINYFISH_SEARCH_BASE_URL`
`fetchBase`	`TINYFISH_FETCH_BASE_URL`

🔍 Behaviour worth knowing

A 404 is a result, not an error. A per-URL fetch failure comes back carrying its status, because that is resource state the model needs.
publishedAt is honest. TinyFish reports human dates ("Apr 30, 2026", "1 year ago"). What parses becomes ISO-8601; what doesn't is dropped, never invented. Unzoned dates read as UTC, so the same page reports the same day everywhere.
Empty searches retry. The upstream answers a valid query with nothing about one run in three — a blank result is retried up to attempts before it is believed.
A blocked run is terminal. If a Monid workspace control stops a run, the error says why and links to top up. Never retried.
Off means unavailable, not gone. A switched-off kind stays registered and declines. If the profile still pins that tool to Tinyfish, the call fails loudly instead of silently rerouting — point the tool at another provider to use one. With nothing pinned, a withdrawn Tinyfish simply yields: auto-select picks whoever is left, and switching one kind off is how you resolve an "ambiguous provider" standoff down to a single candidate.
Unavailable has three causes and one message. The seam only sees a boolean, so "switched off", "no credential", and "bad base URL" all read the same downstream. The card can tell them apart — check the switches, the key badges, and the endpoint overrides there.
purpose is one sentence for every fetch. The seam's fetch request carries a URL and nothing else — no goal slot, by design — so a per-call goal is impossible without a harness change. The configured sentence is attached to each fetch verbatim: a standing bias, not a per-task instruction.

TinyFish's agent and browser surfaces are not exposed: metered, wallet-billed, and not a search or a fetch. Use the tinyfish CLI directly when a page genuinely needs a real browser.

🛠 Development

The toolchain is Vite+: vp pack builds with tsdown, vp test runs Vitest, vp lint / vp fmt are Oxlint and Oxfmt, type-aware. Lint and format live in vite.config.ts — Vite+ ignores standalone configs.

pnpm install
pnpm test               # hermetic — no network, no credential
pnpm run check          # format + lint + types
pnpm run release:gate   # build, then the full gate incl. 18 package checks
pnpm run test:live      # the real APIs, still $0, needs credentials

Requires DSH ^0.2.0-rc.1 (0.2.0-rc.1 and later, below 0.3.0) and Node 24+. Full process and invariants: AGENTS.md. Contributing: CONTRIBUTING.md.

License

MIT

dsh-tinyfish

Install

Source

Tags

Creators

Readme

dsh-tinyfish

🚀 Quick start

Method 1: Direct from Web UI (Recommended)

Method 2: Terminal / Profile `package.json`

🔑 Two channels, one plugin

⚙️ Settings page

Filters live in the patch file

Where a credential comes from

Where an endpoint comes from

License

Install

Source

Tags

Creators

Readme

dsh-tinyfish

🚀 Quick start

Method 1: Direct from Web UI (Recommended)

Method 2: Terminal / Profile package.json

🔑 Two channels, one plugin

⚙️ Settings page

Filters live in the patch file

Where a credential comes from

Where an endpoint comes from

License

Method 2: Terminal / Profile `package.json`