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

> Learn to use environment variable substitution in HOCON configurations with `${VAR}` for required and `${?VAR}` for optional variables. Streamline your Neuro-SAN Studio setup.

- Repository: [Cognizant AI Lab/neuro-san-studio](https://github.com/cognizant-ai-lab/neuro-san-studio)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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`:

```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`:

```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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/docs/user_guide.md):

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

```

## Practical Implementation Patterns

### Runtime LLM Selection

Switch models without modifying configuration files:

```bash
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:

```hocon

# registries/tools/openai_image_generation.hocon

"api_key": ${OPENAI_API_KEY}

```

### Feature Flags

Enable debug modes or experimental features conditionally:

```hocon
"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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/docs/user_guide.md) file provides specific examples for local development.