Skip to main content

Context7 On-Premise keeps your repositories, generated documentation, application database, vector store, and MCP server in your infrastructure.

Two kinds of outside services receive data:

  • Your AI providers receive the content needed for parsing, embedding, reranking, and source-code documentation.
  • Context7 Cloud receives license checks, a daily usage report, and public library searches, but only with an online license. See Network and data flow.

What’s Included#

  • Full Context7 parsing and indexing pipeline
  • Local vector storage (no external vector DB required)
  • Built-in MCP server. Works with any MCP-compatible AI client
  • Web UI for managing indexed libraries and configuration
  • REST API compatible with the public Context7 API
  • Private GitHub and GitLab repository ingestion

On-Premise Architecture

Setup#

Request a trial

Go to context7.com/plans and click Learn More on the Enterprise plan, then click Request On-Premise Trial. Fill out the request form. No credit card required. You’ll receive a 30-day full-featured license key via email once approved.

Complete the setup wizard

Open http://localhost:3000 in your browser. On first launch, the setup wizard guides you through configuring:

  1. AI Provider - Choose OpenAI, Anthropic, Gemini, AWS Bedrock, or a custom OpenAI-compatible endpoint. Enter the provider credentials and model name.
  2. Embedding Provider - Use the same provider as your LLM, or configure a separate one for embeddings.
  3. Git Tokens - Add a GitHub and/or GitLab token for the platforms you use.

All configuration is stored locally in the embedded database and can be updated later in Workspace Settings.

Ingest your first repository

From the dashboard, click Add source, choose GitHub or GitLab, and enter the repository URL. Once ingestion completes, your private docs are ready to query.

You can also add libraries via the REST API with a personal API key (see Authentication):

Connecting Your AI Client#

The Context7 CLI is the recommended way to connect an AI coding agent. Install it once on the machine that runs your client:

For restricted or air-gapped environments, mirror the ctx7 package and its dependencies in your approved internal npm registry. Once installed, on-premise setup does not contact npm, GitHub, or Context7 Cloud. It uses bundled rule and skill content and contacts only your deployment to discover its MCP authentication setting.

Pass the root URL of your deployment (without /mcp or /api) and select the client:

Setup reads the deployment’s MCP authentication setting. When MCP authentication is disabled, no credential is written. When it is enabled, the dashboard’s Connect card presents two steps: sign in and click Create API key, then copy the command after the dashboard inserts the one-time-visible key. Select Configure manually to reveal the equivalent client-native configuration instead. If you run the base command without --api-key, the CLI requests the key with hidden input.

For non-interactive automation, provide the personal key through the environment:

You can use --api-key ctx7op-... instead, but command-line arguments may be retained in shell history. Setup writes the MCP client configuration, a Context7 rule, and a bundled context7-mcp skill. The bundled files mean the deployment does not need to expose Context7 Cloud’s skill APIs.

Note

Custom --base-url setup uses the deployment’s Streamable HTTP endpoint. Hosted OAuth, local stdio transport, and CLI-query mode are not available for on-premise targets.

Manual configuration#

If your client is not supported by ctx7 setup, point it at <deployment-root>/mcp. When MCP authentication is enabled, send the personal key as a standard bearer token:

For other clients, see All Clients.

Configuration#

Environment Variables#

These are set in your docker-compose.yml or .env file before starting the container.

