# TinyFish Cookbook: Sample Apps for the TinyFish Web Agent

> The TinyFish Cookbook is a MIT-licensed collection of TypeScript sample apps and recipes built on the TinyFish web agent, plus an installable agent skill and CLI. It is a starting point for teams that need agents to read or act on live web pages, not a framework you build on directly.

**tinyfish-io/tinyfish-cookbook** — A collection of sample apps and recipes built with the TinyFish web agent. Open-source examples for you to learn & build!

- Repository: https://github.com/tinyfish-io/tinyfish-cookbook
- Website: https://tinyfish.ai
- Stars: 2,201 · Forks: 337
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/tinyfish-io-tinyfish-cookbook

## What the TinyFish Cookbook is for

The repository collects sample applications and recipes built on TinyFish, described in the README as "the web layer for AI agents." The target reader is an engineer whose agent needs to search the live web, read a page as clean text, run a multi-step browser flow, or reach a site that exposes no API. Each recipe folder is a standalone project, so you read it, copy the parts you need, and adapt them.

The recipe list shows the intended range rather than a single use case. viet-bike-scout compares motorbike rental prices across Vietnamese cities using parallel browser agents. openbox-deals aggregates open-box and refurbished listings across eight retailers. silicon-signal tracks semiconductor supply chain signals such as lifecycle, availability and lead time. tutor-finder and summer-school-finder search education listings across multiple platforms. Most of these are comparison or aggregation problems where the source sites have no usable API, which is exactly the gap TinyFish sells against.

## Search, Fetch, Agent and Browser: four endpoints, two billing models

TinyFish exposes four endpoints layered by cost and control. Search (api.search.tinyfish.ai) returns structured JSON results and the README claims rank-stable output across calls, with a stated latency under 0.5s. Fetch (api.fetch.tinyfish.ai) turns any URL into clean markdown, JSON or HTML using full-browser rendering, and the README says failed URLs are free. Both are listed as free with generous rate limits and no credit card. Agent takes a URL plus a natural-language goal, navigates and acts, and returns JSON, at roughly 10 seconds to minutes per run, metered. Browser rents a managed cloud browser you drive with your own Playwright or Selenium scripts, also metered.

The design decision worth noting is that Fetch is positioned as a drop-in replacement for Firecrawl, a native LLM fetch tool, or hand-rolled Playwright. The README's argument is token efficiency: Fetch strips navigation, scripts and cookie banners, so you do not pay a model to read junk HTML. That is a real cost argument rather than a capability one, and it only holds if your pipeline was previously feeding raw page markup to a model. The repository does not publish a token-savings measurement, so treat the claim as a design intent rather than a benchmark.

Two features sit outside the endpoint table. Vault stores agent-grade credentials and session memory for authenticated workflows, with 1Password just-in-time access and encrypted session reuse named in the README. Stealth is bundled: rotating proxies and stealth profiles are included at no extra cost, which matters for sites that block datacenter traffic.

## Installing the TinyFish CLI and running your first search

The README gives install commands for the CLI, both SDKs and the agent skill. The CLI is published on npm as @tiny-fish/cli and installs globally. After installing, you authenticate, which writes credentials the later commands reuse.

```bash
npm install -g @tiny-fish/cli
tinyfish auth login
```

The README's stated advantage of the CLI over calling the API from inside an agent loop is that results land on the filesystem instead of passing through the model's context window. Two subcommands are shown: search query for retrieval and fetch content get for reading a single page.

```bash
tinyfish search query "web automation tools"
tinyfish fetch content get https://example.com
```

If you prefer the REST API directly, the README shows a GET against the search host with the key in an X-API-Key header. This is the same key used across all endpoints, so one environment variable covers the free and metered tiers alike.

