Skip to main content

Configure a Connector with Moddy support

This guide will walk you through how to configure the Moderne Connector to enable support for Moddy, Moderne's multi-repo AI agent. Moddy employs a bring-your-own model (BYOM) approach, which allows you to connect any large language model (LLM) that has been approved for use within your company.

Prerequisites​

  • You will need an API key from your chosen LLM provider (OpenAI, Anthropic, Google Gemini, or Mistral)
  • If you use Google Vertex AI, you will need a Google Cloud project with the Vertex AI API enabled and a service account instead of an API key

Supported LLM providers​

The Moderne Connector currently supports the following LLM providers:

ProviderModel UsedAPI Endpoint
OpenAIGPT-6 Astrahttps://api.openai.com/v1
AnthropicClaude Opus 5https://api.anthropic.com/v1
Google GeminiGemini 3.1 Pro Previewhttps://generativelanguage.googleapis.com/v1beta
Google Vertex AIGemini 3.1 Pro PreviewYou set the full URL. See Google Vertex AI.
MistralMistral Large Latesthttps://api.mistral.ai/v1

If you need a model or LLM provider that isn't listed here, please contact Moderne support.

Configuring the Moderne Connector​

The following table contains all of the variables/arguments you need to add to your Moderne Connector run command in order to enable Moddy. Please note that these variables/arguments must be combined with ones found in other steps in the Configuring the Moderne Connector guide.

Variables are nested under the specific provider you are configuring. Replace {PROVIDER} with one of: OPENAI, ANTHROPIC, GEMINI, VERTEX, MISTRAL (for environment variables) or {provider} with one of: openai, anthropic, gemini, vertex, mistral (for JAR arguments).

Google Vertex AI has no API key. For VERTEX, URI is required, and you can set CREDENTIALSJSON instead of APIKEY. See Google Vertex AI.

Environment variables:

Variable NameRequiredDefaultDescription
MODERNE_MODDY_{PROVIDER}_APIKEYtrueThe API key for the specified LLM provider. Replace {PROVIDER} with OPENAI, ANTHROPIC, GEMINI, or MISTRAL.
MODERNE_MODDY_{PROVIDER}_MODELfalseOptional model name override for the LLM provider.
MODERNE_MODDY_{PROVIDER}_URIfalseOptional URI override for the LLM API endpoint. If not specified, the default endpoint for the provider is used (see table above). Required for VERTEX, where you set the full endpoint URL. Useful for routing requests through a custom API gateway.
MODERNE_MODDY_{PROVIDER}_HASHUSERIDfalsetrueWhether to send the SHA-256 hash of the user's email (true) or the plain email (false) as the user identifier on each LLM request. See User identity on LLM requests.
MODERNE_MODDY_{PROVIDER}_PROXY_HOSTfalseThe hostname of a proxy server used to reach the LLM API. If specified, PROXY_PORT must also be set.
MODERNE_MODDY_{PROVIDER}_PROXY_PORTfalseThe port of the proxy server used to reach the LLM API. If specified, PROXY_HOST must also be set.
MODERNE_MODDY_VERTEX_CREDENTIALSJSONfalseThe contents of a Google Cloud service account key file. Used only for VERTEX. If you leave it out, the Connector uses Application Default Credentials.
MODERNE_MODDY_ADMINONLYfalsefalseIf true, only admins will see Moddy in the UI and be able to chat with Moddy.

Example:

export MODERNE_MODDY_ANTHROPIC_APIKEY=...

docker run \
# ... other configuration ...
-e MODERNE_MODDY_ANTHROPIC_APIKEY \
# ... rest of configuration ...
moderne-connector:latest

Provider-specific examples​

OpenAI​

export MODERNE_MODDY_OPENAI_APIKEY=...

docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_OPENAI_APIKEY \
# ... rest of configuration ...
moderne-connector:latest

Anthropic (Claude)​

export MODERNE_MODDY_ANTHROPIC_APIKEY=...

docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_ANTHROPIC_APIKEY \
# ... rest of configuration ...
moderne-connector:latest

Google Gemini​

export MODERNE_MODDY_GEMINI_APIKEY=...

docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_GEMINI_APIKEY \
# ... rest of configuration ...
moderne-connector:latest

