Environment variables

FlowForge v3 currently ships a deliberately minimal environment-variable surface. The variables documented here override settings in .flowforge/config.yml at the per-process level — useful for short-lived debug sessions, CI runs, and per-shell tweaks. Environment variables are read once per process; they do not persist into config.yml and do not survive across shells.

The list will grow with each v3 release as new runtime knobs are promoted from internal to user-facing. This page only documents what is wired up today; everything else is forward-looking and clearly labelled as such.

Implemented today

FF_STALE_THRESHOLD_SECS

Attribute	Value
Type	positive integer (seconds)
Default	900 (15 minutes)
Source	v3/internal/claude/stale.go
Related config	(none — runtime-only knob)

Overrides the threshold used by FlowForge’s stale-Claude detection daemon. A Claude session is considered stale when it remains in StatusBusy and produces no pane output for the threshold duration. When that happens, the daemon flags the session for operator attention.

The default of 900 seconds (15 minutes) is calibrated for typical interactive sessions — long enough to absorb genuine deep-thinking pauses, short enough to surface a hung session within a coffee break.

When to tune it down. Debugging a flaky integration; running fast-feedback CI smoke tests where any pause longer than a few minutes is suspicious; pairing sessions where you want quick visibility into stuck agents.

When to tune it up. Workloads with known long pauses — large model warm-ups, slow build steps inside the agent loop, or pipelines that legitimately wait minutes on external services.

Validation. The value must be a positive integer. Non-numeric input, zero, and negative values are silently ignored and the default (900) is used. There is no upper bound.

# Aggressive: flag stale sessions after 5 minutes (debugging, fast CI).
FF_STALE_THRESHOLD_SECS=300 flowforge run dev:status

# Conservative: tolerate 30-minute pauses (long-running build agents).
FF_STALE_THRESHOLD_SECS=1800 flowforge run dev:status

Reserved — do not set

Caution

FlowForge reserves a small set of names for internal security boundaries. These are not user-facing knobs. Setting them by hand to bypass a hook or guardrail is a security-policy violation under FlowForge Rule #38; if a hook blocks a legitimate action, escalate the block instead of working around it.

• FLOWFORGE_BYPASS — reserved as a security boundary. Setting it to bypass FlowForge enforcement is a Rule #38 violation. Escalate the underlying friction to the FlowForge team instead.
• FLOWFORGE_AUTH_TOKEN — internal authentication artifact, not a user knob. Setting it manually is also a Rule #38 violation.

Planned for future releases

The variables in this table are not yet implemented and have no effect if set today. They are documented here to communicate the planned shape of the configuration surface; setting them in production is at best a no-op and at worst misleading to other operators reading your shell history. Wait for the release notes that announce each one before adopting it.

Variable	Planned purpose
FLOWFORGE_LOG_LEVEL	Log severity threshold for FlowForge runtime output.
FLOWFORGE_DEBUG	Verbose debug logging toggle.
FLOWFORGE_CONFIG	Override path to config.yml.
FLOWFORGE_HOME	Override the FlowForge state directory.
FLOWFORGE_TIMEZONE	Timezone used in time-tracking reports.
FLOWFORGE_GH_TIMEOUT	Timeout (seconds) for GitHub API calls.
FLOWFORGE_GH_MAX_ATTEMPTS	Retry budget for GitHub API calls.
FLOWFORGE_TEAM_MODE	Enables team-workflow features.

Caution

None of the variables in the table above are wired into v3 today. Do not set them in production environments — they will not influence behavior, and other operators reading your environment may be misled into thinking they do.

See also

• Configuration overview — high-level model.
• config.yml schema — fields the environment may override once the planned variables ship.