mesh-configs/skills/autonomous-ai-agents/hermes-tool-gateway-config/references/nous-tool-gateway.md

# Nous Tool Gateway — Complete Reference

Source: https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway
Source: https://hermes-agent.nousresearch.com/docs/integrations/nous-portal

## What's Included

| Tool | Partner | What It Does |
|------|---------|--------------|
| **Web search & extract** | Firecrawl | Agent-grade search + full-page extraction. No rate limits — gateway handles scaling. |
| **Image generation** | FAL | 9 models under one endpoint (see Model IDs below). Default: `FLUX 2 Klein 9B`. |
| **Text-to-speech** | OpenAI TTS | High-quality TTS without separate OpenAI key. Enables voice mode. |
| **Cloud browser automation** | Browser Use | Headless Chromium for `browser_navigate`, `browser_click`, `browser_type`, `browser_vision`. No Browserbase account needed. |
| **Cloud terminal sandbox** | Modal | Serverless terminal sandboxes for code execution (optional add-on). |

## Billing

- Pay-as-you-use against your Nous subscription
- Mix & match — route some tools through Nous, keep your own keys for others
- Same quality — same backends, just fronted by Nous
- No lock-in — bring your own keys anytime, per-tool

## Eligibility

- **Paid subscription required** — Free-tier Nous accounts can use Portal for inference but **don't include managed tools**
- **Free tool pool** — Some accounts get a small managed-tool allowance covering gateway calls without a paid subscription. Gateway surfaces it with a setup prompt on first use.

## Setup Entry Points

```bash
# Fresh install: OAuth + set Nous as provider + enable gateway all at once
hermes setup --portal

# Switch inference provider to Nous Portal, then offered to enable gateway for all tools
hermes model

# À la carte: enable gateway per-tool, one at a time
hermes tools
```

**Key behavior:** `hermes tools` lists Nous-managed backends even if you've never signed in. Selecting one triggers Portal login inline — no need to run `hermes model` first. This path **only** logs you in and enables the single tool picked; it does **not** switch inference provider or prompt for other tools.

## Check Status

```bash
hermes portal info        # Portal auth + Tool Gateway routing summary
hermes portal tools       # Gateway catalog with current routing per tool
hermes status             # Full system status (Tool Gateway is one section)
```

**Example `hermes portal info` output:**
```
◆ Nous Tool Gateway
  Nous Portal     ✓ managed tools available
  Web tools       ✓ active via Nous subscription
  Image gen       ✓ active via Nous subscription
  TTS             ✓ active via Nous subscription
  Browser         ○ active via Browser Use key
```
- `✓ active via Nous subscription` = routed through gateway
- `○ active via [key]` = using your direct API key

## Mix & Match

| Strategy | Example |
|----------|---------|
| All through Nous | Easiest; one subscription, done |
| Gateway for web + images, own TTS | Keep ElevenLabs voice, Nous handles rest |
| Gateway only for missing keys | "I have Browserbase but no Firecrawl" |

**Switch anytime:**
```bash
hermes tools          # Interactive picker per tool category
```
Select tool → pick **Nous Subscription** (or any direct provider). No config editing. If not logged in, picking **Nous Subscription** kicks off Portal login inline.

## Image Model IDs

Default: `fal-ai/flux-2/klein/9b` (fast, good default). Override per-call by passing model ID to `image_generate`:

| Model | ID | Best For |
|-------|-----|----------|
| FLUX 2 Klein 9B | `fal-ai/flux-2/klein/9b` | Fast, good default |
| FLUX 2 Pro | `fal-ai/flux-2-pro` | Higher fidelity FLUX |
| Z-Image Turbo | `fal-ai/z-image/turbo` | Stylized, fast |
| Nano Banana Pro | `fal-ai/nano-banana-pro` | Google Gemini 3 Pro Image |
| GPT Image 1.5 | `fal-ai/gpt-image-1.5` | OpenAI image gen, text+image |
| GPT Image 2 | `fal-ai/gpt-image-2` | OpenAI latest |
| Ideogram V3 | `fal-ai/ideogram/v3` | Strong prompt adherence + typography |
| Recraft V4 Pro | `fal-ai/recraft/v4/pro/text-to-image` | Vector-style, graphic design |
| Qwen Image | `fal-ai/qwen-image` | Alibaba multimodal |

> **Live list:** `hermes tools` → Image Generation shows current models.

## Configuration Reference (config.yaml)

Most users never need this — `hermes model` and `hermes tools` cover all workflows. For scripting or direct edits:

### Per-Tool `use_gateway` Flag

```yaml
web:
  backend: firecrawl
  use_gateway: true

image_gen:
  use_gateway: true

tts:
  provider: openai
  use_gateway: true

stt:
  provider: openai
  use_gateway: true

browser:
  use_gateway: true
```

## Critical Note: Hermes 4 Models

> **Hermes 4 (Hermes-4-70B, Hermes-4-405B) is NOT recommended for use inside Hermes Agent.**
> - Tuned for **chat and reasoning**, not rapid-fire tool-calling loops
> - Use for: Nous Chat, research workflows, or via subscription proxy from other tooling
> - **For agent work, pick a frontier agentic model instead:**

```bash
/model anthropic/claude-sonnet-4.6     # best general-purpose agentic model
/model openai/gpt-5.5-pro              # strong reasoning + tool calling
/model google/gemini-3-pro-preview     # huge context window
/model deepseek/deepseek-v4-pro        # cost-effective coder
```

## Day-to-Day Usage

```bash
# Inspect what's wired up
hermes portal            # Log in + set up (alias for `hermes auth add nous --type oauth`)
hermes portal info       # Portal auth + Tool Gateway routing summary
hermes portal tools      # Gateway catalog with current routing per tool
hermes status            # Full system status (Tool Gateway is one section)
```

## OAuth Over SSH / Remote Hosts

See [OAuth over SSH / Remote Hosts](https://hermes-agent.nousresearch.com/docs/guides/oauth-over-ssh) — uses `ssh -L` port forwarding or `--manual-paste` for browser-only environments (Cloud Shell, Codespaces).

## Profile Setup

If using [Hermes profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles), the Portal refresh token is **automatically shared** across all profiles via shared token store. Sign in once, all profiles pick it up.