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

# Providers

> Provider choices, support status, and data-processing boundaries for Overlay Web.

Provider selection is controlled by runtime config v2 under `providers`, with backward-compatible mirrors in `auth`, `billing`, `storage`, `llm`, `database`, and `capabilities`.

Use `none` plus the matching feature flag when a provider family must be disabled. Disabled features are hidden from UI and blocked by server-side gates with `capability_disabled` responses.

## Core Providers

| Purpose | Values | Current support |
| - | - | - |
| Auth | `workos`, `better-auth`, `oidc`, `none` | `workos` is the hosted default. `better-auth` owns the web session and supports provider-driven enterprise SSO with its own separate Postgres database. `oidc` remains a low-level bearer/access-token verifier for deployment-specific browser wiring. |
| Billing | `stripe`, `none` | `stripe` supports subscriptions, top-ups, portal sessions, and webhooks. Use `none` for private deployments. |
| Object storage | `r2`, `s3`, `none` | `r2` is the hosted default. `s3` covers AWS S3 and compatible enterprise object stores. Keep compatible stores under `s3`; set `storage.s3.forcePathStyle=true` only when required. |
| Models | `openrouter`, `ai-gateway`, `openai`, `anthropic`, `groq`, `none` | All listed model providers have active routing paths except `none`, which intentionally disables generation. |
| Database | `convex` | `convex` is the only app-data provider and the hosted default. Enterprise self-hosting runs the official `convex-backend` binary; see [Self-hosted Convex backend](https://getoverlay.io/docs/self-hosting/install/self-hosted-convex.md). |

## Enterprise Provider Families

| Purpose | Values | Data processed | Current support |
| - | - | - | - |
| Vector search | `convex`, `pgvector`, `pinecone`, `none` | Embeddings and searchable text chunks | `convex` and `none` are supported. `pgvector` was removed with the Postgres app-data provider; `pinecone` is declared but rejected until an adapter exists. |
| Embeddings | `ai-gateway`, `openai`, `azure-openai`, `none` | Text chunks sent for embedding | `ai-gateway`, `openai`, and `none` are current paths. `azure-openai` is declared but rejected until implemented. |
| Integrations | `composio`, `executor`, `mcp`, `none` | Connected-account metadata and tool inputs/outputs | `composio`, `executor`, and `none` are supported. `executor` delegates OAuth and shared connection lifecycle to a customer-hosted Executor service. `mcp` is declared but rejected as a provider family until bootstrap wiring exists. |
| Sandboxes | `box`, `e2b`, `local-firecracker`, `none` | Commands, staged files, desktop sessions, and generated artifacts | `box` (Overlay Cloud, the default) and `none` are supported. `daytona` was removed. `e2b` is planned as the self-hosted provider and, like `local-firecracker`, is declared but rejected until an adapter exists. `vercel` is still accepted so older configs validate, but nothing uses it. |
| Web search | `elo`, `ai-gateway`, `perplexity`, `tavily`, `none` | Search queries, result snippets, and fetched page content | `elo` and `none` are supported. The backward-compatible `elo` setting routes `web_search` through TinyFish Search first with ELO/Tavily fallback. `deep_search` searches and reads source pages through TinyFish, with ELO/Parallel fallback; `web_fetch` uses TinyFish Fetch. Either `TINYFISH_API_KEY` or `ELO_API_KEY` enables search; Fetch requires TinyFish. `ai-gateway`, `perplexity`, and `tavily` are declared but rejected — the gateway search path was removed. |
| Analytics | `posthog`, `none` | Pageviews and product events | `posthog` and `none` are supported. Set feature and provider to disabled values to avoid SDK initialization. |
| Error reporting | `sentry`, `none` | Error events and sanitized stack/request metadata | `sentry` and `none` are supported. Set feature and provider to disabled values to avoid initialization. |
| Secrets | `env`, `workos-vault`, `aws-secrets-manager`, `vault`, `none` | Provider credentials | `env` is the general runtime path. `workos-vault` supports hosted BYOK flows. `aws-secrets-manager` supports BYOK provider keys for private deployments; Convex stores only the opaque secret ARN. Vault remains declared but unsupported. |
| Rate limit | `convex`, `memory`, `redis`, `none` | Rate-limit counters | All declared providers are supported. Multi-instance production/on-prem deployments should use Redis with fail-closed behavior; memory is development-only. |
| Transactional email | `resend`, `ses`, `smtp`, `none` | Recipient address and account email content | All are supported; the default is `none`. SMTP requires TLS in production. Delivery uses a durable outbox with suppression checks and audit records. |

## Disable External Processors

For a private deployment, disable high-risk external processors explicitly:

```json theme={null}
{
  "features": {
    "integrations": false,
    "sandboxes": false,
    "webSearch": false,
    "analytics": false,
    "errorReporting": false
  },
  "providers": {
    "integrations": { "provider": "none" },
    "sandbox": { "provider": "none" },
    "webSearch": { "provider": "none" },
    "analytics": { "provider": "none" },
    "errorReporting": { "provider": "none" }
  }
}
```

For strict deployments, combine this with `compliance.allowExternalProcessors=false` and allowlist only approved processors such as `models:openai` or `objectStorage:s3`.

## Vector Search

Vector search is opt-in. For deployments that do not need knowledge retrieval, keep:

```env theme={null}
OVERLAY_PROVIDER_VECTOR_SEARCH=none
VECTOR_SEARCH_ENABLED=false
OVERLAY_FEATURE_VECTOR_SEARCH=false
```

To enable memory and knowledge search, use `convex` vector search plus one supported embeddings provider (`ai-gateway` or `openai`). Convex performs indexing, model-versioned embeddings, scoped hybrid retrieval, and cleanup inside the deployment; no separate worker is required.

```env theme={null}
OVERLAY_PROVIDER_VECTOR_SEARCH=convex
OVERLAY_PROVIDER_EMBEDDINGS=openai
OVERLAY_EMBEDDING_MODEL_VERSION=text-embedding-3-small-v1
VECTOR_SEARCH_ENABLED=true
OVERLAY_FEATURE_VECTOR_SEARCH=true
```

## MCP server credentials

People can add their own MCP servers. Their tokens are encrypted with a key you provide. Generate it once:

```bash theme={null}
openssl rand -hex 32
```

Store it as `MCP_CREDENTIAL_ENCRYPTION_KEY` on the web runtime. During
rotation, place the old value in `MCP_CREDENTIAL_ENCRYPTION_KEY_PREVIOUS`, deploy
the new primary key, rewrite saved credentials through the management API, then
remove the previous key. MCP responses expose only `hasAuth`; bearer tokens and
custom header values are AES-256-GCM encrypted at rest and are never returned by
list APIs. Production MCP URLs must use HTTPS and pass Overlay's SSRF validation.

Each server has a default execution policy of `allow`, `approval_required`, or
`deny`, plus optional per-tool overrides. Use `approval_required` as the enterprise
default when a server contains write-capable tools. Tool name, argument hash,
policy decision, result status, duration, and request context are persisted for
audit without storing raw tool arguments.

### Deep search retrieval

TinyFish Search and Fetch provide source evidence; Overlay’s model synthesizes it with citations and can request follow-up searches. This does not call TinyFish’s separately billed Research API.

The `fast`, `standard`, and `deep` effort levels cap search queries at 2, 4, and 6 and fetched pages at 3, 6, and 20, respectively. Deep defaults to at most 10 pages unless `maxResults` requests more. Fetch requests contain at most 10 URLs; per-page time budgets are 15, 25, and 45 seconds, with a 60-second request deadline. Text budgets and domain/date filters still apply, and `maxAgeSeconds` maps to Fetch cache freshness.

Partial results retain readable pages and clearly label unfetched snippets. If no usable pages are available or TinyFish is unavailable, the tool falls back to Elo Parallel. Completed Search and Fetch requests count toward the existing per-call tool charge, including completed requests preceding an Elo fallback. At most six Search requests, two Fetch batches, and one Elo fallback fit within the existing reservation. Failed overall operations retain the reconciliation path.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.