Configuration

Grog is configured using a grog.toml file that is placed in the root of your workspace. Find below a complete example of a grog configuration file:

# Workspace Settings
root = "/home/grace/grog_data"
requires_grog = ">=0.15.0"
# cache_namespace = "org-myrepo" # optional — opt-in target cache namespace

# Execution Settings
fail_fast = true # Exit immediately when encountering an issue
num_workers = 4
load_outputs = "minimal"
hash_algorithm = "xxh3" # default
# Disable injecting "set -eu" before running target commands
# disable_default_shell_flags = true

# Target Selection
all_platforms = false

# Logging Settings
stream_logs = true
log_level = "info"

# Environment Variables
environment_variables = { FOO = "bar" }

# Cache Settings
enable_cache = true # default
async_cache_writes = true # default
# num_io_workers = 12 # defaults to 3 * num_workers

[cache]
backend = "gcs"  # Options: "" (local), "gcs", "s3", "azure"

[cache.gcs]
bucket = "my-gcs-bucket"
prefix = "grog-cache/"

# [cache.s3]
# bucket = "my-s3-bucket"
# prefix = "grog-cache/"

# [cache.azure]
# account_url = "https://myaccount.blob.core.windows.net/"
# container = "my-azure-container"
# prefix = "grog-cache/"

# Trace Settings
[traces]
enabled = true
# Optionally use a separate backend for traces:
# backend = "s3"
# [traces.s3]
#   bucket = "my-traces-bucket"

All value in this file can be overridden at runtime by passing an environment variable of the same name prefixed with GROG_. For instance, to set or override the fail_fast option set GROG_FAIL_FAST=false.

Configuration Variables Explained

• root: The base directory where Grog stores its internal files. Defaults to ~/.grog.
• cache_namespace: Optional namespace for the target cache under root. The target cache is flat by default (stored at $GROG_ROOT/cache/) so that the same repo checked out at different absolute paths (e.g. ephemeral CI runners) shares cache hits — this is safe because cache keys already hash their complete inputs. Setting cache_namespace moves the cache to $GROG_ROOT/<cache_namespace>/cache/ to isolate it from other projects on the same machine. Logs and the workspace lockfile remain keyed by the absolute workspace path regardless, so parallel grog invocations in different checkouts never conflict.
• requires_grog: A semver range that the running Grog binary must satisfy. If the version is outside of this range Grog exits with an error.
• fail_fast: When true, Grog will stop execution after encountering the first error, cancelling all running tasks. Defaults to false.
• num_workers: Number of concurrent workers for parallel task execution. Defaults to the number of CPUs.
• log_level: Determines verbosity of logging (e.g., “debug”, “info”). Defaults to info.
• stream_logs: When true, Grog will stream build and test logs to stdout. Defaults to false.
• disable_default_shell_flags: When false (default), Grog prepends set -eu to target commands before execution to fail fast on unset variables and errors. Set to true to opt out.
• environment_variables: Key-value pairs that will be set for all target executions and passed to the Pkl loader.
• enable_cache: Controls whether caching is enabled. Defaults to true.
• load_outputs: Determines what outputs are loaded from the cache. Available options are:
  • all (default): Load all outputs from the cache.
  • minimal: Only load outputs of a target if a direct dependant needs to be re-built. This setting is useful to save bandwidth and disk space in CI settings.
• hash_algorithm: Selects the hash function used for cache keys and change detection. xxh3 (default) offers extremely fast, 128-bit hashes with a negligible collision probability for typical builds, while sha256 is slower but cryptographically strong—use it if you are hashing untrusted inputs or want a vanishingly small risk of collisions despite the performance cost.
• all_platforms: When set to true skips the platform selection step and builds all targets for all platforms (read more).
• async_cache_writes: When true (default), cache writes are offloaded to a dedicated I/O worker pool, freeing task workers to start downstream targets sooner. Output hashes are still computed synchronously so dependency chains and cache keys stay correct. The I/O pool is drained before the build returns, and its progress is shown alongside running targets in the build UI. Write failures are non-fatal warnings — the build result is unaffected. Set to false to run cache writes inline on task workers (the pre-0.18 behaviour).
• num_io_workers: Number of I/O workers for async cache writes. Only relevant when async_cache_writes is true. Defaults to 3 * num_workers.
• skip_workspace_lock: When true, Grog does not acquire a workspace-level lock before executing. Warning: Running multiple grog instances without locking can corrupt the workspace or cache.

Trace Settings

• traces.enabled: When true, Grog records an execution trace for every build, test, and run invocation. Traces capture per-target phase-level timing data for performance analysis. Defaults to false.
• traces.backend: Override the storage backend for traces. When not set, traces use the same backend as the build cache. Supports "gcs" and "s3".
• traces.gcs.bucket / traces.s3.bucket: Bucket name for trace storage when using a separate backend.
• traces.gcs.prefix / traces.s3.prefix: Optional prefix within the bucket. Defaults to /.

See Execution Traces for usage details and dashboard integration.

Profiles

Grog supports profiles, which allow you to define a set of configuration options that can be used to override the default configuration. For instance you might want to have a default grog.toml aswell as a grog.ci.toml for ci use cases and a grog.local.toml for local development. You can select those profiles by passing the --profile flag to grog or setting the GROG_PROFILE environment variable.

Most CI runners by default set CI=1 which will cause Grog to automatically use the grog.ci.toml profile.