Skip to content
An 8-bit style illustration features four colored squares stacked to represent different types of files such as .env and config files. Each square shows a unique icon: a keyhole for secrets, a spark for scripts, a gear for configuration, and a chain link for include files. Above the stack, a swirling line connects them, suggesting the merging or combining of these files. The design is simple, minimal, uses five flat colors, and has no people or background elements.

Configuration Files

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

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
Terminal window
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

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 format (including comments, trailing commas, etc…).

The configuration schema is at https://microsoft.github.io/genaiscript/schemas/config.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"
}
}
}

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

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
include:
- "globalpath/*.genai.mjs"

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

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

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

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

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.

genaiscript.config.yml
allowedDomains:
- github.com
- '*.github.com'
- '*.githubusercontent.com'
- '*.openai.com'
- example.org
genaiscript.config.json
{
"allowedDomains": [
"github.com",
"*.github.com",
"*.githubusercontent.com",
"*.openai.com",
"example.org"
]
}

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)

You can also configure allowed domains via environment variables:

Terminal window
# Comma-separated list
GENAISCRIPT_ALLOWED_DOMAINS=github.com,*.openai.com,example.org
# YAML array format
GENAISCRIPT_ALLOWED_DOMAINS='["github.com", "*.openai.com", "example.org"]'

When a domain is blocked, you’ll see a clear error message explaining how to configure allowed domains.

Individual scripts can override the global allowedDomains configuration by specifying their own list:

script({
title: "API Integration Script",
allowedDomains: [
"github.com",
"*.api.example.com",
"secure.partner.org"
]
})
// This script can only access the domains listed above,
// regardless of global configuration
const data = await host.fetchText("https://api.example.com/data")

Script-level configuration takes precedence over global settings, providing fine-grained security control per script.

Enable the config debug category to see additional information about the configuration resolution.

You can also enable other debug categories for more detailed logs.

Terminal window
DEBUG=config genaiscript run ...