English | 简体中文 | 日本語

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
Every provider takes the query or nothing	Standing defaults — domain, language, recency, date bounds, cache TTL, selectors

📊 How it compares

Need	Use	Cost
Search and fetch inside the native tools, free	dsh-tinyfish, either channel	$0 — a TinyFish key on direct, your platform key on Monid; identical payloads
The shipped defaults	deepseek-official + http	Search bills per call; fetched HTML pays a turndown conversion
Provider-specific SERP detail (geo, volume, rank) or bulk queries	A Monid SERP mirror via monid_run	Roughly $0.002–$0.18 per call, provider-dependent — only when the task needs that detail
Pages fetch cannot read (JS-heavy, login, interaction)	tinyfish agent / browser from the CLI	Metered ($0.016/step, $0.002/min) — escalate only from an empty fetch

🚀 Quick start

Method 1: Direct from Web UI (Recommended)

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

1. Open DSH Web and choose Plugins in the sidebar (插件).
2. Click Add plugin (添加插件).
3. Enter the package name dsh-tinyfish (or @viztor/dsh-tinyfish) — it is a free-text field, not a registry search.
4. Click Install — DSH fetches the package from npm and loads the bundle patch it declares. A live profile (the shipped Web one mounts HMR) applies the change at once; otherwise DSH says it takes effect at the next start.
5. On that Plugins page, open the Tinyfish card: select your channel (direct or monid), enter the key — or both keys — and hit Save!
6. That is the whole install — the bundle points the web path at TinyFish on both kinds. See Select it to choose otherwise.
7. Ask your agent something current; live sources come back. The result does not name the provider — a failure does, and names tinyfish.

---

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 ship the same built 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. The scoped tarball's manifest and patch name differ, so the loader can resolve it under the scope. 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.11.0" },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-tinyfish",
      ],
    },
  },
}

Bundles installed through package.json resolve at boot, so restart DSH here — reloading the patch alone won't load them.

Add a key — pick a channel below and save it, then ask your agent something current (who won the last Formula 1 race?). Live sources coming back is the proof the row validated and a credential resolved; the result itself does not name the provider, so confirm the pin in your profile patch (searchProvider / fetchProvider) — or provoke a failure, whose message does name tinyfish.

Select it

The bundle selects TinyFish on both web kinds by default, so a fresh install works with no patch editing. It does that by setting the web seam's searchProvider / fetchProvider, matched by row id. That is the only route a plugin has: dsh-web resolves those two fields once in its constructor and exposes no API by which a provider could elect itself.

To choose differently, override it in the profile's cordis.patch.yml, which applies after every bundle patch and therefore wins:

- id: web
  config:
    searchProvider: deepseek-official
    fetchProvider: http

The two kinds are independent fields, so search can run through TinyFish while fetch stays on the shipped http provider, or the other way round. The plugin stays mounted and idle either way. A host can also set DSH_WEB_SEARCH_PROVIDER / DSH_WEB_FETCH_PROVIDER — those feed the same fields, with the config value winning when both are present, which on a stock profile means the shipped base patch always wins.

🔑 Two channels, one plugin

Feature	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.

⚙️ Plugins card

Plugins → Tinyfish. Everything you can edit from the GUI lives here: whether TinyFish answers search and fetch, the channel picker, your keys, what the search ranks on, and attempts. 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; the Monid field's hint names its reference, and the Direct field's reference is printed on the description line beneath it — so you can set the Monid key while Direct is selected, and tell which of the two exists without switching back and forth.

This row configures how TinyFish behaves; it does not select it. The bundle already points searchProvider/fetchProvider at tinyfish, so a fresh install is on the web path with no patch editing — override those two fields in your own patch layer to use something else. See Select it.

📖 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 reference
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 sent with every search and fetch; TinyFish ranks on it; capped at 2000 characters
attempts	3	total tries for a transient failure or an empty search (1–5); 3 means at most 2 retries
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
filters.recencyMinutes	(unset)	freshness window in minutes (1–5256000); mutually exclusive with .afterDate upstream — patch file only
filters.afterDate	(unset)	lower date bound, YYYY-MM-DD; not for research_paper — patch file only
filters.pubYearMin	(unset)	lower publication-year bound (0–9999), research_paper only — patch file only
fetchOptions.ttl	(unset)	cache tolerance in seconds; 0 forces a live fetch, unset accepts any cache — patch file only
fetchOptions.perUrlTimeoutMs	(unset)	per-URL wall-clock budget in ms (1–110000) — patch file only
fetchOptions.excludeSelectors	(unset)	comma-separated CSS selectors pruned before extraction (1–20 × ≤1000 chars); direct PDF/CSV downloads reject it — 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

Manifest metadata, not configuration

The manifest also carries dsh.compatibility: the Node and DSH ranges stated explicitly, plus a per-release verdict — compatible, incompatible, or unknown — for the DSH versions a catalog checks.

DSH itself never reads it. No harness code reads dsh.compatibility, and the dshReleases map appears nowhere in the harness, so these fields cannot change how the plugin loads, registers, or behaves. DSH's own compatibility machinery is a separate thing: the loader checks peerDependencies, and exemptions live in the profile's compatibility.json. These fields exist so a listing can state what has actually been verified, and the verdicts here are honest rather than aspirational: 0.2.0-rc.2 is what every build and test in this repository runs against, 0.2.0-rc.1 is admitted by the peer range but never exercised, and 0.1.7-rc.2 sits below that floor.

Filters and fetch options live in the patch file

filters and fetchOptions are nested objects, and the settings form addresses one flat key per field — so search and fetch tuning stays operator-level:

- id: dsh-tinyfish
  config:
    channel: monid
    filters:
      domainType: research_paper
      language: zh
      includeDomains: arxiv.org,openreview.net
      pubYearMin: 2023
    fetchOptions:
      ttl: 0 # force a live fetch instead of accepting a cached page
      excludeSelectors: nav, .cookie-banner

Both sections always resolve: an unset one is an empty group that adds nothing to the request, and an unusable member degrades to unset rather than travelling upstream. Three upstream caveats pass through as documented behaviour instead of being enforced:

• recencyMinutes and afterDate are mutually exclusive in TinyFish's API; a row setting both sends both.
• excludeSelectors cannot apply to direct PDF/CSV downloads, which answer selector_unsupported while it is set.
• Upstream cross-checks each date bound against domainType: recencyMinutes and afterDate are refused for research_paper, pubYearMin exists only for it, and either wrong pairing rejects the whole search while set.

Where a credential comes from

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

1. the apiKey literal in the row (a secret in config; prefer 2–3)
2. the credentials service — apiKeyEnv (direct) or monidKeyEnv (monid), saved from the settings UI
3. the launch environment (exported before DSH started)
4. the live environment — the configured ref name first (apiKeyEnv / monidKeyEnv, which may name a variable of your own), then MONID_API_KEY / MONID_MCP_TOKEN / TINYFISH_API_KEY (either Monid variable covers the monid channel)
5. 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. A date-only value with no zone reads as UTC, so the same page reports the same day everywhere; a value carrying a clock time is parsed as given.
• Empty searches retry. The upstream answers a valid query with nothing about one run in three — a blank result is retried until the attempt budget (attempts, total tries) runs out 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 and the key badges there, and the endpoint overrides in the row or the environment.
• purpose is one sentence for every request. The seam's requests carry no goal slot — {query} for search, {url} for fetch — so a per-call goal is impossible without a harness change. The configured sentence rides every search and 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. the 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