Google Vertex AI​

Vertex AI serves Gemini models from your own Google Cloud project. You set the full endpoint URL yourself, and the Connector signs each request with a Google access token.

Setting the endpoint​

Set URI to the base URL for your project and location. Replace {PROJECT} with your Google Cloud project ID.

Where the model runsURI
Globalhttps://aiplatform.googleapis.com/v1/projects/{PROJECT}/locations/global/publishers/google
One regionhttps://europe-west4-aiplatform.googleapis.com/v1/projects/{PROJECT}/locations/europe-west4/publishers/google
EU multi-regionhttps://aiplatform.eu.rep.googleapis.com/v1/projects/{PROJECT}/locations/eu/publishers/google
Through a gatewayhttps://llm-gateway.company.com/vertex_ai/v1/projects/{PROJECT}/locations/global/publishers/google

Google does not offer every model in every location. Check that your model is available in the location you pick.

If you use a gateway, you will still need to give the Connector Google credentials. The Connector will send a Google access token with each request. Your gateway will need to accept that token or pass it through.

Choosing credentials​

Create a service account with the Vertex AI User role (roles/aiplatform.user) on your project. You can then give the Connector its key in one of two ways:

  1. Set CREDENTIALSJSON to the contents of the service account key file.
  2. Leave CREDENTIALSJSON out. The Connector then uses Application Default Credentials, such as the GOOGLE_APPLICATION_CREDENTIALS variable or a service account attached to the machine it runs on.

Choosing a model​

Set MODEL to a Gemini model name that your project can use. The default is gemini-3.1-pro-preview, which is a preview model. You should set MODEL to the model you want so it does not change under you.

export MODERNE_MODDY_VERTEX_CREDENTIALSJSON="$(cat service-account-key.json)"

docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_VERTEX_URI=https://aiplatform.googleapis.com/v1/projects/my-project/locations/global/publishers/google \
-e MODERNE_MODDY_VERTEX_MODEL=gemini-3.1-pro-preview \
-e MODERNE_MODDY_VERTEX_CREDENTIALSJSON \
# ... rest of configuration ...
moderne-connector:latest

Mistral​

export MODERNE_MODDY_MISTRAL_APIKEY=...

docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_MISTRAL_APIKEY \
# ... rest of configuration ...
moderne-connector:latest

Proxy configuration​

If your organization requires LLM API access to go through a proxy, you can configure the proxy host and port per provider. Both must be specified together.

export MODERNE_MODDY_ANTHROPIC_APIKEY=...

docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_ANTHROPIC_APIKEY \
-e MODERNE_MODDY_ANTHROPIC_PROXY_HOST=proxy.company.com \
-e MODERNE_MODDY_ANTHROPIC_PROXY_PORT=8080 \
# ... rest of configuration ...
moderne-connector:latest

User identity on LLM requests​

Every request Moddy sends to your LLM carries the signed-in user's identifier and, when your identity provider supplies it, the user's country. Your LLM proxy can use these values to meter usage per user and to apply model-per-country policy. Moderne does not meter or route requests itself.

ProviderUser identifierCountry
OpenAIRequest body userHeader x-moderne-user-country
AnthropicRequest body metadata.user_idHeader x-moderne-user-country
Google GeminiHeader x-moderne-user-idHeader x-moderne-user-country
Google Vertex AIHeader x-moderne-user-idHeader x-moderne-user-country
MistralHeader x-moderne-user-idHeader x-moderne-user-country

By default, the user identifier is the SHA-256 hash of the user's email address. The country is passed through from your identity provider unchanged. Send a two-letter ISO 3166-1 code, such as DE, so your proxy has a predictable value to match. If a user has no country, the header is omitted.

Sending the plain email to your proxy​

Set hash-user-id to false on a provider to send the user's email address instead of its hash. The setting is per provider, so you can send the plain email to one provider and the hash to another. You should only do this when the provider's URI points at your own LLM proxy.

Anthropic rejects an email address in metadata.user_id and fails the request. Keep hash-user-id at true on the Anthropic block, or make sure your proxy replaces the identifier before forwarding to Anthropic. Your proxy can still meter by email with hashing on, because the identifier is the unsalted SHA-256 of the email and your proxy can compute the same value.

