> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OGX

> Nimble is a built-in web_search provider in OGX, the open agentic API server: grounded, live web search for any model it serves.

### Overview

[OGX](https://github.com/ogx-ai/ogx) is an open, production-ready agentic API server and the successor to Llama Stack. It runs the agentic loop (inference, tool calling, RAG, and conversation management) behind the native APIs of OpenAI, Anthropic, and Google.

Nimble ships as the `remote::nimble-search` provider, registered under the `builtin::websearch` toolgroup alongside the other web search backends. When a model calls the `web_search` tool, OGX routes the request to Nimble's [Search API](/nimble-sdk/web-tools/search) and returns ranked, grounded results with source URLs. No fork, no plugin.

The provider ships in **OGX v1.1.0 and later**.

### Web search for any model

Any model OGX serves can search the web through Nimble, with no model-specific code. A `web_search` tool call resolves to `builtin::websearch`, which dispatches to the registered `remote::nimble-search` provider automatically.

Nimble handles anti-bot evasion, JavaScript rendering, and geo-targeting underneath, so the model gets back clean, ranked results to ground its answer in.

### Quick Start

#### 1. Get a Nimble API key

Get your API key from [Nimble's dashboard](https://online.nimbleway.com/account-settings/api-keys) (free trial available) and export it in the environment OGX runs in:

```bash theme={"system"}
export NIMBLE_API_KEY="your-api-key"
```

#### 2. Register the provider and start OGX

Add Nimble to the `tool_runtime` section of your distribution config (for example, the `starter` distribution):

```yaml theme={"system"}
tool_runtime:
  - provider_id: nimble-search
    provider_type: remote::nimble-search
    config:
      api_key: ${env.NIMBLE_API_KEY:=}
      max_results: 3
      search_depth: lite
      country: US
      locale: en
```

Then start the server:

```bash theme={"system"}
ogx run starter
```

On boot, OGX auto-registers the toolgroup: `provider_id=nimble-search toolgroup_id=builtin::websearch`.

#### 3. Search the web from a model

Call the Responses API with the `web_search` tool enabled. OGX routes the call through `builtin::websearch` to Nimble:

```bash theme={"system"}
curl http://localhost:8321/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "input": "What were the biggest AI model releases this month? Cite your sources.",
    "tools": [{"type": "web_search"}],
    "stream": false
  }'
```

The response contains a `web_search_call` item (status `completed`), followed by an assistant message grounded in live Nimble results with source URLs.

### Configuration

The `remote::nimble-search` provider accepts these keys under `config`:

<AccordionGroup>
  <Accordion title="api_key" icon="key">
    **Required.** Your Nimble API key. Provide it once via the `NIMBLE_API_KEY` environment variable (referenced as `${env.NIMBLE_API_KEY:=}`), or per request via the `X-OGX-Provider-Data` header:

    ```json theme={"system"}
    {"nimble_search_api_key": "your-api-key"}
    ```

    A per-request header value overrides the configured key.
  </Accordion>

  <Accordion title="max_results" icon="list-ol">
    **Optional.** Maximum number of results to return. Defaults to `3`.
  </Accordion>

  <Accordion title="search_depth" icon="layer-group">
    **Optional.** Controls the speed-vs-richness tradeoff. Defaults to `lite`.

    * `lite`: titles, URLs, and snippets. Lowest latency, best for broad discovery.
    * `deep`: full real-time page extraction for each result. Higher latency, richer content, and may require a higher Nimble tier. If your account lacks it, the provider returns a clear "tier not enabled" message rather than failing.

    See [Search Depth](/nimble-sdk/web-tools/search-depth) for details.
  </Accordion>

  <Accordion title="country" icon="globe">
    **Optional.** ISO-2 country code for geo-targeted results (e.g. `US`, `GB`). Defaults to `US`. Can also be set per request via the model's location hint.
  </Accordion>

  <Accordion title="locale" icon="language">
    **Optional.** Language/locale code for results (e.g. `en`). Defaults to `en`.
  </Accordion>
</AccordionGroup>

### Using Nimble over MCP (alternative)

On an OGX release earlier than v1.1.0, or if you prefer an MCP-based setup, OGX can reach Nimble through its built-in Model Context Protocol support, with no provider configuration needed. Point a Responses `mcp` tool at Nimble's hosted MCP server:

```bash theme={"system"}
curl http://localhost:8321/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "input": "What are the latest changes to the EU AI Act? Search the web and cite sources.",
    "tools": [{
      "type": "mcp",
      "server_label": "nimble",
      "server_url": "https://mcp.nimbleway.com/mcp",
      "authorization": "your-api-key"
    }],
    "stream": false
  }'
```

Pass the raw API key in the tool's `authorization` field. OGX adds the `Bearer` prefix itself. The hosted server exposes the `nimble_search` tool alongside Nimble's other capabilities. See the [Nimble MCP server docs](/integrations/mcp-server/mcp-server) for the full tool list and authentication details.

### Additional Resources

<CardGroup cols={2}>
  <Card title="OGX on GitHub" icon="github" href="https://github.com/ogx-ai/ogx">
    The open agentic API server.
  </Card>

  <Card title="Nimble Search API" icon="magnifying-glass" href="/nimble-sdk/web-tools/search">
    The Search endpoint behind the provider: parameters and response format.
  </Card>

  <Card title="Nimble MCP Server" icon="plug" href="/integrations/mcp-server/mcp-server">
    Reach Nimble over the Model Context Protocol.
  </Card>

  <Card title="OGX Provider Docs" icon="book-open" href="https://ogx-ai.github.io/docs/providers/tool_runtime/remote_nimble-search">
    The `remote::nimble-search` reference in OGX's own documentation.
  </Card>
</CardGroup>