Configuration

Enterprise Studio is configured through a config.yaml file. This file is included as a template in the binary distribution package, or built dynamically when using Docker or Kubernetes. Any setting can also be supplied with a NES_* environment variable; see Environment variable overrides.

Minimal example

This is an illustrative minimal configuration that uses basic authentication for the asset store. For production, use OIDC authentication instead, as described in OIDC authentication.

Enterprise Studio validates its configuration at startup and exits immediately if any required setting is missing. Ensure your configuration contains at least the following settings before first launch:

Config file (config.yaml)

version: 1
kind: neo4j-enterprise-studio-config

license:
  path: /licenses/nes.license          (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687    (2)
    database: tools-storage            (3)
    authentication:
      basic:
        username: my-service-user      (4)
        password: my-service-password  (5)

neo4jDeployments:
  mydeployment:                        (6)
    name: My Neo4j                     (7)
    uri: http://my-neo4j-host:7474     (8)

1	Path to the Enterprise Studio license file. Not strictly required, but highly recommended under the terms of your license agreement with Neo4j, Inc. or its affiliates.
2	URI of the Neo4j instance where Enterprise Studio stores its internal data.
3	Database on that instance to use for storage.
4	Service account user for asset storage.
5	Password for that user. For production, use a Secrets Manager (`passwordFrom`) or an environment variable; see Security → Secrets management.
6	Unique identifier for this deployment (letters and digits only).
7	Human-readable label for the deployment.
8	Endpoint of the Neo4j instance that end users query through Enterprise Studio.

Environment file

The same minimal configuration can be expressed as an environment file (.env):

NES_server_port=8080
NES_license_path=/licenses/nes.license
NES_assetStore_default_uri=neo4j://my-neo4j-host:7687
NES_assetStore_default_database=tools-storage
NES_assetStore_default_authentication_basic_username=my-service-user
NES_assetStore_default_authentication_basic_password=my-service-password
NES_neo4jDeployments_mydeployment_name=My Neo4j
NES_neo4jDeployments_mydeployment_uri=http://my-neo4j-host:7474

Pass this file to Docker with the --env-file flag:

docker run -p 8080:8080 --env-file .env \
  -v /your/path/to/licenses:/licenses \
  neo4j/enterprise-studio

See Environment variable overrides for the full naming scheme.

Asset store

Enterprise Studio persists tool assets (dashboards, saved queries, Perspectives) in a dedicated Neo4j database. It connects to this database with a dedicated service account, configured under assetStore.default:

database: Name of the database used for storage. This database must already exist — create it before starting Enterprise Studio (see Prerequisites → Set up the tool asset database).
authentication: Authentication method the server uses to connect to the storage database. Configure exactly one method block: basic (username/password), oidc (OAuth 2.0 client-credentials grant), or none (no authentication).

Basic authentication

The service account signs in with a Neo4j username and password:

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        username: tools_service
        password: secret

See Prerequisites → Create a service account for creating this user and granting it the required privileges. For supplying the password outside the configuration file, see Security → Secrets management.

OIDC authentication

The service account can authenticate with a bearer token instead of a username and password. Enterprise Studio requests the token from your identity provider using the OAuth 2.0 client credentials grant, so no interactive login takes place. It fetches the token when the server starts and refreshes it automatically before it expires.

This requires a confidential client in your identity provider and a matching OIDC provider in neo4j.conf. See Prerequisites → Service account with SSO for setting these up.

With that in place, point assetStore.default.authentication.oidc at the token endpoint of your identity provider:

assetStore:
  default:
    uri: neo4j+s://my-neo4j-host:7687                   (1)
    database: tools-storage
    authentication:
      oidc:
        tokenUrl: https://idp.example.com/oauth2/token  (2)
        clientId: studio-storage-sa                     (3)
        clientSecret: my-api-key                         (4)
        scopes: []                                      (5)

1	Use an encrypted scheme such as `neo4j+s://` or `bolt+s://` to encrypt the bearer token.
2	Token endpoint of your identity provider. It must use `https`. For Keycloak the format is `https://<host>/realms/<realm>/protocol/openid-connect/token`, and for Microsoft Entra ID it is `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`.
3	Client ID of the confidential client you registered.
4	Client secret. Supply this through an environment variable rather than the file, as shown below.
5	Scopes requested when the token is fetched. This is optional and depends on the provider. Keycloak in client credentials mode needs none, while Microsoft Entra ID expects `[api://<neo4j-app-id>/.default]`.

Supply the client secret through the environment so it is never written to disk:

export NES_assetStore_default_authentication_oidc_clientSecret="your-client-secret"

When you override scopes with an environment variable, pass it as a JSON array, for example NES_assetStore_default_authentication_oidc_scopes='["openid"]'.

To resolve values from Secrets Manager, see Secrets Manager.

For OIDC-based authentication to the storage database, see the OIDC fields in the reference.

Neo4j deployments

A deployment represents a Neo4j instance that end users connect to through Enterprise Studio. At least one deployment must be defined.

By default, Enterprise Studio proxies queries to Neo4j on behalf of the user. In this mode, uri must point to the Neo4j HTTP API (typically port 7474 for HTTP or 7473 for HTTPS), because the server translates user queries into HTTP API requests:

HTTPS (default proxy mode)

neo4jDeployments:
  production:
    name: Production Graph
    uri: https://neo4j-prod:7473

Bolt (direct client query mode)

neo4jDeployments:
  production:
    name: Production Graph
    uri: neo4j+s://neo4j-prod:7687

In proxy mode, uri points to the Neo4j HTTP API (port 7474 / 7473). In direct client query mode, uri uses the Bolt protocol (port 7687). If a deployment uri points to a Neo4j cluster, the HTTP endpoint must provide session affinity, or transactions fail intermittently with Transaction with Id … was not found errors. See Prerequisites → Set up communication to a Neo4j cluster.

Direct client query

Alternatively, you can let the user’s browser connect directly to Neo4j by enabling directClientQuery. In this mode, uri must use a Bolt scheme (neo4j://, neo4j+s://, bolt://, or bolt+s://) because the browser communicates with Neo4j over the Bolt protocol (typically port 7687). You must also provide a publicUri that is reachable from the end user’s browser:

neo4jDeployments:
  production:
    name: Production Graph
    uri: neo4j+s://neo4j-prod:7687
    directClientQuery:
      enabled: true
      publicUri: neo4j+s://neo4j.example.com:7687

uri: Internal URI used by the server. Not required to be publicly accessible.
directClientQuery.publicUri: Public URI that end-user browsers connect to directly. Must be reachable from the user’s network.

Authentication methods

By default, end users can sign in to a deployment with either username/password (basic) or single sign-on through an OIDC identity provider (oidc). Use authentication to restrict which methods are offered in the connection form:

neo4jDeployments:
  production:
    name: Production Graph
    uri: http://neo4j-prod:7474
    authentication:
      basic:
        enabled: false  (1)

1	Disable username/password sign-in.

Each method is enabled by default when omitted.

Authorization

Map Neo4j database users or roles to Enterprise Studio roles to control who can administer or create content. When roleMapping is omitted, Enterprise Studio grants studioAdmin to the Neo4j admin role and studioCreator to the Neo4j PUBLIC role. See Administration for a full walkthrough of role assignment by database role, username, or SSO.

neo4jDeployments:
  production:
    name: Production Graph
    uri: http://neo4j-prod:7474
    authorization:
      roleMapping:
        - role: studioAdmin
          members:
            - kind: databaseRole
              name: admin
        - role: studioCreator
          members:
            - kind: databaseRole
              name: PUBLIC

Server

By default, Enterprise Studio listens on HTTP port 8080.

server:
  port: 9090                            (1)
  https:
    enabled: true                       (2)

1	Change the listen port.
2	Enable HTTPS. Requires TLS certificates; see TLS below.

TLS

Clients send their Neo4j credentials (username/password or bearer token) to Enterprise Studio on every request. Without TLS, those credentials travel in cleartext and can be intercepted. Always serve Enterprise Studio over HTTPS in production, either by enabling server.https.enabled or by terminating TLS at a trusted reverse proxy or load balancer in front of it.

When server.https.enabled is false, Enterprise Studio prints a reminder at startup. See Security → TLS encryption for guidance.

When server.https.enabled is true, place certificate files in the directory specified by server.https.certificates.baseDirectory (default: certificates/https relative to the installation home). These settings configure inbound HTTPS only; outbound trust to Neo4j is separate — see Security → TLS encryption and Binary deployment.

server:
  https:
    enabled: true
    certificates:
      baseDirectory: /etc/studio/certs  (1)
      privateKey: private.key           (2)
      publicCertificate: public.crt     (3)

1	Absolute or relative path to the certificate directory.
2	Unencrypted PKCS#8 PEM private key file.
3	PEM public certificate file.

See TLS encryption for a step-by-step guide.

Tools

Individual tools can be disabled if not needed:

tools:
  dashboards:
    enabled: true
  bloom:
    enabled: true
  query:
    enabled: false

Set enabled to false to hide a tool from the UI. All tools are enabled by default.

Enterprise Studio reads tool configuration only at startup. Restart the server after changing any tools.*.enabled setting for the change to take effect.

Generative AI

Enterprise Studio can add generative AI features to its tools by calling a large language model (LLM) provider that you supply and control. The feature is off by default.

Features

When a provider is configured and enabled, the following features become available:

Query: the Query co-pilot, which suggests a Cypher® query for a question asked in natural language.
Bloom: the Bloom co-pilot, which turns a description in natural language into a graph search pattern.
Dashboards: AI dashboard generation, query suggestions, and natural language queries in the widget editor.

Minimal configuration

generativeAi:
  chatCompletionProvider:
    enabled: true                                          (1)
    default:                                               (2)
      upstream:
        url: https://api.openai.com/v1/chat/completions    (3)
        apiKey: my-api-key                                 (4)
      model: my-model                                      (5)

1	Turns the feature on. Defaults to `false`.
2	The provider slot. `default` is a fixed key name, not an identifier you choose. Only a single provider is supported.
3	The complete url to the endpoint of the OpenAI Chat Completions API. Required when enabled. Enterprise Studio calls this endpoint exactly as written. Both `http` and `https` are accepted, so a gateway running on `localhost` can be used.
4	Provider API key, sent as `Authorization: Bearer <key>`. Optional; see Authenticating to the provider.
5	Model name the provider expects. Required when enabled.

enabled defaults to false, and a configured provider on its own does not switch the feature on. It also gates validation: when enabled is false, the rest of the block is not checked.

Supported providers

Enterprise Studio supports any endpoint that is compatible with the OpenAI Chat Completions API.

See Examples → Generative AI providers for a worked configuration per provider.

Selecting a model

Since the features generate Cypher and structured data, the model you choose affects how well they work.

Select a model that is:

Capable of code generation: Every feature ultimately produces Cypher. Models that are weak at code tend to return queries that fail against your schema.
Skilled at reasoning: Generating a dashboard means planning several related queries against a schema the model sees only in the prompt.
Able to return structured output: Enterprise Studio asks the provider for a JSON response matching a supplied JSON schema.
Large enough in context: Prompts include the schema of the connected database, so a wide schema makes for a long prompt.

Small, inexpensive models are usually a poor fit, because they are the most likely to return invalid Cypher or malformed JSON. Weigh this against latency: these features are interactive, so a model that reasons at length before answering makes the UI feel slow and may need a higher settings.requestTimeout.

In practice, the flagship or mid tier of any current model family from a major provider meets these criteria. Reasonable starting points are OpenAI’s GPT models (Terra or Sol), Google’s Gemini Flash models, and Anthropic’s Claude Sonnet models. Avoid the cheapest tier of a family, which is tuned for cost and latency rather than for generating code.

Treat this as a starting point rather than a recommendation, and test against your own schema.

With a reasoning model, the tokens spent on internal reasoning count towards settings.maxCompletionTokens along with the answer itself. Such a model may therefore need a higher value than the default to return a complete answer. See Troubleshooting for how a truncated answer appears in the log.

When you have selected your model, give model exactly the name the endpoint expects, and check that the model is available on that endpoint before you enable the feature.

Authenticating with a provider

Set at most one of apiKey or apiKeyFrom. Both may be omitted when headers carries the credential, or when the upstream requires no authentication at all.

upstream.apiKey: The API key as a literal value, sent as Authorization: Bearer <key>. Supply this through an environment variable rather than writing it into config.yaml. See example below.
upstream.apiKeyFrom.secretRef: Read the key from a cloud Secrets Manager instead. Set type to aws, azure, or gcp, and name to the secret identifier. The matching secretsManager.<type>.enabled must be true; see Secrets Manager.
upstream.headers: Arbitrary HTTP headers sent on every request to the provider. They are applied after the proxy’s own headers, so they always take precedence. Can be used for custom headers or if you want to authenticate towards your provider in another way than a bearer token.

Supply the API key through the environment so it is never written to disk:

export NES_generativeAi_chatCompletionProvider_default_upstream_apiKey="my-api-key"

When using Kubernetes, the Helm chart has dedicated values for the provider API key, so that it is held in a Kubernetes Secret rather than in the ConfigMap. See Deploy to Kubernetes → Generative AI.

When you override headers with an environment variable, pass it as a JSON object, for example NES_generativeAi_chatCompletionProvider_default_upstream_headers='{"X-goog-api-key":"your-api-key"}'. This is required because header names contain characters that cannot appear in an environment variable name.

Using a gateway for other authentication schemes

Enterprise Studio authenticates to the provider with an API key or with headers. It does not implement cloud identity schemes such as AWS SigV4 request signing, Microsoft Entra ID tokens, or Google service account credentials.

If you would rather not manage a long-lived provider API key, put an LLM gateway in front of the provider. The gateway accepts the simple credential that Enterprise Studio sends, and authenticates to the provider upstream with that provider’s own identity mechanism, so no long-lived provider secret has to live in the Enterprise Studio configuration.

Gateways such as LiteLLM and Bifrost commonly support:

AWS Bedrock — the standard AWS credential chain, including instance profiles, IAM Roles for Service Accounts (IRSA) on EKS, and roles assumed through STS.
Google Vertex AI — Application Default Credentials, service account credentials, and Workload Identity Federation.
Azure OpenAI — Microsoft Entra ID tokens obtained from a managed identity or a service principal.

Between Enterprise Studio and the gateway you then use a credential that the gateway issues, such as a virtual key, in apiKey. That credential is scoped to the gateway rather than to your cloud account, and you can rotate or revoke it there without touching the provider.

Limiting cost and latency

The optional settings block bounds what a single generation may cost and how long it may take. Every value is a positive integer, and timeouts are in whole seconds. The values shown here are the defaults.

generativeAi:
  chatCompletionProvider:
    enabled: true
    default:
      upstream:
        url: https://api.openai.com/v1/chat/completions
        apiKey: my-api-key
      model: my-model
      settings:
        requestTimeout: 120
        maxRequestBodyBytes: 1048576
        maxCompletionTokens: 16384
        maxConcurrentRequests: 30
        queueTimeout: 30

requestTimeout: Seconds allowed for one round trip to the provider. Exceeding it returns 504 Gateway Timeout. Default: 120.
maxRequestBodyBytes: Maximum size of a single request payload. Exceeding it returns 413 Content Too Large. Default: 1048576 (1 MiB).
maxCompletionTokens: Upper bound on the tokens generated for one call, sent to the provider as max_completion_tokens. Set too low, answers are truncated without an error; see Troubleshooting. Default: 16384.
maxConcurrentRequests: Number of provider calls allowed in flight at once. Default: 30.
queueTimeout: Seconds a request waits for a free slot before it is rejected with 429 Too Many Requests and a Retry-After: 5 header. Default: 30.

maxConcurrentRequests is enforced per server instance. When you run multiple replicas, the concurrency your provider sees is this value multiplied by the number of replicas.

Database requirements

The generative AI features send the schema of the connected database to the provider as context, so that generated Cypher matches your data model. They read that schema by calling the apoc.meta.schema procedure. APOC must therefore be installed on the Neo4j deployments where you want to use these features.

This applies to the databases your users query through a deployment, not to the tool asset database. APOC Core ships with Neo4j, but needs to be installed. See APOC → Installation.

If you restrict procedures with dbms.security.procedures.allowlist in neo4j.conf, then make sure to include apoc.meta.schema in the allowlist.

Troubleshooting

The proxy returns the following status codes:

Status Cause

Status	Cause
`401`	The caller’s Neo4j deployment credentials were rejected.
`404`	Generative AI is not enabled.
`413`	The request body exceeded `settings.maxRequestBodyBytes`.
`429`	`settings.maxConcurrentRequests` calls were already in flight and no slot became free within `settings.queueTimeout`, or the provider itself rate limited the request.
`500`	Enterprise Studio could not build the request, or could not resolve the API key from the Secrets Manager.
`502`	The provider could not be reached, returned an unsuccessful status, or returned a response that could not be parsed.
`504`	The provider did not answer within `settings.requestTimeout`.

401

The caller’s Neo4j deployment credentials were rejected.

404

Generative AI is not enabled.

413

The request body exceeded settings.maxRequestBodyBytes.

429

settings.maxConcurrentRequests calls were already in flight and no slot became free within settings.queueTimeout, or the provider itself rate limited the request.

500

Enterprise Studio could not build the request, or could not resolve the API key from the Secrets Manager.

502

The provider could not be reached, returned an unsuccessful status, or returned a response that could not be parsed.

504

The provider did not answer within settings.requestTimeout.

The provider’s own error responses are never forwarded to the browser, because they can disclose a partially masked key or your organization name. To see what the provider actually returned, set logs.level to debug and retry.

If answers come back truncated or fail to parse, the completion was cut short. Enterprise Studio logs LLM provider did not finish the completion with finishReason: length, which means settings.maxCompletionTokens is too low for that feature.

See Logging and monitoring → Generative AI requests for the per-request token accounting used to attribute spend to a feature.

For every setting, its environment variable, and its default, see Reference → generativeAi.

Logging

logs:
  level: info
  format: json

level: Log verbosity. One of debug, info, warn, or error.
format: Log output format. Use json (recommended for production) or pretty (human-readable, useful during development).

Secrets Manager

Enterprise Studio can resolve asset storage credentials (username, password) and the OIDC clientSecret from an external Secrets Manager at runtime, instead of storing them in plaintext in config.yaml.

To set up Secrets Manager:

Enable a provider under secretsManager.
For each sensitive field, set exactly one of the literal or the *From reference (username/usernameFrom, password/passwordFrom, clientSecret/clientSecretFrom).

Each secretRef needs a type (aws, azure, or gcp) and a name (the secret identifier in that provider). Use a separate secret for each field (usernameFrom, passwordFrom, clientSecretFrom). The secret value must be the credential string itself — Enterprise Studio does not parse JSON key/value objects.

Enterprise Studio uses the cloud provider’s default credential chain. Do not put cloud access keys in config.yaml. How you supply those credentials depends on where you run Enterprise Studio — see Binary, Docker, and Kubernetes.

See the configuration reference for all settings.

This describes a third-party service; this guidance is based on the information available at the time of writing and may not always reflect the current state of the third party.

AWS Secrets Manager

Enable secretsManager.aws, set the Region, and set secretRef.name to the secret name or ARN in AWS Secrets Manager.

Store each credential as a plaintext SecretString, see AWS documentation for more information:

In the AWS console, select Other type of secret, then the Plaintext tab, and enter only the username or password (not key/value pairs).
With the CLI, pass a plain string, for example --secret-string 'my-service-password'.

Do not store the value as a JSON object (key/value pairs) or as SecretBinary. Enterprise Studio uses the entire SecretString as the credential and does not extract keys from JSON. Binary secrets are rejected.

Example AWS Secrets Manager configuration

secretsManager:
  aws:
    enabled: true
    region: eu-west-1                  (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        usernameFrom:
          secretRef:
            type: aws                  (2)
            name: nes-assetstore-username  (3)
        passwordFrom:
          secretRef:
            type: aws
            name: nes-assetstore-password

1	Required when AWS is enabled.
2	Must be `aws`.
3	Secret name or ARN. Value must be a plaintext `SecretString` (the username or password only).

For OIDC, use the same pattern with clientSecretFrom instead of passwordFrom.

Enterprise Studio uses the AWS SDK default credential chain. See Authentication and access control for AWS Secrets Manager.

Azure Key Vault

Enable secretsManager.azure, set the vault URL, and set secretRef.name to the secret name in Azure Key Vault.

Key Vault secrets are a single string value. Store the username, password, or client secret as that value (for example with az keyvault secret set --name nes-assetstore-password --value 'my-service-password'). Enterprise Studio uses the secret value as returned — it does not parse JSON objects.

Example Azure Key Vault configuration

secretsManager:
  azure:
    enabled: true
    vaultUrl: https://contoso.vault.azure.net/  (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        usernameFrom:
          secretRef:
            type: azure               (2)
            name: nes-assetstore-username  (3)
        passwordFrom:
          secretRef:
            type: azure
            name: nes-assetstore-password

1	Required when Azure is enabled. Vault URI from the Azure portal or CLI.
2	Must be `azure`.
3	Key Vault secret name. The secret value must be the credential string itself.

Enterprise Studio uses DefaultAzureCredential. Grant the identity permission to get secrets — for example the Key Vault Secrets User role. See Authenticate Go apps to Azure.

Google Cloud Secret Manager

Enable secretsManager.gcp, set the project ID, and set secretRef.name to the secret ID in Secret Manager. Enterprise Studio reads the latest version of the named secret.

Store each credential as the secret version payload — typically UTF-8 text that is only the username, password, or client secret (for example echo -n 'my-service-password' | gcloud secrets versions add nes-assetstore-password --data-file=-). Enterprise Studio uses the full payload as the credential string and does not parse JSON objects.

Example Google Cloud Secret Manager configuration

secretsManager:
  gcp:
    enabled: true
    project: my-project               (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        usernameFrom:
          secretRef:
            type: gcp                 (2)
            name: nes-assetstore-username  (3)
        passwordFrom:
          secretRef:
            type: gcp
            name: nes-assetstore-password

1	Required when GCP is enabled. Google Cloud project ID.
2	Must be `gcp`.
3	Secret ID (not the full resource name). Enterprise Studio resolves `projects/<project>/secrets/<name>/versions/latest`. The payload must be the credential string itself.

Enterprise Studio uses Application Default Credentials (ADC). Grant the identity Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) on the secrets it must read.

Environment variable overrides

Any setting in config.yaml can be overridden by setting an environment variable. Use them to adjust values per environment without modifying the file. For passwords and OIDC client secrets in production, use a cloud Secrets Manager when available; otherwise use environment variables — see Security → Secrets management.

To derive the environment variable name from a config path:

Start with the prefix NES_
Replace each . with _
Keep camelCase as-is

Table 1. Examples
Config path	Environment variable
`assetStore.default.uri`	`NES_assetStore_default_uri`
`assetStore.default.authentication.basic.password`	`NES_assetStore_default_authentication_basic_password`
`assetStore.default.authentication.oidc.clientSecret`	`NES_assetStore_default_authentication_oidc_clientSecret`
`generativeAi.chatCompletionProvider.default.upstream.apiKey`	`NES_generativeAi_chatCompletionProvider_default_upstream_apiKey`
`server.port`	`NES_server_port`
`server.https.enabled`	`NES_server_https_enabled`
`neo4jDeployments.mydeployment.uri`	`NES_neo4jDeployments_mydeployment_uri`

Deployment IDs must contain only letters and digits (a-z, A-Z, 0-9). This keeps them safe to use directly in NES_neo4jDeployments_<id>_… environment variable names.

For example, to override the asset storage URI and server port:

export NES_assetStore_default_uri="neo4j://my-host:7687"
export NES_server_port="9090"

Environment variables override values in config.yaml at runtime: they do not modify the file on disk. See the Docker deployment page for a complete example using environment variables.