How to Use Optional Environment Variable Substitution with ${?...} Syntax in Neuro San Studio

Use the ${?VARIABLE_NAME} syntax in HOCON configuration files to substitute environment variables when present, or silently omit the entire configuration line when the variable is absent.

The cognizant-ai-lab/neuro-san-studio repository uses HOCON (Human-Optimized Config Object Notation) files to define agent networks and tool configurations. Understanding how to implement optional environment variable substitution allows you to create flexible deployments that adapt to different runtime environments without breaking when specific variables are undefined.

Understanding the ${?...} Syntax in HOCON

Standard substitution in HOCON uses ${VAR_NAME} and fails if the variable is missing. Optional substitution uses ${?VAR_NAME} to handle absent variables gracefully.

According to the documentation in docs/user_guide.md (lines 148-153), the ${?...} syntax tells the pyhocon parser to treat the substitution as optional. If the environment variable is not set, the parser removes the entire key-value pair from the configuration object rather than raising an error. This behavior allows configurations to remain valid across local development, staging, and production environments without requiring every deployment to define the same set of variables.

Practical Use Cases for Optional Environment Variable Substitution

Feature Toggles and Experimental Flags

Use optional substitution to enable features only when specific flags are present in the environment:

features {
  experimental = ${?EXPERIMENTAL}
}

If EXPERIMENTAL is not defined, the experimental key disappears from the configuration, and the application uses default non-experimental behavior.

Dynamic Model Overrides in Agent Networks

Override LLM model names without breaking configurations that lack the variable:

llm_config {
  model_name = ${?MODEL_NAME}
}

As documented in docs/user_guide.md (lines 592-597), when MODEL_NAME=gemini-pro is set, the configuration uses that value; when absent, the line is omitted and the system falls back to the default model specified in code.

Optional Database Credentials

The repository demonstrates this pattern in registries/tools/pdf_rag.hocon for database connections:

connection_params {
  user = ${?POSTGRES_USER}
  password = ${?POSTGRES_PASSWORD}
  host = ${?POSTGRES_HOST}
}

If these environment variables are not present, the entire connection_params block can be omitted or handled by application logic that provides alternative storage mechanisms.

Implementation Examples from the Repository

The registries/manifest.hocon file uses optional substitution for tool configuration paths that may vary by deployment environment.

In mcp/mcp_info.hocon, the syntax appears in comments explaining secret injection patterns:

# Use ${?GITHUB_TOKEN} for optional authentication

The coded_tools/agent_network_designer/hocon_agent_network_assembler.py file dynamically constructs HOCON strings using ${} placeholders, which the parser later resolves against the environment.

How the pyhocon Parser Handles Missing Variables

When parsing configuration files, the pyhocon library distinguishes between mandatory and optional substitutions:

• Mandatory (${VAR}): Raises a ConfigSubstitutionException if the environment variable is undefined
• Optional (${?VAR}): Silently removes the configuration key if the variable is undefined

This behavior allows Neuro San Studio configurations to remain valid across different deployment contexts without requiring every environment to define the same set of variables.

Summary

• Use ${?VARIABLE_NAME} syntax for optional environment variable substitution in HOCON files
• The question mark indicates that the entire configuration line should be omitted if the variable is undefined
• This pattern appears throughout the cognizant-ai-lab/neuro-san-studio repository in docs/user_guide.md, registries/tools/pdf_rag.hocon, and other configuration files
• Optional substitution enables feature toggles, dynamic model overrides, and deployment-specific credentials without breaking configurations

Frequently Asked Questions

What happens if I use ${VAR} instead of ${?VAR}?

Using ${VAR} creates a mandatory substitution. If the environment variable VAR is not defined when the configuration loads, the pyhocon parser raises a ConfigSubstitutionException and the application fails to start. Use ${?VAR} when the variable is truly optional.

Can I use optional substitution with default values?

HOCON does not support default values directly within the substitution syntax. To provide a fallback, define the default in your application code when reading the configuration, or use a two-step approach where you check for the presence of the key after parsing. The ${?VAR} syntax only controls whether the key appears at all.

Where is the ${?...} syntax documented in Neuro San Studio?

The syntax is documented in docs/user_guide.md at lines 148-153, which explains how environment variables are substituted in HOCON files. Additional examples appear at lines 592-597 demonstrating optional model name overrides. The repository also uses this pattern extensively in registries/tools/pdf_rag.hocon for optional database credentials.

Does this work with all environment variables or only specific ones?

The ${?...} syntax works with any environment variable accessible to the process. The pyhocon parser reads from the standard environment variable namespace (e.g., os.environ in Python). There are no restrictions to specific variable names, though the repository commonly uses this pattern for API keys, database credentials, model names, and feature flags.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}