```bash
curl "https://api.search.tinyfish.ai?query=web+automation+tools" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

For coding agents, the skill installs with a single npx command and teaches the agent when to choose Search, Fetch or Agent. The README lists Claude Code, Codex, Cursor, OpenCode, Antigravity and other MCP-aware clients as supported, and the MCP server is added by URL rather than by local process.

```bash
npx skills add github.com/tinyfish-io/tinyfish-cookbook --skill use-tinyfish
```

## The Makefile sets up pre-commit hooks, not the recipes

The repository's Makefile does not build or run any recipe. Its init target depends on setup-pre-commit and check-trufflehog, then installs pre-commit with pip and registers the hook. The setup target copies .github/config/.pre-commit-config-template.yaml into .pre-commit-config.yaml if that file does not already exist, and leaves an existing file alone.

The check-trufflehog target fails with instructions when the trufflehog binary is missing, suggesting brew install trufflehog on macOS or the upstream install script on Linux. This is contributor tooling for a repository that accepts external recipes, and it tells you something about the maintenance model: secret scanning is enforced before commits land. It also means make init will modify your local git hooks and install a Python tool, so run it only if you intend to contribute rather than merely read the samples. Each recipe folder is independent, and the README points to INSTALL.md and CONTRIBUTING.md for the details the top-level Makefile does not cover.

## Where the Cookbook is the wrong tool

This is a collection of examples, not a library. There are no releases in the repository metadata, so there is no versioned artifact to pin and no changelog of breaking changes beyond the CHANGELOG.md file at the top level. If you copy a recipe, you own the copy. Upstream fixes do not reach you through a package manager.

The metered endpoints are the second boundary. Search and Fetch are advertised as free, but Agent and Browser are billed, and the Agent endpoint's own description puts runs at roughly 10 seconds to minutes. A workflow that needs thousands of short, deterministic page fetches per hour is a poor fit for the Agent endpoint; Fetch is the right layer there, and Search is the right layer for discovery. Choosing Agent for work Fetch could do is the most likely way to overspend.

Finally, the recipes assume live third-party sites. viet-bike-scout, openbox-deals and the retail trackers depend on pages the repository does not control. When a target site changes its markup or blocks the traffic, the recipe breaks and the fix is yours. The README does not document a rollback path or a fallback for that case.

## Cookbook versus Firecrawl and hand-rolled Playwright

The README itself frames Fetch as a drop-in replacement for Firecrawl, a native LLM fetch tool, or hand-rolled Playwright. The difference is scope. Firecrawl is a scraping and crawling product you adopt as a dependency; its focus is turning sites into LLM-ready content. Hand-rolled Playwright is a browser automation library you run yourself, which means you also run the browsers, the proxies and the stealth configuration. TinyFish sits between them: Fetch and Search are hosted retrieval, while Browser lets you keep your existing Playwright or Selenium scripts and point them at a managed cloud browser.

That middle position is the actual trade-off. You give up control of the browser environment in exchange for not operating it, and you gain bundled rotating proxies and stealth profiles that would otherwise be your problem. If your compliance rules require browsers to run inside your own network, none of the hosted endpoints fit and Playwright on your own infrastructure remains the answer. If your only need is to read a handful of pages once, the free Fetch endpoint plus curl is less machinery than any of these.

## Licence and the cost of keeping up

The repository is MIT-licensed, and the README's licence badge links to the LICENSE file rather than naming the terms inline. MIT is permissive: you can copy recipe code into a commercial product, and the main obligation is preserving the copyright notice. That applies to the sample code in this repository. It does not extend to the TinyFish service itself, which is governed by separate terms on the vendor's site, and the SDKs and CLI are separately published packages with their own licence files. Nothing here is legal advice; read the LICENSE file and the service terms before shipping.

The last push to the repository was on 2026-08-31, which is recent enough that the samples track the current SDK. Renovate is configured at the top level, which suggests dependency updates are automated rather than manual. The upgrade cost you should budget for is not the repository: it is the API surface. When an endpoint changes shape, every recipe you copied needs the same edit, and no release note will tell you which of your copies is affected.

## Conclusion

Adopt the Cookbook if you want working reference code for Search, Fetch, Agent or Browser before writing your own integration, or if you want the use-tinyfish skill teaching your coding agent which endpoint to call. Skip it if you need a supported library with versioned releases: this is a sample collection, and the recipes are standalone folders you copy from rather than depend on. Verify first that Search and Fetch still carry the free tier the README advertises, and read INSTALL.md and CONTRIBUTING.md before running make init, because the Makefile installs pre-commit hooks and requires TruffleHog on your machine.

## FAQ

### What is an AI cookbook?

In this repository the term means a collection of sample apps and recipes built on the TinyFish web agent, each in its own folder as a standalone project. They are reference implementations you read and adapt, not a library you install.

### What does a cook book contain?

For the TinyFish Cookbook, the contents are recipe folders such as viet-bike-scout, openbox-deals, silicon-signal and tutor-finder, plus shared assets like a CLI, SDKs, an agent skill and contributor tooling in the Makefile.

### What is a coding cookbook?

The README describes this repository as a growing collection of recipes, demos and automations built on TinyFish, with each folder presented as a standalone project. The samples are written in TypeScript and several of them have live demos deployed on Vercel.

## Sources

- [Issues](https://github.com/tinyfish-io/tinyfish-cookbook/issues)
- [License: MIT](https://github.com/tinyfish-io/tinyfish-cookbook/blob/main/LICENSE)
- [Project website](https://tinyfish.ai)
- [README](https://github.com/tinyfish-io/tinyfish-cookbook/blob/main/README.md)
- [tinyfish-io/tinyfish-cookbook on GitHub](https://github.com/tinyfish-io/tinyfish-cookbook)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tinyfish-io-tinyfish-cookbook