Configuration Reference

Every Griptape Nodes engine setting, grouped by category. Each setting can be placed in any griptape_nodes_config.json file (see Engine Configuration for the load order). Settings with a GTN_CONFIG_* env var, including the GTN_CONFIG_<NAME>__<SUB_KEY> form for a nested setting's scalar sub-keys and the GTN_CONFIG_<NAME>__<KEY> form for a mapping-valued setting's entries, can also be overridden from the environment; list-valued settings must be edited in a config file. A mapping's keys are matched case-sensitively but the whole variable name is lowercased, so only an already-lowercase key is reachable from the environment (see the guide for details).

File System

Directories and file paths for the application

Setting	Type	Default	Environment variable	Description
workspace_directory	string	<current_working_directory>/GriptapeNodes	GTN_CONFIG_WORKSPACE_DIRECTORY	Root directory for projects, workflows, and generated assets. Defaults to a GriptapeNodes folder under the current working directory. The other File System paths (libraries_directory, static_files_directory, sandbox_library_directory, synced_workflows_directory) are interpreted relative to this directory unless they are set to absolute paths.
static_files_directory	string	"staticfiles"	GTN_CONFIG_STATIC_FILES_DIRECTORY	Path to the static files directory, relative to the workspace directory.
sandbox_library_directory	string	"sandbox_library"	GTN_CONFIG_SANDBOX_LIBRARY_DIRECTORY	Path to the sandbox library directory (useful while developing nodes). Relative paths are interpreted relative to the workspace directory. Absolute paths are used as-is.
libraries_directory	string	"libraries"	GTN_CONFIG_LIBRARIES_DIRECTORY	Path to directory for downloaded libraries. All griptape_nodes_library.json files found recursively will be auto-discovered on startup. Relative paths are interpreted relative to the workspace directory. Absolute paths are used as-is. A project may override this location via the project-template libraries_dir field (inheritable down the parent-project chain), which takes precedence over this value so a child project can share its parent's library install location.
ffmpeg_directory	string	""	GTN_CONFIG_FFMPEG_DIRECTORY	Absolute path to the directory holding the ffmpeg/ffprobe binaries the engine downloads on first use. Unlike the other directory settings, this is never interpreted relative to the workspace: the ffmpeg cache belongs to the machine, not to a workspace, so it is shared across every workspace and project. A relative value is ignored with a warning. Empty (the default) means <XDG_DATA_HOME>/griptape_nodes/ffmpeg. To supply your own binaries instead of downloading, point this at a directory containing bin/<platform>/ holding ffmpeg, ffprobe, and an empty installed.crumb file - static-ffmpeg treats that marker as proof of a completed install, and re-downloads over the binaries whenever it is missing.
synced_workflows_directory	string	"synced_workflows"	GTN_CONFIG_SYNCED_WORKFLOWS_DIRECTORY	Path to the synced workflows directory, relative to the workspace directory.
enable_workspace_file_watching	boolean	true	GTN_CONFIG_ENABLE_WORKSPACE_FILE_WATCHING	Enable file watching for synced workflows directory

Application Events

Configuration for application lifecycle events

Setting	Type	Default	Environment variable	Description
app_events	object	(nested object)	GTN_CONFIG_APP_EVENTS__ON_APP_INITIALIZATION_COMPLETE__REQUIRES_ENGINE	Nested settings; the listed sub-keys can be set from the environment, and every sub-key can be edited directly in a config file.
app_events.on_app_initialization_complete	object	(nested object)	GTN_CONFIG_APP_EVENTS__ON_APP_INITIALIZATION_COMPLETE__REQUIRES_ENGINE	Nested settings; the listed sub-keys can be set from the environment, and every sub-key can be edited directly in a config file.
app_events.events_to_echo_as_retained_mode	array	(list of 22 values)	n/a (list/object; edit config file)	A list of values; edit it in a config file.

Execution

Workflow execution and processing settings