export MODERNE_MODDY_MISTRAL_APIKEY=...

docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_MISTRAL_APIKEY \
-e MODERNE_MODDY_MISTRAL_URI=https://llm-proxy.company.com/v1 \
-e MODERNE_MODDY_MISTRAL_HASHUSERID=false \
# ... rest of configuration ...
moderne-connector:latest

Sending the user's country​

Your identity provider needs to send the user's country as a claim on login. Moderne maps the claim into the user's session. See the authentication reference for the attribute to send.

Configuring your LLM proxy​

Point the provider's URI at your proxy. Moddy sends each request in the provider's native format. The MODEL value is the model name your proxy receives, so your proxy decides which backend model answers.

  • Your proxy can read the user identifier from the request body for OpenAI and Anthropic without configuration. For Google Gemini, Google Vertex AI, and Mistral, you will need to configure your proxy to read the x-moderne-user-id header. In LiteLLM, for example, add header_name: x-moderne-user-id with litellm_user_role: customer under general_settings.user_header_mappings.
  • Routing by country is a rule you add to your proxy that reads x-moderne-user-country. No proxy applies one by default.
  • Your proxy will need to end its response to the Connector as soon as the provider's stream ends. Moddy asks your LLM for every answer as a stream.

Complete example with multiple configurations​

Here's a complete example showing a Connector configured with GitHub, Artifactory, and Moddy support:

export MODERNE_CONNECTOR_CRYPTO_SYMMETRICKEY=...
export MODERNE_CONNECTOR_TOKEN=...
export MODERNE_SCM_GITHUB_0_OAUTH_CLIENTID=...
export MODERNE_SCM_GITHUB_0_OAUTH_CLIENTSECRET=...
export MODERNE_ORGANIZATION_SOURCES_HTTP_0_POLL_ARTIFACTORY_0_USERNAME=...
export MODERNE_ORGANIZATION_SOURCES_HTTP_0_POLL_ARTIFACTORY_0_PASSWORD=...
export MODERNE_MODDY_ANTHROPIC_APIKEY=...

docker run \
-e MODERNE_CONNECTOR_APIGATEWAYRSOCKETURI=https://api.tenant.moderne.io/connector \
-e MODERNE_CONNECTOR_CRYPTO_SYMMETRICKEY \
-e MODERNE_CONNECTOR_NICKNAME=prod-1 \
-e MODERNE_CONNECTOR_TOKEN \
-e MODERNE_SCM_GITHUB_0_OAUTH_CLIENTID \
-e MODERNE_SCM_GITHUB_0_OAUTH_CLIENTSECRET \
-e MODERNE_SCM_GITHUB_0_URI=https://myorg.github.com \
-e MODERNE_SCM_GITHUB_0_ALLOWABLEORGANIZATIONS_0=moderne \
-e MODERNE_SCM_GITHUB_0_OAUTH_INCLUDEPRIVATEREPOS=true \
-e MODERNE_ORGANIZATION_SOURCES_HTTP_0_URI=https://internal.example.com/repos-lock.csv \
-e MODERNE_ORGANIZATION_SOURCES_HTTP_0_POLL_ARTIFACTORY_0_URI=https://myartifactory.example.com/artifactory/ \
-e MODERNE_ORGANIZATION_SOURCES_HTTP_0_POLL_ARTIFACTORY_0_USERNAME \
-e MODERNE_ORGANIZATION_SOURCES_HTTP_0_POLL_ARTIFACTORY_0_PASSWORD \
-e MODERNE_ORGANIZATION_SOURCES_HTTP_0_POLL_ARTIFACTORY_0_LSTQUERYFILTERS_0='"name":{"$match":"*-ast.jar"}' \
-e MODERNE_MODDY_ANTHROPIC_APIKEY \
-p 8080:8080 \
moderne-connector:latest

Verifying the configuration​

After starting the Connector with the new configuration, "Moddy" will be displayed in the navigation bar in the Moderne SaaS UI:

moddy-nav-bar.png
"Moddy" displayed in the nav bar

You can then click "Moddy" and begin asking it questions about your codebase.