VariableRequiredDescription
LICENSE_KEYYesLicense key issued by Upstash
PORTNoHTTP port (default: 3000)
DATA_DIRNoData directory inside the container (default: /data)
DATABASE_URLNoPostgres connection string. Without it, the embedded SQLite database in DATA_DIR is used. See Scaling
PG_POOL_MAXNoPostgres connection pool size per replica (default: 10)
ENCRYPTION_KEYNo64 hex characters (openssl rand -hex 32) that encrypt stored secrets. Without it, a key is generated in $DATA_DIR/.encryption-key. The variable wins over the file
VECTOR_STORENoauto (default), lancedb, pgvector, or milvus. See Vector Stores
VECTOR_DATABASE_URLNoPostgres connection string for pgvector, if it differs from DATABASE_URL
PG_VECTOR_POOL_MAXNopgvector connection pool size per replica (default: 5)
MILVUS_ADDRESS, MILVUS_TOKEN, MILVUS_USERNAME, MILVUS_PASSWORD, MILVUS_DATABASENoMilvus connection settings
CONTEXT7_API_URLNoBase URL for license checks, usage reports, and cloud library queries (default: https://context7.com/api)
NODE_EXTRA_CA_CERTSNoPath to a PEM bundle of extra CA certificates. The server trusts it for all outbound HTTPS, and git uses it too
GIT_TLS_INSECURENotrue or 1 turns off TLS verification for all outbound HTTPS and git. Use it only for testing
AWS_REGION, AWS_DEFAULT_REGION, AWS_BEARER_TOKEN_BEDROCK, standard AWS credential variablesNoAWS Bedrock authentication. See AWS Bedrock
LOG_MAX_SIZE_MBNoSize of the log file before it rotates (default: 10). Logs are JSONL in $DATA_DIR/logs/context7.jsonl
LOG_MAX_FILESNoNumber of rotated log files to keep (default: 3)
NOTION_REQUESTS_PER_MINUTENoNotion API rate (default: 180). The only other accepted value is 600
MAX_FILES, PARSE_CONCURRENCY, PARSE_TIMEOUT, NOTION_MAX_PAGES, GOOGLE_DRIVE_MAX_FILESNoDefault values for the parsing settings. A value saved in the dashboard wins
Note

Set AI providers, models, provider keys, and git tokens in the setup wizard. You can change them later in Workspace Settings. There are no environment variables for git tokens (such as GITHUB_TOKEN or GITLAB_TOKEN) or for provider API keys.

AWS Bedrock is the exception. It can also authenticate with AWS_BEARER_TOKEN_BEDROCK, the standard AWS credential variables, a mounted shared profile, or a workload IAM role. See AWS Bedrock.

AI Provider Settings#

Configured under Workspace Settings › AI models in the web UI.

SettingDescription
LLM Provideropenai, anthropic, gemini, bedrock, or custom
LLM API KeyAPI key for your chosen provider; optional for Bedrock with workload credentials
LLM ModelModel name or Bedrock model/inference-profile ID
AWS RegionRegion used for Bedrock LLM and embedding requests
Base URL / Bedrock endpointCustom OpenAI-compatible endpoint, or an optional Bedrock Runtime endpoint

Examples#

Embedding Settings#

By default, Context7 uses the same provider as your LLM for generating embeddings. Anthropic has no embedding models, so when the LLM provider is Anthropic, you must configure a separate embedding provider. With other providers, a separate embedding provider is optional.

SettingDescription
Embedding Provideropenai, gemini, bedrock, or custom
Embedding API KeySeparate key; inherits the LLM key only when both use the same provider
Embedding ModelEmbedding model name, such as text-embedding-3-small or amazon.titan-embed-text-v2:0
Embedding base URL / Bedrock endpointCustom embedding endpoint, or an optional Bedrock Runtime endpoint

See AWS Bedrock for IAM, model, region, and private-network configuration.

Decision Model#

Optionally, a decision model can classify pages, check for duplicate snippets, and rerank search results in place of the language model. It is faster and costs less for these yes/no decisions. See Decision Models to turn it on.

Parsing Settings#

Change these in Workspace Settings › Parsing. Some settings also have an environment variable. The variable only sets the default; a value saved in the dashboard wins.

The three count limits also have a No limit option: files per library, Notion pages, and Google Drive files. Setting their environment variable to 0 does the same. Without a limit, a very large source can take a long time and make many LLM calls. File timeout and the concurrency settings always have a limit.

The Max files per library setting with its list open and No limit selected

When a change takes effect:

  • Settings with an environment variable: at the next parse, on every replica.
  • Max concurrent parses, Max concurrent LLM requests, LLM timeout: at once on the replica that saves them. In a multi-replica deployment, other replicas use the new value after they restart.
SettingDefaultRangeEnv fallbackDescription
Max concurrent parses11–10—Parses each replica runs at the same time
Max concurrent LLM requests51–64—Requests in flight to the language model, shared by parsing and search
LLM timeout120 s30–1800 s—How long to wait for one model call. Each part of a page takes up to four calls in a row (a page check, then code, API and info extraction), so it may run up to four times this value
Max files per library5001–100000, or no limitMAX_FILESDocumentation files a repository parse reads, or pages a website or llms.txt parse keeps. Extra files are skipped and logged
Files parsed in parallel51–64PARSE_CONCURRENCYFiles one parse processes at the same time
File timeout500 s30–3600 sPARSE_TIMEOUTHow long one file may take. The parse skips a file that takes longer
Max pages per Notion library100001–100000, or no limitNOTION_MAX_PAGESA Notion selection with more pages is refused
Max files per Google Drive library100001–100000, or no limitGOOGLE_DRIVE_MAX_FILESA Google Drive selection with more Docs and Slides is refused

The Parsing settings page with concurrency, timeout, and file limit settings

Git Access Tokens#

Configured under Workspace Settings › GitHub, GitLab and Other Git in the web UI.

SettingDescription
GitHub TokenGitHub Personal Access Token. Required for GitHub repositories
GitLab TokenGitLab token. Required for GitLab repositories
GitLab Server URLYour self-hosted GitLab host, such as gitlab.your-company.com. In the GitLab row, select Self-managed, then enter it in Server URL

You only need tokens for the platforms you use. If you only parse GitLab repos, you don’t need a GitHub token, and vice versa. Create tokens with repo scope (GitHub) or read_repository scope (GitLab) for private repository access.

The GitLab token is sent only to gitlab.com and the host in Server URL.

Access Control#

The server creates an admin account with the password admin at first boot. Change these credentials immediately after setup from Personal settings > Password > Change password.

Who can do what by default:

  • Admins can do everything.
  • Signed-in members and their API keys can parse and refresh libraries. To re-parse or replace an existing library, a member needs read access to it under the library access rules.
  • Anonymous callers (no session and no API key) can do none of these.

Delete, cancel parse, and support bundle downloads are for admins only. Use the switches in Workspace Settings › Authorization to open some actions to anonymous callers. The MCP authentication switch in Workspace Settings › Authentication requires authentication for MCP and API search.

The Non-admin permissions card with the anonymous parse, refresh, support bundle, and delete switches off

PermissionDefaultDescription
Parse repositoriesOffAllow anonymous callers to trigger parsing
Refresh repositoriesOffAllow anonymous callers to refresh libraries. Notion and Google Drive libraries stay admin-only
Delete repositoriesOffAllow anonymous callers and members to delete libraries and cancel parses
Download support bundleOffAllow anonymous callers and members to download the support bundle
MCP authenticationOn for a new installRequire a session or personal API key for /mcp, /api/v2, and the library, log, and queue read endpoints. See Authentication
Note

Earlier versions allowed anonymous parse and refresh by default. If you never saved these switches, they are off after an upgrade. Scripts that call these endpoints without an API key then get 403. Add a personal API key to the script, or turn the switch on.

A fresh install with no users, no existing admin, and no libraries starts with MCP authentication on. An install you upgrade keeps the setting you saved, so if you never turned it on it stays off.

When MCP authentication is enabled, each user creates personal keys from Personal settings > API keys. Clients send the key as Authorization: Bearer <key>.

When MCP authentication is off, a client that sends a valid personal API key is still treated as that user for library access, so it reads the restricted libraries the user can access. A client with no key, or an unknown key, is anonymous and reads only libraries that are open to everyone.

Recover admin access#

Lost the admin password, or locked out by a broken SSO setup? Run the reset-password script inside the container. It resets a local admin account and turns password sign-in back on. See Docker or Kubernetes.

Policies#

Policies let you control which public documentation from the Context7 cloud is accessible to your on-premise instance. They do not affect locally parsed on-premise content.

Open Workspace Settings › Content policies. Requires admin login and a valid LICENSE_KEY.

For details on source type toggles and library filters, see Customizing What Is Retrieved.

Network and Data Flow#

Besides your AI providers, git hosts, and connected sources, an instance with an online license contacts Context7 Cloud:

CallWhenWhat is sent
License checkEvery hourThe license key
Usage reportOnce a dayLicense key, call counts per endpoint, number of active API keys, app version, team size. No query text
Public library searchOn each library searchThe search text and library name, with secrets masked first
Public library contextOn a context query for a library that is not on this instanceThe query, with secrets masked first, and the public library ID

A context query for one of your local libraries is answered on the instance and sends nothing. No local library content or ID is sent. Per-user usage stays on the instance.

An offline license (ctx7off. prefix) is checked locally and makes none of these calls.

The server does not use HTTP_PROXY or HTTPS_PROXY for its own calls. For the full egress list, CONTEXT7_API_URL, and private CA setup, see Docker or Kubernetes.

Hosting#

  • Serve Context7 at the root of a host name, such as https://context7.internal.yourcompany.com. Hosting under a sub-path is not supported.
  • Behind a reverse proxy, Context7 uses X-Forwarded-Host and X-Forwarded-Proto to build SSO redirect URLs. Configure the proxy to set these headers and overwrite any values the client sends.

Web UI#

Open your deployment URL in a browser to access the dashboard. From here you can:

  • Add and remove libraries
  • Trigger re-indexing
  • Monitor parsing status and logs
  • Update AI provider settings, git tokens, and permissions
  • Configure policies for public cloud documentation access
  • Test MCP connectivity
  • Change admin credentials

Operations#

For updating, health checks, and other operational tasks, see the deployment guide for your platform:

Support#

For license issues, upgrade requests, or deployment questions, contact context7@upstash.com.