Setting	Type	Default	Environment variable	Description
log_level	one of CRITICAL, ERROR, WARNING, INFO, DEBUG	"INFO"	GTN_CONFIG_LOG_LEVEL	Logging verbosity for the engine. One of CRITICAL, ERROR, WARNING, INFO, or DEBUG, from least to most verbose.
workflow_execution_mode	one of sequential, parallel	"sequential"	GTN_CONFIG_WORKFLOW_EXECUTION_MODE	Workflow execution mode for node processing. SEQUENTIAL mode uses ParallelResolutionMachine with max_nodes_in_parallel=1 to execute nodes one at a time. PARALLEL mode uses the configured max_nodes_in_parallel value.
max_nodes_in_parallel	integer	5	GTN_CONFIG_MAX_NODES_IN_PARALLEL	Maximum number of nodes executing at a time for parallel execution.
worker	object	(nested object)	GTN_CONFIG_WORKER__HEARTBEAT_INTERVAL_S, GTN_CONFIG_WORKER__HEARTBEAT_TIMEOUT_S, GTN_CONFIG_WORKER__HEARTBEAT_STARTUP_GRACE_S	Nested settings; the listed sub-keys can be set from the environment, and every sub-key can be edited directly in a config file.
worker.heartbeat_interval_s	number	5.0	GTN_CONFIG_WORKER__HEARTBEAT_INTERVAL_S	Interval in seconds between worker heartbeat challenges sent by the orchestrator.
worker.heartbeat_timeout_s	number	15.0	GTN_CONFIG_WORKER__HEARTBEAT_TIMEOUT_S	Seconds without a heartbeat response before a worker is evicted.
worker.heartbeat_startup_grace_s	number	600.0	GTN_CONFIG_WORKER__HEARTBEAT_STARTUP_GRACE_S	Grace period in seconds after worker spawn before heartbeat timeouts are enforced. Workers need time to install venv deps and import modules before they can respond. First-time installs of large libraries (e.g. torch, diffusers) can easily exceed two minutes; this also bounds how long the orchestrator waits for worker libraries to load before marking them as FAILURE.

Logging

Where engine logs are kept and how much history is retained

Setting	Type	Default	Environment variable	Description
logging	object	(nested object)	GTN_CONFIG_LOGGING__LOG_TO_FILE, GTN_CONFIG_LOGGING__LOG_DIRECTORY, GTN_CONFIG_LOGGING__LOG_RETENTION_DAYS, GTN_CONFIG_LOGGING__SESSION_LOG_BUFFER_LINES	Nested settings; the listed sub-keys can be set from the environment, and every sub-key can be edited directly in a config file.
logging.log_to_file	boolean	true	GTN_CONFIG_LOGGING__LOG_TO_FILE	Write engine logs to a file as well as to the console. Each engine process writes its own file, rolling over at 10 MB and keeping 5 rollovers, so the total size per process is capped. Turn this off if you only ever need the logs from the session that is running right now.
logging.log_directory	string	""	GTN_CONFIG_LOGGING__LOG_DIRECTORY	Absolute path to the directory holding engine log files. Like ffmpeg_directory, this is never interpreted relative to the workspace: logs belong to the machine, not to a workspace, so every workspace and project shares one location. A relative value is ignored with a warning. Empty (the default) means <XDG_DATA_HOME>/griptape_nodes/logs.
logging.log_retention_days	integer	7	GTN_CONFIG_LOGGING__LOG_RETENTION_DAYS	Delete engine log files that have not been written to for this many days. Checked when the engine starts, and again whenever a logging setting changes. The log file the engine is currently writing is never deleted, however old it is. Set to 0 to keep log files forever.
logging.session_log_buffer_lines	integer	5000	GTN_CONFIG_LOGGING__SESSION_LOG_BUFFER_LINES	How many of the most recent log lines the engine keeps in memory for the current session, so a problem report includes what just happened without you having to reproduce it. These lines carry whatever log_level allows, so raise log_level to DEBUG before reproducing a problem if you need debug detail in the report. Set to 0 to disable, which means a problem report can only include whatever reached the log files.

Storage

Data storage and persistence configuration

Setting	Type	Default	Environment variable	Description
storage_backend	one of local, gtc	"local"	GTN_CONFIG_STORAGE_BACKEND	Backend used to persist workflow data and generated assets. 'local' stores files on the local filesystem under the workspace; 'gtc' uses Griptape Cloud storage.
auto_inject_workflow_metadata	boolean	true	GTN_CONFIG_AUTO_INJECT_WORKFLOW_METADATA	Automatically inject workflow metadata into saved files with supported formats
thread_storage_backend	"local" (constant)	"local"	GTN_CONFIG_THREAD_STORAGE_BACKEND	Storage backend for conversation threads. Only 'local' (filesystem) is supported; Griptape Cloud support was removed in the Pydantic AI migration.

System Requirements

System resource requirements and limits

Setting	Type	Default	Environment variable	Description
minimum_disk_space_gb_libraries	number	10.0	GTN_CONFIG_MINIMUM_DISK_SPACE_GB_LIBRARIES	Minimum disk space in GB required for library installation and virtual environment operations
minimum_disk_space_gb_workflows	number	1.0	GTN_CONFIG_MINIMUM_DISK_SPACE_GB_WORKFLOWS	Minimum disk space in GB required for saving workflows
discovery_max_depth	integer	5	GTN_CONFIG_DISCOVERY_MAX_DEPTH	Maximum directory depth the engine walks when a registered entry points at a directory to recursively discover files (e.g. project files under projects_to_register). Bounds boot-time scans against pathologically deep trees and symlink loops. 0 scans only the top-level directory; each nested level adds 1.

