Hermes TinyFish Plugin

TinyFish web search, content extraction, and optional credit-gated web automation for Hermes Agent.

This is an independent community plugin. It is not affiliated with, endorsed by, or maintained by TinyFish or Hermes / Nous Research.

TinyFish documentation currently describes Search and Fetch as free, and Agent and Browser as credit-consuming. This plugin treats Search and Fetch as the safe default entry point, but pricing and free-use assumptions are based only on current TinyFish docs and may change. Credit-risking features default to deny.

Install

Hermes Git plugin install:

hermes plugins install gabeosx/hermes-plugin-tinyfish --enable
hermes tinyfish setup

Python package install:

pip install hermes-plugin-tinyfish
hermes tinyfish setup

Safe Default Setup

hermes tinyfish setup configures TinyFish for Hermes web_search and web_extract only:

mcp_servers:
  tinyfish:
    url: https://agent.tinyfish.ai/mcp
    auth: oauth
    tools:
      include: [search, fetch_content]
      resources: false
      prompts: false

web:
  search_backend: tinyfish
  extract_backend: tinyfish

tinyfish:
  credit_policy:
    agent: deny
    browser: deny
    profile_setup: deny
    model_tools: deny

The plugin prefers TinyFish's hosted OAuth MCP server and falls back to REST with TINYFISH_API_KEY when MCP OAuth is unavailable. It may save TINYFISH_API_KEY to ~/.hermes/.env if you choose to add API-key fallback.

Verify the default Search/Fetch setup:

hermes tinyfish doctor
hermes tinyfish doctor --live

doctor --live performs only Search and Fetch checks.

Credit Policy

Credit-risking TinyFish capabilities are controlled independently:

hermes tinyfish credits status
hermes tinyfish credits set agent request
hermes tinyfish credits set browser allow
hermes tinyfish credits set profile-setup deny
hermes tinyfish credits set model-tools request
hermes tinyfish credits reset

Policies:

• deny: fail closed. This is the default.
• request: use Hermes' existing approval flow for each invocation.
• allow: run without per-invocation approval.

model-tools controls whether model-callable TinyFish Agent tools are exposed. Even when model-tools is enabled, agent must also be set to request or allow.

Optional Capabilities

Browser Provider

TinyFish Browser can be selected as a Hermes cloud browser provider after explicit opt-in:

browser:
  cloud_provider: tinyfish
tinyfish:
  credit_policy:
    browser: request

When selected, TinyFish-backed browser_* calls are gated by the browser credit policy.

Agent API

Run TinyFish goal-based automation from the CLI:

hermes tinyfish credits set agent request
hermes tinyfish agent run --url https://example.com --goal "Find the pricing"
hermes tinyfish agent run-async --url https://example.com --goal "Extract product names"
hermes tinyfish agent status <run_id>
hermes tinyfish agent cancel <run_id>

Browser Context Profiles

Manage persistent TinyFish Browser Context Profiles:

hermes tinyfish profiles list
hermes tinyfish profiles create --name "Example account"
hermes tinyfish credits set profile-setup request
hermes tinyfish profiles setup-session <profile_id>
hermes tinyfish profiles save-setup <profile_id> --session-id <session_id>
hermes tinyfish profiles cancel-setup <profile_id> --session-id <session_id>

Search and Fetch Options

Optional REST fallback defaults can be configured in config.yaml:

tinyfish:
  search:
    location: US
    language: en
    recency_minutes: 1440
    domain_type: web
    page: 0
  fetch:
    format: markdown
    links: false
    image_links: false
    ttl: 3600

MCP remains the preferred path when configured. These options apply to REST fallback calls.

Diagnostics

hermes tinyfish status
hermes tinyfish usage
hermes tinyfish doctor --live
hermes tinyfish doctor --live-paid

doctor --live-paid respects credit policy. It refuses under deny, prompts under request, and runs under allow.

Upgrade Safety

This plugin uses public Hermes extension points:

• ctx.register_web_search_provider(...)
• ctx.register_browser_provider(...)
• ctx.register_tool(...) for optional Agent tools
• ctx.register_hook("pre_tool_call", ...) for credit policy gates
• ctx.register_cli_command(...)
• Hermes MCP config under mcp_servers
• Hermes .env config helpers for optional API-key fallback

It does not patch Hermes Agent, update scripts, Dockerfiles, or files inside a Hermes installation or source checkout.

Development

python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
ruff format .
ruff check .
mypy hermes_plugin_tinyfish
pytest
python -m build

Live tests are opt-in:

TINYFISH_LIVE_TESTS=1 TINYFISH_API_KEY=... pytest tests/test_live.py

Maintainer Docs

• Release operations
• Compatibility testing
• User install smoke test
• Hermes extension points
• TinyFish integration notes

References

• TinyFish MCP Integration
• TinyFish Authentication
• TinyFish Search API
• TinyFish Fetch API
• TinyFish Agent API
• TinyFish Browser API
• TinyFish Browser Context Profiles
• Hermes Web Search Provider Plugins
• Hermes Browser Provider Plugins
• Hermes Plugins
• Hermes MCP