Reference

Schema version for this Enterprise Studio configuration file.

Identifies the file as an Enterprise Studio configuration.

neo4j-enterprise-studio-config

Neo4j deployment URI of the tools asset database (for example neo4j://localhost:7687).

Name of the database used for tool asset storage.

Service-account authentication method the server uses to connect to the asset storage DBMS. Configure exactly one method block: basic, oidc, or none.

When oidc is set, Enterprise Studio obtains a bearer token from an external identity provider via the OAuth 2.0 client-credentials grant and uses it to authenticate to the storage database. The oidc sub-block fields below configure the IdP request, and the Neo4j DBMS must be configured with a matching OIDC provider that trusts the IdP.

Specify none as an empty block (none: {}) to connect without authentication.

Service account username for the asset storage connection. Set exactly one of username or usernameFrom.

Secrets Manager type used to resolve the asset storage username. Must match an enabled provider under secretsManager. See Configuration → Secrets Manager.

aws, azure, gcp

Secret name in the configured provider. For AWS, the Secrets Manager secret name or ARN; the value must be a plaintext SecretString (not key/value JSON or SecretBinary). For Azure, the Key Vault secret name; the secret value must be the credential string. For GCP, the Secret Manager secret ID; the version payload must be the credential string. Required when usernameFrom is set.

Service account password for the asset storage connection. Set exactly one of password or passwordFrom. In production, use passwordFrom with a Secrets Manager when available, or the environment variable; see Security → Secrets management.

Secrets Manager type used to resolve the asset storage password. Must match an enabled provider under secretsManager. See Configuration → Secrets Manager.

aws, azure, gcp

Secret name in the configured provider. For AWS, the Secrets Manager secret name or ARN; the value must be a plaintext SecretString (not key/value JSON or SecretBinary). For Azure, the Key Vault secret name; the secret value must be the credential string. For GCP, the Secret Manager secret ID; the version payload must be the credential string. Required when passwordFrom is set.

OAuth 2.0 token endpoint of the identity provider, used when the oidc method is configured. Must use the https scheme. For Microsoft Entra ID this is https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token; for Keycloak it is https://<host>/realms/<realm>/protocol/openid-connect/token.

OAuth 2.0 client ID of the service principal that Enterprise Studio authenticates as. Required when the oidc method is configured.

OAuth 2.0 client secret of the service principal. Set exactly one of clientSecret or clientSecretFrom when the oidc method is configured. In production, use clientSecretFrom with a Secrets Manager when available, or the environment variable; see Security → Secrets management.

Secrets Manager type used to resolve the OIDC client secret. Must match an enabled provider under secretsManager. See Configuration → Secrets Manager.

aws, azure, gcp

Secret name in the configured provider. For AWS, the Secrets Manager secret name or ARN; the value must be a plaintext SecretString (not key/value JSON or SecretBinary). For Azure, the Key Vault secret name; the secret value must be the credential string. For GCP, the Secret Manager secret ID; the version payload must be the credential string. Required when clientSecretFrom is set.

List of OAuth 2.0 scopes requested when fetching the token. Provider-specific; for Microsoft Entra ID set this to [api://<neo4j-app-id>/.default]. Optional - some providers (for example Keycloak in client-credentials mode) don’t require any scopes.

When overriding with an environment variable, supply the value as a JSON array, for example ["openid"].

Whether query profiling is enabled for the Storage API.

true or false.

Whether per-request access logs for the Storage API are enabled.

true or false.

Display name shown to users in the UI for this deployment.

Neo4j deployment URI of the main database used by the server.

When directClientQuery.enabled is false, the URI must use the http or https scheme, since Enterprise Studio proxies all queries over HTTP. When directClientQuery.enabled is true, the URI can use any Neo4j protocol scheme (for example bolt, bolt+s, neo4j, neo4j+s, http, or https).

Whether the browser client queries the main database directly instead of routing queries through the Enterprise Studio server.

true or false.

Browser-reachable Neo4j URI of the main database, used when directClientQuery.enabled is true. May differ from neo4jDeployments.<deployment-id>.uri, which is reachable from the server.

Whether end users can sign in to this deployment with username/password (basic) authentication.

true or false.

Whether end users can sign in to this deployment with single sign-on through an OIDC identity provider.

true or false.

Role mapping that grants Enterprise Studio roles to Neo4j database users and roles.

In _config.yaml\_, define roleMapping as a YAML list; each entry has a role (studioAdmin or studioCreator) and a members list, where each member has a kind (databaseUser or databaseRole) and a name.

When overriding with an environment variable, set NES_neo4jDeployments_<deployment-id>_authorization_roleMapping to the full roleMapping array as a JSON string. There are no separate environment variables for individual members or role values.

When omitted, the role mapping defaults to granting studioAdmin to the Neo4j admin role (databaseRole:admin) and studioCreator to the Neo4j PUBLIC role (databaseRole:PUBLIC).

Whether Enterprise Studio resolves secretRef values of type aws from AWS Secrets Manager. When true, secretsManager.aws.region is required. See Configuration → AWS Secrets Manager.

true, false

AWS Region used for Secrets Manager API calls when secretsManager.aws.enabled is true.

Whether Enterprise Studio resolves secretRef values of type azure from Azure Key Vault. When true, secretsManager.azure.vaultUrl is required. See Configuration → Azure Key Vault.

true, false

Azure Key Vault URI (for example https://contoso.vault.azure.net/) when secretsManager.azure.enabled is true.

Whether Enterprise Studio resolves secretRef values of type gcp from Google Cloud Secret Manager. When true, secretsManager.gcp.project is required. See Configuration → Google Cloud Secret Manager.

true, false

Google Cloud project ID used for Secret Manager API calls when secretsManager.gcp.enabled is true.

Whether the Dashboards tool is shown in the Enterprise Studio UI.

true or false.

Whether the Bloom tool is shown in the Enterprise Studio UI.

true or false.

Whether the Query tool is shown in the Enterprise Studio UI.

true or false.

Filesystem path to the Enterprise license file. Optional: Enterprise Studio runs without a license, but providing one is highly recommended under the terms of your license agreement with Neo4j, Inc. or its affiliates.

HTTP port the Enterprise Studio server listens on.

Whether the Enterprise Studio web listener serves HTTPS on server.port. When false, the server uses plain HTTP. When true, configure server.https.certificates and place certificate files on disk; see Security → TLS. Outbound trust to Neo4j is configured separately; see Binary deployment.

Enterprise Studio reads HTTPS settings only at startup; restart the server after changes.

true or false.

Content-Security-Policy header value for static assets served by the server. If omitted, a default policy is applied automatically. Set to an empty string ("") to disable the header entirely.

The default policy shown below is applied when this setting is omitted.

default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' data: https://fonts.gstatic.com https://fonts.googleapis.com/; img-src 'self' data: blob:; media-src 'self' data: blob:; connect-src 'self' ws: wss: http: https:; worker-src 'self' blob:; child-src 'self' blob:; form-action 'none'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'

Directory for TLS certificate files when server.https.enabled is true, relative to the installation home unless an absolute path is set.

Private key filename within server.https.certificates.baseDirectory. Must be an unencrypted PKCS#8 PEM file (BEGIN PRIVATE KEY).

Public certificate filename within server.https.certificates.baseDirectory.

Whether map tiles are served by the Enterprise Studio server for use by the Dashboards map visualization. By default, the Neo4j PMTiles provider tiles.neo4j.io/current/planet.pmtiles is used. Set to false to disable maps entirely; this is recommended for air-gapped deployments without outbound internet access where no self-hosted tile provider is configured.

true or false

Tile data format of the custom provider. Required when customTilesProvider is configured.

raster or pmtiles

Edge length, in pixels, of one raster tile (usually 256, or 512 for high-density "@2x" tiles). Only valid when format.type is raster.

URL of the upstream tile provider, proxied through the Enterprise Studio server. For raster format, the URL must contain the placeholder template {z}/{x}/{y}. For pmtiles format, it must be a single-file URL with no placeholders.

Set exactly one of upstream.http or upstream.file.

Map of HTTP headers forwarded to the upstream provider on every request — used for API keys or bearer tokens the provider requires.

When overriding with an environment variable, set the value to a JSON object, for example {"X-API-Key":"…​"}.

Absolute filesystem path to a single PMTiles file served by the proxy. Only valid for pmtiles format. Set exactly one of upstream.http or upstream.file.

Value sent in the Access-Control-Allow-Origin response header for the reverse-proxied /map-tiles requests. Set to a specific origin (for example, https://studio.example.com) to restrict tile access to your own domain when the tile provider requires it.

Attribution label rendered in the map. Required for compliance with most tile providers' terms of service.

URL linked from the attribution label rendered in the map.

Whether generative AI features are switched on. A configured provider alone does not enable the feature; this flag must be true.

It also gates validation: when false, the rest of the block is not checked, and Enterprise Studio logs Generative AI is configured but not enabled, proxy disabled at startup if a provider is present.

true or false

Endpoint compatible with the OpenAI Chat Completions API that the server calls. Required when chatCompletionProvider.enabled is true.

The URL is called exactly as written; no path is appended. Include any query parameters the provider requires.

An absolute URL with a host, using the http or https scheme. http is permitted so that a gateway on localhost or inside your network can be used.

Provider API key, sent to the upstream as an Authorization: Bearer header.

Optional. Set at most one of apiKey or apiKeyFrom, and omit both when upstream.headers carries the credential or the upstream needs none — in that case no Authorization header is sent.

A non-empty value in config.yaml triggers a plaintext secret warning at startup, even when the feature is not enabled. Supply it with this environment variable or with apiKeyFrom instead.

Secrets Manager provider that holds the API key. The matching secretsManager.<type>.enabled must be true.

aws, azure, or gcp

Secret name in the configured provider. For AWS, the Secrets Manager secret name or ARN; the value must be a plaintext SecretString (not key/value JSON or SecretBinary). For Azure, the Key Vault secret name; the secret value must be the credential string. For GCP, the Secret Manager secret ID; the version payload must be the credential string.

The secret value must be the API key itself.

Map of HTTP headers forwarded to the provider on every request — can be used for custom headers or if you want to authenticate towards your provider in another way than a bearer token.

Headers are applied after the proxy’s own headers, so a value set here overrides it. Header names must not be empty.

When overriding with an environment variable, set the value to a JSON object, for example {"X-goog-api-key":"…​"}.

Model name that is sent to the provider, for example gpt-5.6-sol. Required when chatCompletionProvider.enabled is true.

The model has a large effect on how well the generative AI features work. See Configuration → Choosing a model.

Seconds allowed for one round trip to the provider. Exceeding it returns 504 Gateway Timeout.

An integer greater than 0.

Maximum size in bytes of a single request payload sent to the proxy. Exceeding it returns 413 Content Too Large.

An integer greater than 0.

Upper bound on the tokens generated for one call, sent to the provider as max_completion_tokens.

A completion cut short by this bound still returns 200 OK with truncated content. Enterprise Studio logs LLM provider did not finish the completion with finishReason: length when that happens.

An integer greater than 0.

Number of provider calls allowed in flight at once. Further calls wait for a free slot for up to settings.queueTimeout seconds. Note that Dashboard generation issues several requests.

This limit is enforced per server instance, so with multiple replicas the concurrency the provider sees is this value multiplied by the replica count.

An integer greater than 0.

Seconds a request waits for a free concurrency slot before it is rejected with 429 Too Many Requests and a Retry-After: 5 header.

An integer greater than 0.

Log level for general server logs.

One of debug, info, warn, or error.

Log output format; json is recommended for production.

One of json or pretty.