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:
| Provider | Model Used | API Endpoint |
|---|---|---|
| OpenAI | GPT-6 Astra | https://api.openai.com/v1 |
| Anthropic | Claude Opus 5 | https://api.anthropic.com/v1 |
| Google Gemini | Gemini 3.1 Pro Preview | https://generativelanguage.googleapis.com/v1beta |
| Google Vertex AI | Gemini 3.1 Pro Preview | You set the full URL. See Google Vertex AI. |
| Mistral | Mistral Large Latest | https://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.
- OCI Container
- Executable JAR
Environment variables:
| Variable Name | Required | Default | Description |
|---|---|---|---|
MODERNE_MODDY_{PROVIDER}_APIKEY | true | The API key for the specified LLM provider. Replace {PROVIDER} with OPENAI, ANTHROPIC, GEMINI, or MISTRAL. | |
MODERNE_MODDY_{PROVIDER}_MODEL | false | Optional model name override for the LLM provider. | |
MODERNE_MODDY_{PROVIDER}_URI | false | Optional 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}_HASHUSERID | false | true | Whether 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_HOST | false | The hostname of a proxy server used to reach the LLM API. If specified, PROXY_PORT must also be set. | |
MODERNE_MODDY_{PROVIDER}_PROXY_PORT | false | The port of the proxy server used to reach the LLM API. If specified, PROXY_HOST must also be set. | |
MODERNE_MODDY_VERTEX_CREDENTIALSJSON | false | The 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_ADMINONLY | false | false | If 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
Arguments:
| Argument Name | Required | Default | Description |
|---|---|---|---|
--moderne.moddy.{provider}.api-key | true | The API key for the specified LLM provider. Replace {provider} with openai, anthropic, gemini, or mistral. | |
--moderne.moddy.{provider}.model | false | Optional model name override for the LLM provider. | |
--moderne.moddy.{provider}.uri | false | Optional 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}.hash-user-id | false | true | Whether 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.host | false | The hostname of a proxy server used to reach the LLM API. If specified, proxy.port must also be set. | |
--moderne.moddy.{provider}.proxy.port | false | The port of the proxy server used to reach the LLM API. If specified, proxy.host must also be set. | |
--moderne.moddy.vertex.credentials-json | false | The 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.admin-only | false | false | If true, only admins will see Moddy in the UI and be able to chat with Moddy. |
Example:
export MODERNE_MODDY_ANTHROPIC_APIKEY=...
java -jar connector-{version}.jar \
# ... other configuration ...
--moderne.moddy.anthropic.api-key=$MODERNE_MODDY_ANTHROPIC_APIKEY \
# ... rest of configuration ...
Provider-specific examples
OpenAI
- OCI Container
- Executable JAR
export MODERNE_MODDY_OPENAI_APIKEY=...
docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_OPENAI_APIKEY \
# ... rest of configuration ...
moderne-connector:latest
export MODERNE_MODDY_OPENAI_APIKEY=...
java -jar connector-{version}.jar \
# ... other required agent configuration ...
--moderne.moddy.openai.api-key=$MODERNE_MODDY_OPENAI_APIKEY \
# ... rest of configuration ...
Anthropic (Claude)
- OCI Container
- Executable JAR
export MODERNE_MODDY_ANTHROPIC_APIKEY=...
docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_ANTHROPIC_APIKEY \
# ... rest of configuration ...
moderne-connector:latest
export MODERNE_MODDY_ANTHROPIC_APIKEY=...
java -jar connector-{version}.jar \
# ... other required agent configuration ...
--moderne.moddy.anthropic.api-key=$MODERNE_MODDY_ANTHROPIC_APIKEY \
# ... rest of configuration ...
Google Gemini
- OCI Container
- Executable JAR
export MODERNE_MODDY_GEMINI_APIKEY=...
docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_GEMINI_APIKEY \
# ... rest of configuration ...
moderne-connector:latest
export MODERNE_MODDY_GEMINI_APIKEY=...
java -jar connector-{version}.jar \
# ... other required agent configuration ...
--moderne.moddy.gemini.api-key=$MODERNE_MODDY_GEMINI_APIKEY \
# ... rest of configuration ...
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 runs | URI |
|---|---|
| Global | https://aiplatform.googleapis.com/v1/projects/{PROJECT}/locations/global/publishers/google |
| One region | https://europe-west4-aiplatform.googleapis.com/v1/projects/{PROJECT}/locations/europe-west4/publishers/google |
| EU multi-region | https://aiplatform.eu.rep.googleapis.com/v1/projects/{PROJECT}/locations/eu/publishers/google |
| Through a gateway | https://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:
- Set
CREDENTIALSJSONto the contents of the service account key file. - Leave
CREDENTIALSJSONout. The Connector then uses Application Default Credentials, such as theGOOGLE_APPLICATION_CREDENTIALSvariable 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.
- OCI Container
- Executable JAR
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
export MODERNE_MODDY_VERTEX_CREDENTIALSJSON="$(cat service-account-key.json)"
java -jar connector-{version}.jar \
# ... other required agent configuration ...
--moderne.moddy.vertex.uri=https://aiplatform.googleapis.com/v1/projects/my-project/locations/global/publishers/google \
--moderne.moddy.vertex.model=gemini-3.1-pro-preview \
--moderne.moddy.vertex.credentials-json="$MODERNE_MODDY_VERTEX_CREDENTIALSJSON" \
# ... rest of configuration ...
Mistral
- OCI Container
- Executable JAR
export MODERNE_MODDY_MISTRAL_APIKEY=...
docker run \
# ... other required agent configuration ...
-e MODERNE_MODDY_MISTRAL_APIKEY \
# ... rest of configuration ...
moderne-connector:latest
export MODERNE_MODDY_MISTRAL_APIKEY=...
java -jar connector-{version}.jar \
# ... other required agent configuration ...
--moderne.moddy.mistral.api-key=$MODERNE_MODDY_MISTRAL_APIKEY \
# ... rest of configuration ...
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.
- OCI Container
- Executable JAR
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
export MODERNE_MODDY_ANTHROPIC_APIKEY=...
java -jar connector-{version}.jar \
# ... other required agent configuration ...
--moderne.moddy.anthropic.api-key=$MODERNE_MODDY_ANTHROPIC_APIKEY \
--moderne.moddy.anthropic.proxy.host=proxy.company.com \
--moderne.moddy.anthropic.proxy.port=8080 \
# ... rest of configuration ...
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.
| Provider | User identifier | Country |
|---|---|---|
| OpenAI | Request body user | Header x-moderne-user-country |
| Anthropic | Request body metadata.user_id | Header x-moderne-user-country |
| Google Gemini | Header x-moderne-user-id | Header x-moderne-user-country |
| Google Vertex AI | Header x-moderne-user-id | Header x-moderne-user-country |
| Mistral | Header x-moderne-user-id | Header 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.
- OCI Container
- Executable JAR
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
export MODERNE_MODDY_MISTRAL_APIKEY=...
java -jar connector-{version}.jar \
# ... other required agent configuration ...
--moderne.moddy.mistral.api-key=$MODERNE_MODDY_MISTRAL_APIKEY \
--moderne.moddy.mistral.uri=https://llm-proxy.company.com/v1 \
--moderne.moddy.mistral.hash-user-id=false \
# ... rest of configuration ...
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-idheader. In LiteLLM, for example, addheader_name: x-moderne-user-idwithlitellm_user_role: customerundergeneral_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:
- OCI Container
- Executable JAR
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
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=...
java -jar connector-{version}.jar \
--moderne.connector.api-gateway-rsocket-uri=https://api.tenant.moderne.io/connector \
--moderne.connector.nickname=prod-1 \
--moderne.scm.github[0].uri=https://myorg.github.com \
--moderne.scm.github[0].allowable-organizations[0]=moderne \
--moderne.scm.github[0].oauth.include-private-repos=true \
--moderne.organization.sources.http[0].uri=https://internal.example.com/repos-lock.csv \
--moderne.organization.sources.http[0].poll.artifactory[0].uri=https://myartifactory.example.com/artifactory/ \
--moderne.organization.sources.http[0].poll.artifactory[0].lst-query-filters[0]='"name":{"$match":"*-ast.jar"}' \
--moderne.moddy.anthropic.api-key=$MODERNE_MODDY_ANTHROPIC_APIKEY
Verifying the configuration
After starting the Connector with the new configuration, "Moddy" will be displayed in the navigation bar in the Moderne SaaS UI:
You can then click "Moddy" and begin asking it questions about your codebase.