
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”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
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”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…).
Schema
Section titled “Schema”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" } }}
envFile
property
Section titled “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”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.
include: - "globalpath/*.genai.mjs"
modelAliases
property
Section titled “modelAliases property”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 } }}
modelEncodings
property
Section titled “modelEncodings property”The modelEncodings
property allows you to provide the encoding for the model.
{ "modelEncodings": { "azure:gpt__4o_random_name": "gpt-4o" }}
allowedDomains
property
Section titled “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.
allowedDomains: - github.com - '*.github.com' - '*.githubusercontent.com' - '*.openai.com' - example.org
{ "allowedDomains": [ "github.com", "*.github.com", "*.githubusercontent.com", "*.openai.com", "example.org" ]}
Wildcard Patterns
Section titled “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”You can also configure allowed domains via environment variables:
# Comma-separated listGENAISCRIPT_ALLOWED_DOMAINS=github.com,*.openai.com,example.org
# YAML array formatGENAISCRIPT_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.
Script-Level Override
Section titled “Script-Level Override”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 configurationconst data = await host.fetchText("https://api.example.com/data")
Script-level configuration takes precedence over global settings, providing fine-grained security control per script.
Debugging
Section titled “Debugging”Enable the config
debug category to see additional information about the configuration resolution.
You can also enable other debug categories for more detailed logs.
DEBUG=config genaiscript run ...