MCP Servers

Model Context Protocol server configurations

Setting	Type	Default	Environment variable	Description
mcp_servers	array	[]	n/a (list/object; edit config file)	List of Model Context Protocol server configurations

Static Server

Static file server configuration for serving media assets

Setting	Type	Default	Environment variable	Description
static_server_base_url	string	null	GTN_CONFIG_STATIC_SERVER_BASE_URL	Base URL for the static server. Leave unset to derive it from the server's host/port (including the OS-assigned port when the configured port is unavailable). Set this only to override the derived URL, e.g. when fronting the server with a tunnel (ngrok, cloudflare) or reverse proxy.

Artifacts

Settings for artifact providers and preview generation

Setting	Type	Default	Environment variable	Description
artifacts	object	{}	GTN_CONFIG_ARTIFACTS__<KEY>	Control how previews are generated for images and other media files

Projects

Project template configurations and registrations

Setting	Type	Default	Environment variable	Description
project_file	string	null	GTN_CONFIG_PROJECT_FILE	Path to the project file (griptape-nodes-project.yml) to load initially when the engine starts. When set, overrides the default location of \/griptape-nodes-project.yml. If the specified path does not exist, falls back to the workspace default. The sentinel value '' means the engine deliberately stays on system defaults and suppresses the workspace-default fallback (so a workspace griptape-nodes-project.yml is not auto-discovered); this is what the engine persists when it is intentionally on system defaults.
project_workspaces	object	{}	GTN_CONFIG_PROJECT_WORKSPACES__<KEY>	Mapping of project identifiers to workspace directory overrides. A key may be either a project ID or a project file path: it is first matched against loaded project IDs, and if none match, treated as a project file path. When a project is loaded, if it matches a key here, the corresponding value is used as the workspace directory instead of the project-adjacent config or auto-default.

Agent

Agent behavior and system prompt

Setting	Type	Default	Environment variable	Description
agent	object	(nested object)	GTN_CONFIG_AGENT__SYSTEM_PROMPT	Nested settings; the listed sub-keys can be set from the environment, and every sub-key can be edited directly in a config file.
agent.system_prompt	string	""	GTN_CONFIG_AGENT__SYSTEM_PROMPT	Additional text appended to the agent's built-in system prompt. Use to customize tone, preferred patterns, or domain context.

Libraries

Settings for library management and dependency installation

Setting	Type	Default	Environment variable	Description
library	object	(nested object)	GTN_CONFIG_LIBRARY__DEPENDENCY_INSTALL_BEHAVIOR, GTN_CONFIG_LIBRARY__LAZY_NODE_LOADING, GTN_CONFIG_LIBRARY__MINIMUM_RELEASE_AGE	Nested settings; the listed sub-keys can be set from the environment, and every sub-key can be edited directly in a config file.
library.dependency_install_behavior	one of always, never	"always"	GTN_CONFIG_LIBRARY__DEPENDENCY_INSTALL_BEHAVIOR	Controls automatic installation of library dependencies declared in library manifests. 'always' downloads and installs them on registration. 'never' skips installation and marks the library as degraded if required dependencies are missing.
library.lazy_node_loading	boolean	true	GTN_CONFIG_LIBRARY__LAZY_NODE_LOADING	When True (the default), a node's Python module is imported lazily the first time a node of that type is created (or the type is otherwise resolved, such as when introspected) rather than at startup, which speeds up engine startup for libraries with many or heavy nodes. The tradeoff is that a broken node's import error is not reported until that type is first created. When False, the engine imports every node's Python module at startup, so an import error surfaces immediately as a library problem, before the node is placed on a canvas; set this while authoring nodes if you want that check. Nodes in the sandbox library are always loaded eagerly regardless of this setting.
library.minimum_release_age	number	0.0	GTN_CONFIG_LIBRARY__MINIMUM_RELEASE_AGE	Minimum age, in hours, of the target release before a library update is applied. When 0 (the default), updates apply as soon as they are available. When greater than 0, an update is withheld until the commit it would move to is at least this many hours old, guarding against automatically adopting a freshly-pushed release before there is time to catch and yank a bad one. If the target commit's age cannot be determined (e.g. the remote timestamp is unreadable), the update is allowed (fail-open) and a warning is logged, so a metadata hiccup never permanently blocks updates. Age is measured from the target commit's git committer timestamp, which is not necessarily when the release was published: rebased, cherry-picked, backdated (GIT_COMMITTER_DATE), or force-moved tags can report an age that differs from the actual publish time.