How to Use Environment Variable Substitution in HOCON Configuration in Neuro-SAN Studio

Use ${VAR} for required environment variables that must exist at runtime, and ${?VAR} for optional variables that can be omitted without causing configuration errors.

Neuro-SAN Studio stores agent network definitions, tool configurations, and LLM settings in HOCON files (*.hocon). Environment variable substitution in HOCON configuration allows you to externalize secrets, API keys, and deployment-specific settings without hard-coding them into your configuration files, enabling secure and portable deployments across development, staging, and production environments.

HOCON Substitution Syntax Explained

Neuro-SAN Studio uses the standard HOCON parser, which supports two primary substitution patterns for environment variables.

Required Variables with ${VAR}

The ${VAR} syntax inserts the value of an environment variable directly into the configuration. If the variable is not set, the parser throws an error and the configuration fails to load.

Example from registries/tools/google_search.hocon:

"api_key": ${GOOGLE_SEARCH_API_KEY}
"cse_id":  ${GOOGLE_SEARCH_CSE_ID}

Optional Variables with ${?VAR}

Use ${?VAR} for optional configuration values. If the environment variable is undefined, the entire key-value pair is omitted from the configuration rather than causing an error.

Example from registries/basic/music_nerd.hocon:

"llm_config": {
    "model_name": ${?MODEL_NAME}
}

If MODEL_NAME is not set, the model_name key disappears and the system falls back to the default defined in neuro_san/internals/run_context/langchain/llms/default_llm_info.hocon.

String Concatenation Limitations

Substitutions do not work inside quoted strings. To combine environment variables with literal text, concatenate them outside of quotes as shown in the docs/user_guide.md:

"instructions": ${instruction_prefix} " main part " ${instruction_suffix}

Practical Implementation Patterns

Runtime LLM Selection

Switch models without modifying configuration files:

export MODEL_NAME="claude-3-7-sonnet"
python -m run

The ${?MODEL_NAME} substitution in your agent's HOCON file overrides the default model while maintaining backward compatibility when the variable is unset.

Secure Credential Injection

Keep secrets out of version control by referencing environment variables in tool configurations:

# registries/tools/openai_image_generation.hocon

"api_key": ${OPENAI_API_KEY}

Feature Flags

Enable debug modes or experimental features conditionally:

"debug_mode": ${?ENABLE_DEBUG}

When ENABLE_DEBUG is unset, the key vanishes and the application uses its internal default.

Key Configuration Files

The following files demonstrate environment variable substitution patterns in the Neuro-SAN Studio repository:

• docs/user_guide.md – Documents HOCON import and substitution syntax (lines 14-63)
• registries/basic/music_nerd.hocon – Shows optional ${?MODEL_NAME} usage for LLM selection
• registries/tools/google_search.hocon – Demonstrates required ${GOOGLE_SEARCH_API_KEY} substitution
• neuro_san/internals/run_context/langchain/llms/default_llm_info.hocon – Defines system-wide defaults that environment variables can override

Summary

• Use ${VAR} for required environment variables; the configuration fails if the variable is missing.
• Use ${?VAR} for optional values; the key is omitted if the variable is undefined.
• Never place substitutions inside quoted strings; concatenate unquoted references instead.
• Environment variable substitution in HOCON configuration enables secure, portable agent definitions across development, staging, and production environments.

Frequently Asked Questions

What happens if a required environment variable is not set?

The HOCON parser throws an error during configuration loading, preventing the application from starting. This ensures that critical credentials or settings cannot be accidentally omitted in production deployments.

Can I use default values with environment variable substitution?

Standard HOCON does not support default values in the substitution syntax itself. To achieve defaults, use optional substitution ${?VAR} and rely on the application to provide an internal default when the key is missing, or structure your includes to provide fallback values in separate files.

Why does my substitution not work inside a quoted string?

HOCON treats quoted strings as literal values. The parser does not evaluate ${...} sequences inside double quotes. To build dynamic strings, concatenate unquoted substitutions with quoted literals: ${PREFIX} "middle" ${SUFFIX}.

Where are environment variables typically set in a Neuro-SAN deployment?

Set environment variables in your shell before running python -m run, in a .env file loaded by your orchestration tool, or in the container environment if deploying via Docker or Kubernetes. The docs/user_guide.md file provides specific examples for local development.

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