Directories

Directories are logical name-to-path mappings. Instead of hard-coding a path like outputs/renders everywhere, you give it a name (outputs) and use that name in macros. If you later change where outputs should go, you update the directory definition in one place.

Default directories

The system defaults define six directories:

Name	Default path	Description
inputs	inputs	Files brought into the project — uploads, copies, and downloads.
outputs	outputs	Files generated by nodes during workflow execution.
temp	temp	Temporary scratch files; safe to delete between runs.
griptape-nodes-previews	.griptape-nodes-previews	Generated preview/thumbnail artifacts; mirrors source-file hierarchy.
griptape-nodes-metadata	.griptape-nodes-metadata	Sidecar metadata for project files; mirrors source-file hierarchy.
griptape-nodes-thumbnails	.griptape-nodes-thumbnails	Workflow thumbnail images shown in the UI.

All default paths are relative and resolve against the project base directory.

Using directory names in macros

Directory names are available as variables in any macro. When a macro is resolved, the project system automatically substitutes the directory name with its configured path:

Template:  {outputs}/{file_name_base}.{file_extension}
           ↓
Resolved:  outputs/my_image.png

You do not supply directory values yourself — they come from the directory definitions. Directory names are reserved: if you try to pass a variable with the same name as a directory, the system will reject it with an error to prevent ambiguity.

Customizing directory paths

Override a directory's path in your griptape-nodes-project.yml:

project_template_schema_version: "0.1.0"
name: "My Project"

directories:
  outputs:
    path_macro: "renders/final"

Now {outputs} in any macro resolves to renders/final instead of outputs.

Directory descriptions

Each directory definition can carry an optional description — a human-readable explanation of what the directory is for and how it's meant to be used. Descriptions are surfaced in tools that display project directories (such as the Project Management screen in the GUI) and make hand-edited project YAMLs easier to understand.

directories:
  outputs:
    path_macro: "renders/final"
    description: "Final renders ready for delivery to clients."

description is optional and defaults to null. To clear an inherited description from a base or parent template, set it to null in your overlay:

directories:
  outputs:
    description: null

Adding new directories

Add a directory that doesn't exist in the defaults:

directories:
  deliverables:
    path_macro: "client_deliverables"

Once added, {deliverables} is available in any macro.

Directory paths with macros

The path_macro field supports tilde (~) expansion, macro syntax, and environment variable references:

directories:
  downloads:
    path_macro: "~/Downloads"

This maps the downloads directory to the current user's Downloads folder, regardless of the machine it runs on.

directories:
  outputs:
    path_macro: "$OUTPUT_BASE/renders"

If $OUTPUT_BASE is set in your environment (or in the project's environment section), it will be substituted when the path is resolved.

You can also reference builtin variables in directory paths:

directories:
  outputs:
    path_macro: "{workflow_dir}/renders"

This makes the outputs directory relative to the current workflow's location rather than the project base directory.

Per-platform paths

A directory's path_macro can be a single string (used everywhere) or a per-platform mapping when the right path differs across operating systems. Use this when a workspace is shared between collaborators on Linux, macOS, and Windows and the directory needs a different absolute location on each.

directories:
  scratch:
    path_macro:
      linux: "/mnt/fast-scratch"
      darwin: "/Volumes/scratch"
      windows: "D:/scratch"
      default: "{workspace_dir}/scratch"

At resolution time, the engine picks the entry matching the current platform (linux, darwin, or windows). If the active platform's key is unset, it falls back to default. At least one of the four keys must be supplied; otherwise the project fails validation.

directories:
  models:
    path_macro:
      darwin: "~/Library/Caches/models"
      default: "{workspace_dir}/.models"

Per-platform values support the same syntax as the string form — tilde expansion, environment variables, and macros all work the same way per platform.

The mapping is atomic during overlay merges: a child template that supplies a per-platform mapping fully replaces the parent's path_macro, rather than merging key-by-key. To keep one platform's value while overriding another, restate every key you want kept.

Reserved names

Directory names are reserved across the entire variable namespace. You cannot use a directory name as a user-supplied variable in a macro call — the system will return an error if you try. This protects against accidentally overriding a directory path through a variable name collision.

The builtin variables (project_dir, workspace_dir, workflow_name, workflow_dir, static_files_dir) are also reserved and cannot be overridden. See Environment & Builtin Variables.