diff --git a/website/docs/integrations/providers.md b/website/docs/integrations/providers.md index 22deca6381..c0eaf6e624 100644 --- a/website/docs/integrations/providers.md +++ b/website/docs/integrations/providers.md @@ -49,6 +49,10 @@ The OpenAI Codex provider authenticates via device code (open a URL, enter a cod Even when using Nous Portal, Codex, or a custom endpoint, some tools (vision, web summarization, MoA) use a separate "auxiliary" model — by default Gemini Flash via OpenRouter. An `OPENROUTER_API_KEY` enables these tools automatically. You can also configure which model and provider these tools use — see [Auxiliary Models](/docs/user-guide/configuration#auxiliary-models). ::: +:::tip Nous Tool Gateway +Paid Nous Portal subscribers also get access to the **[Tool Gateway](/docs/user-guide/features/tool-gateway)** — web search, image generation, TTS, and browser automation routed through your subscription. No extra API keys needed. It's offered automatically during `hermes model` setup, or enable it later with `hermes tools`. +::: + ### Two Commands for Model Management Hermes has **two** model commands that serve different purposes: diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index aa0acd8c7a..c4d4a11faa 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -110,6 +110,17 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe | `WANDB_API_KEY` | RL training metrics ([wandb.ai](https://wandb.ai/)) | | `DAYTONA_API_KEY` | Daytona cloud sandboxes ([daytona.io](https://daytona.io/)) | +### Nous Tool Gateway + +These variables configure the [Tool Gateway](/docs/user-guide/features/tool-gateway) for paid Nous subscribers or self-hosted gateway deployments. Most users don't need to set these — the gateway is configured automatically via `hermes model` or `hermes tools`. + +| Variable | Description | +|----------|-------------| +| `TOOL_GATEWAY_DOMAIN` | Base domain for Tool Gateway routing (default: `nousresearch.com`) | +| `TOOL_GATEWAY_SCHEME` | HTTP or HTTPS scheme for gateway URLs (default: `https`) | +| `TOOL_GATEWAY_USER_TOKEN` | Auth token for the Tool Gateway (normally auto-populated from Nous auth) | +| `FIRECRAWL_GATEWAY_URL` | Override URL for the Firecrawl gateway endpoint specifically | + ## Terminal Backend | Variable | Description | diff --git a/website/docs/user-guide/features/browser.md b/website/docs/user-guide/features/browser.md index 016f29f7c0..9880965ae4 100644 --- a/website/docs/user-guide/features/browser.md +++ b/website/docs/user-guide/features/browser.md @@ -33,6 +33,10 @@ Key capabilities: ## Setup +:::tip Nous Subscribers +If you have a paid [Nous Portal](https://portal.nousresearch.com) subscription, you can use browser automation through the **[Tool Gateway](tool-gateway.md)** without any separate API keys. Run `hermes model` or `hermes tools` to enable it. +::: + ### Browserbase cloud mode To use Browserbase-managed cloud browsers, add: diff --git a/website/docs/user-guide/features/image-generation.md b/website/docs/user-guide/features/image-generation.md index a782630b19..eea563c441 100644 --- a/website/docs/user-guide/features/image-generation.md +++ b/website/docs/user-guide/features/image-generation.md @@ -11,6 +11,10 @@ Hermes Agent can generate images from text prompts using FAL.ai's **FLUX 2 Pro** ## Setup +:::tip Nous Subscribers +If you have a paid [Nous Portal](https://portal.nousresearch.com) subscription, you can use image generation through the **[Tool Gateway](tool-gateway.md)** without a FAL API key. Run `hermes model` or `hermes tools` to enable it. +::: + ### Get a FAL API Key 1. Sign up at [fal.ai](https://fal.ai/) diff --git a/website/docs/user-guide/features/overview.md b/website/docs/user-guide/features/overview.md index 2d26e153ae..3838b715b8 100644 --- a/website/docs/user-guide/features/overview.md +++ b/website/docs/user-guide/features/overview.md @@ -10,6 +10,7 @@ Hermes Agent includes a rich set of capabilities that extend far beyond basic ch ## Core +- **[Nous Tool Gateway](tool-gateway.md)** — Paid Nous Portal subscribers can route web search, image generation, text-to-speech, and browser automation through the Tool Gateway — no separate API keys needed. Enable it with `hermes model` or `hermes tools`. - **[Tools & Toolsets](tools.md)** — Tools are functions that extend the agent's capabilities. They're organized into logical toolsets that can be enabled or disabled per platform, covering web search, terminal execution, file editing, memory, delegation, and more. - **[Skills System](skills.md)** — On-demand knowledge documents the agent can load when needed. Skills follow a progressive disclosure pattern to minimize token usage and are compatible with the [agentskills.io](https://agentskills.io/specification) open standard. - **[Persistent Memory](memory.md)** — Bounded, curated memory that persists across sessions. Hermes remembers your preferences, projects, environment, and things it has learned via `MEMORY.md` and `USER.md`. diff --git a/website/docs/user-guide/features/tool-gateway.md b/website/docs/user-guide/features/tool-gateway.md new file mode 100644 index 0000000000..4d549f067b --- /dev/null +++ b/website/docs/user-guide/features/tool-gateway.md @@ -0,0 +1,183 @@ +--- +title: "Nous Tool Gateway" +description: "Route web search, image generation, text-to-speech, and browser automation through your Nous subscription — no extra API keys needed" +sidebar_label: "Tool Gateway" +sidebar_position: 2 +--- + +# Nous Tool Gateway + +The **Tool Gateway** lets paid [Nous Portal](https://portal.nousresearch.com) subscribers use web search, image generation, text-to-speech, and browser automation through their existing subscription — no need to sign up for separate API keys from Firecrawl, FAL, OpenAI, or Browser Use. + +## What's Included + +| Tool | What It Does | Direct Alternative | +|------|--------------|--------------------| +| **Web search & extract** | Search the web and extract page content via Firecrawl | `FIRECRAWL_API_KEY`, `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY` | +| **Image generation** | Generate images via FAL (FLUX 2 Pro + upscaling) | `FAL_KEY` | +| **Text-to-speech** | Convert text to speech via OpenAI TTS | `VOICE_TOOLS_OPENAI_KEY`, `ELEVENLABS_API_KEY` | +| **Browser automation** | Control cloud browsers via Browser Use | `BROWSER_USE_API_KEY`, `BROWSERBASE_API_KEY` | + +All four tools bill to your Nous subscription. You can enable any combination — for example, use the gateway for web and image generation while keeping your own ElevenLabs key for TTS. + +## Eligibility + +The Tool Gateway is available to **paid** Nous Portal subscribers. Free-tier accounts do not have access. + +To check your status: + +```bash +hermes status +``` + +Look for the **Nous Tool Gateway** section. It shows which tools are active via the gateway, which use direct keys, and which aren't configured. + +## Enabling the Tool Gateway + +### During model setup + +When you run `hermes model` and select Nous Portal as your provider, Hermes automatically offers to enable the Tool Gateway: + +``` +Your Nous subscription includes the Tool Gateway. + + The Tool Gateway gives you access to web search, image generation, + text-to-speech, and browser automation through your Nous subscription. + No need to sign up for separate API keys — just pick the tools you want. + + ○ Web search & extract (Firecrawl) — not configured + ○ Image generation (FAL) — not configured + ○ Text-to-speech (OpenAI TTS) — not configured + ○ Browser automation (Browser Use) — not configured + + ● Enable Tool Gateway + ○ Skip +``` + +Select **Enable Tool Gateway** and you're done. + +If you already have direct API keys for some tools, the prompt adapts — you can enable the gateway for all tools (your existing keys are kept in `.env` but not used at runtime), enable only for unconfigured tools, or skip entirely. + +### Via `hermes tools` + +You can also enable the gateway tool-by-tool through the interactive tool configuration: + +```bash +hermes tools +``` + +Select a tool category (Web, Browser, Image Generation, or TTS), then choose **Nous Subscription** as the provider. This sets `use_gateway: true` for that tool in your config. + +### Manual configuration + +Set the `use_gateway` flag directly in `~/.hermes/config.yaml`: + +```yaml +web: + backend: firecrawl + use_gateway: true + +image_gen: + use_gateway: true + +tts: + provider: openai + use_gateway: true + +browser: + cloud_provider: browser-use + use_gateway: true +``` + +## How It Works + +When `use_gateway: true` is set for a tool, the runtime routes API calls through the Nous Tool Gateway instead of using direct API keys: + +1. **Web tools** — `web_search` and `web_extract` use the gateway's Firecrawl endpoint +2. **Image generation** — `image_generate` uses the gateway's FAL endpoint +3. **TTS** — `text_to_speech` uses the gateway's OpenAI Audio endpoint +4. **Browser** — `browser_navigate` and other browser tools use the gateway's Browser Use endpoint + +The gateway authenticates using your Nous Portal credentials (stored in `~/.hermes/auth.json` after `hermes model`). + +### Precedence + +Each tool checks `use_gateway` first: + +- **`use_gateway: true`** → route through the gateway, even if direct API keys exist in `.env` +- **`use_gateway: false`** (or absent) → use direct API keys if available, fall back to gateway only when no direct keys exist + +This means you can switch between gateway and direct keys at any time without deleting your `.env` credentials. + +## Switching Back to Direct Keys + +To stop using the gateway for a specific tool: + +```bash +hermes tools # Select the tool → choose a direct provider +``` + +Or set `use_gateway: false` in config: + +```yaml +web: + backend: firecrawl + use_gateway: false # Now uses FIRECRAWL_API_KEY from .env +``` + +When you select a non-gateway provider in `hermes tools`, the `use_gateway` flag is automatically set to `false` to prevent contradictory config. + +## Checking Status + +```bash +hermes status +``` + +The **Nous Tool Gateway** section shows: + +``` +◆ 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 + Modal ○ available via subscription (optional) +``` + +Tools marked "active via Nous subscription" are routed through the gateway. Tools with their own keys show which provider is active. + +## Advanced: Self-Hosted Gateway + +For self-hosted or custom gateway deployments, you can override the gateway endpoints via environment variables in `~/.hermes/.env`: + +```bash +TOOL_GATEWAY_DOMAIN=nousresearch.com # Base domain for gateway routing +TOOL_GATEWAY_SCHEME=https # HTTP or HTTPS (default: https) +TOOL_GATEWAY_USER_TOKEN=your-token # Auth token (normally auto-populated) +FIRECRAWL_GATEWAY_URL=https://... # Override for the Firecrawl endpoint specifically +``` + +These env vars are always visible in the configuration regardless of subscription status — they're useful for custom infrastructure setups. + +## FAQ + +### Do I need to delete my existing API keys? + +No. When `use_gateway: true` is set, the runtime skips direct API keys and routes through the gateway. Your keys stay in `.env` untouched. If you later disable the gateway, they'll be used again automatically. + +### Can I use the gateway for some tools and direct keys for others? + +Yes. The `use_gateway` flag is per-tool. You can mix and match — for example, gateway for web and image generation, your own ElevenLabs key for TTS, and Browserbase for browser automation. + +### What if my subscription expires? + +Tools that were routed through the gateway will stop working until you renew or switch to direct API keys via `hermes tools`. + +### Does the gateway work with the messaging gateway? + +Yes. The Tool Gateway routes tool API calls regardless of whether you're using the CLI, Telegram, Discord, or any other messaging platform. It operates at the tool runtime level, not the entry point level. + +### Is Modal included? + +Modal (serverless terminal backend) is available as an optional add-on through the Nous subscription. It's not enabled by the Tool Gateway prompt — configure it separately via `hermes setup terminal` or in `config.yaml`. diff --git a/website/docs/user-guide/features/tools.md b/website/docs/user-guide/features/tools.md index 0adec6f064..2283c16fb4 100644 --- a/website/docs/user-guide/features/tools.md +++ b/website/docs/user-guide/features/tools.md @@ -31,6 +31,10 @@ High-level categories: For the authoritative code-derived registry, see [Built-in Tools Reference](/docs/reference/tools-reference) and [Toolsets Reference](/docs/reference/toolsets-reference). +:::tip Nous Tool Gateway +Paid [Nous Portal](https://portal.nousresearch.com) subscribers can use web search, image generation, TTS, and browser automation through the **[Tool Gateway](tool-gateway.md)** — no separate API keys needed. Run `hermes model` to enable it, or configure individual tools with `hermes tools`. +::: + ## Using Toolsets ```bash diff --git a/website/docs/user-guide/features/tts.md b/website/docs/user-guide/features/tts.md index 625e25ad9e..7d864eddd5 100644 --- a/website/docs/user-guide/features/tts.md +++ b/website/docs/user-guide/features/tts.md @@ -8,6 +8,10 @@ description: "Text-to-speech and voice message transcription across all platform Hermes Agent supports both text-to-speech output and voice message transcription across all messaging platforms. +:::tip Nous Subscribers +If you have a paid [Nous Portal](https://portal.nousresearch.com) subscription, OpenAI TTS is available through the **[Tool Gateway](tool-gateway.md)** without a separate OpenAI API key. Run `hermes model` or `hermes tools` to enable it. +::: + ## Text-to-Speech Convert text to speech with six providers: diff --git a/website/sidebars.ts b/website/sidebars.ts index c72f3e61d6..b1f7fcf59a 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -36,6 +36,7 @@ const sidebars: SidebarsConfig = { collapsed: true, items: [ 'user-guide/features/overview', + 'user-guide/features/tool-gateway', { type: 'category', label: 'Core',