# Configuration Files

> Learn how to configure common configuration settings using configuration files

GenAIScript supports local and global configuration files to allow reusing common configuration settings and secrets across multiple scripts.

## .env file resolution

[Section titled “.env file resolution”](#env-file-resolution)

GenAIScript will scan, load the following `.env` files in the following order:

* `envFile` property in the configuration files (see below)
* `GENAISCRIPT_ENV_FILE` environment variable
* `--env` command line options

```sh
genaiscript run ... --env ./.env.debug --env ~/.env.dev
```

If none of the above are set, it will try to load the following files:

* `~/.env`
* `./.env`
* `./.env.genaiscript`

### config file resolution

[Section titled “config file resolution”](#config-file-resolution)

GenAIScript will scan for the following configuration files and merge their content into the final configuration.

* `~/genaiscript.config.yaml`
* `~/genaiscript.config.json`
* `./genaiscript.config.yaml`
* `./genaiscript.config.json`

The JSON files support the [JSON5](https://json5.org/) format (including comments, trailing commas, etc…).

## Schema

[Section titled “Schema”](#schema)

The configuration schema is at <https://microsoft.github.io/genaiscript/schemas/config.json> .

```json
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "GenAIScript Configuration",
    "type": "object",
    "description": "Schema for GenAIScript configuration file",
    "properties": {
        "envFile": {
            "oneOf": [
                {
                    "type": "string",
                    "description": "Path to a .env file to load environment variables from"
                },
                {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "description": "Path to a .env file to load environment variables from"
                    },
                    "description": "List of .env files"
                }
            ]
        },
        "include": {
            "description": "List of files to include in the project",
            "type": "array",
            "items": {
                "type": "string",
                "description": "Path to a file or a glob pattern to include in the project"
            }
        },
        "modelEncodings": {
            "type": "object",
            "patternProperties": {
                "^[a-zA-Z0-9_:]+$": {
                    "type": "string",
                    "description": "Encoding identifier",
                    "enum": [
                        "o1",
                        "gpt-4o",
                        "gpt-3.5-turbo",
                        "text-davinci-003",
                        "o200k_base",
                        "cl100k_base",
                        "p50k_base",
                        "r50k_base"
                    ]
                }
            },
            "additionalProperties": true,
            "description": "Equivalent encoders for model identifiers"
        },
        "modelAliases": {
            "type": "object",
            "patternProperties": {
                "^[a-zA-Z0-9_]+$": {
                    "oneOf": [
                        {
                            "type": "string",
                            "description": "Model identifier (provider:model:tag)"
                        },
                        {
                            "type": "object",
                            "properties": {
                                "model": {
                                    "type": "string",
                                    "description": "Model identifier (provider:model:tag)"
                                },
                                "temperature": {
                                    "type": "number",
                                    "description": "Temperature to use for the model"
                                }
                            },
                            "required": [
                                "model"
                            ]
                        }
                    ]
                }
            },
            "additionalProperties": true,
            "description": "Aliases for model identifiers (name)"
        },
        "secretPatterns": {
            "type": "object",
            "patternProperties": {
                "^[a-zA-Z0-9_:\\-\\. ]+$": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Secret regex"
                }
            },
            "additionalProperties": true,
            "description": "Secret scanners to use for scanning chat messages"
        }
    }
}
```

## `envFile` property

[Section titled “envFile property”](#envfile-property)

The final location of `envFile` will be used to load the secret in the environment variables. It supports a single

## `include` property

[Section titled “include property”](#include-property)

The `include` property allows you to provide glob paths to include more scripts. Combined with a global configuration file, this allows to share script for a number of projects.

genaiscript.config.yaml

```yaml
include:
    - "globalpath/*.genai.mjs"
```

## `modelAliases` property

[Section titled “modelAliases property”](#modelaliases-property)

The `modelAliases` property allows you to provide aliases for model names.

```js
{
    "modelAliases": {
        "llama32": "ollama:llama3.2:1b",
        "llama32hot": {
            "model": "ollama:llama3.2:1b",
            "temperature": 2
        }
    }
}
```

## `modelEncodings` property

[Section titled “modelEncodings property”](#modelencodings-property)

The `modelEncodings` property allows you to provide the encoding for the model.

```js
{
    "modelEncodings": {
        "azure:gpt__4o_random_name": "gpt-4o"
    }
}
```

## `allowedDomains` property

[Section titled “allowedDomains property”](#alloweddomains-property)

The `allowedDomains` property controls which domains are allowed for HTTPS resource resolution via `host.resolveResource()` and `host.fetchText()`. By default, all domains are allowed (`*`) for convenience, but you can restrict access for security.

Important: API-Level Filtering Only

Domain filtering **only applies to GenAIScript’s host APIs** (`host.fetchText`, `host.resolveResource`). It does **NOT** restrict:

* Global `fetch()` function
* Third-party libraries making HTTP requests
* Direct network calls from imported packages

This is not an egress proxy - for broader network security, use firewalls or other network-level controls.

genaiscript.config.yml

```yaml
allowedDomains:
  - github.com
  - '*.github.com'
  - '*.githubusercontent.com'
  - '*.openai.com'
  - example.org
```

genaiscript.config.json

```json
{
    "allowedDomains": [
        "github.com",
        "*.github.com",
        "*.githubusercontent.com",
        "*.openai.com",
        "example.org"
    ]
}
```

### Wildcard Patterns

[Section titled “Wildcard Patterns”](#wildcard-patterns)

Domain patterns support glob-style wildcards:

* `github.com` - Exact match only
* `*.github.com` - Matches any subdomain (e.g., `api.github.com`)
* `*` - Matches all domains (use with caution)

### Environment Variable

[Section titled “Environment Variable”](#environment-variable)

You can also configure allowed domains via environment variables:

```bash