Skip to content
OpenWaggle

Environment variables

Every environment variable OpenWaggle, its command line and its install script read, and the ones it sets for the commands it runs.

This page lists every environment variable that OpenWaggle, the openwaggle command and the install script read, and the variables OpenWaggle sets for the commands it starts. A variable reaches only the process started with it and the processes that one starts.

Where the desktop app gets its environment

An app opened from the Dock, the Start menu or a desktop launcher does not see variables exported in your shell profile. At launch, the desktop app reads only these from your login shell:

GroupVariablesWhen the app takes them
PathPATHOn every platform, merged with the app’s own. On Windows it comes from PowerShell with and without your profile, plus common tool folders
Sockets and foldersSSH_AUTH_SOCK, DISPLAY, WAYLAND_DISPLAY, XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_RUNTIME_DIRmacOS and Linux, when the app has none
HomebrewHOMEBREW_PREFIX, HOMEBREW_CELLAR, HOMEBREW_REPOSITORYmacOS and Linux, when the app has none
Desktop sessionDBUS_SESSION_BUS_ADDRESS, XDG_CURRENT_DESKTOP, XDG_SESSION_DESKTOP, XDG_SESSION_TYPEmacOS and Linux
LocaleLANG, LC_ALL, LC_CTYPEmacOS, when the app has none of them. With none set anywhere, the app uses LC_CTYPE=en_US.UTF-8
fnmFNM_DIR, FNM_MULTISHELL_PATHWindows, when the app has none

Any other variable, such as DO_NOT_TRACK or a provider API key, reaches the desktop app only if it was in the app’s own environment when it started. Values in MCP server files written as ${NAME} are an exception. OpenWaggle reads them from your login shell. See MCP.

The Session Host that the desktop app starts keeps the app’s environment. A Session Host that an openwaggle command starts keeps that command’s environment. A Session Host that is already running keeps its own.

Usage statistics

Any one of these turns off usage statistics and error reports for the process. Turn them off explains how they combine with the Settings switch.

VariableTurns statistics off whenDefault
DO_NOT_TRACKSet to anything other than empty, 0, false, no or off, in any caseNot set
PI_TELEMETRYSet to anything other than 1, true or yes (true and yes in any case), even an empty value. Also removes Pi’s provider labelsNot set
CISet to anything other than empty, 0, false, no or off, in any case. CI services set itNot set
OPENWAGGLE_AUTOMATIONSet to 1, which marks an automated test launch. It also stops the app and its Session Host from opening dialogs or browser windowsNot set

App and CLI

VariableWhat it doesDefault
OPENWAGGLE_USER_DATA_DIRUses this folder as the app data folder, for the desktop app, the Session Host and the openwaggle command. Logs go to its logs/ folderThe platform’s app data folder
OPENWAGGLE_LOG_LEVELLowest level written to the logs: debug, info, warn or error. The Session Host the app starts gets the same levelinfo
OPENWAGGLE_PROFILERuns openwaggle commands as this named access profile, like --profile. See Hive CLINot set, so commands run as you
OPENWAGGLE_PROFILE_CREDENTIAL_FILEReads the access profile’s credential from this file, like --profile-credential-file. Needs --profile or OPENWAGGLE_PROFILEThe credential store
OPENWAGGLE_DISABLE_SINGLE_INSTANCESet to 1 to let another copy of the desktop app open while one is runningNot set
OPENWAGGLE_COMPILE_CACHE_DIRKeeps the startup cache in this folder. Must be an absolute pathThe platform’s cache folder
OPENWAGGLE_DISABLE_COMPILE_CACHESet to 1 to keep no startup cache. Node’s own NODE_DISABLE_COMPILE_CACHE works tooNot set
LOCALAPPDATA, XDG_CACHE_HOMEWhere the startup cache goes on Windows and Linux~\AppData\Local, ~/.cache
XDG_CONFIG_HOMEWhere the app data folder goes on Linux~/.config

Pi

Pi, the agent engine inside OpenWaggle, reads these itself. Pi’s environment variables lists the rest, and Pi providers lists the API key variable for each provider.

VariableWhat it doesDefault
PI_CODING_AGENT_DIRPi’s agent folder, with auth.json, models.json, settings.json, mcp.json and Waggle presets~/.pi/agent
PI_CODING_AGENT_SESSION_DIRWhere Pi session files go. OpenWaggle looks for sessions there and stores its new sessions theresessions/ in the agent folder, or Pi’s sessionDir setting
PI_TELEMETRYSee Usage statisticsNot set
PI_PACKAGE_DIROpenWaggle always sets this for its own bundled Pi. Terminals and shells it starts get your own value back, or noneYour value, if any

Install script

scripts/install.sh reads these. Put them before bash in the install command, as in OPENWAGGLE_CHANNEL=beta bash. See Installation.

VariableWhat it doesDefault
OPENWAGGLE_CHANNELInstalls the newest release on stable, beta or alpha, and saves that channel for updatesThe installed app’s channel. On a first install, or when the script can’t read the installed app’s channel, stable, or beta while no stable release exists
OPENWAGGLE_RELEASE_TAGInstalls this exact version once, such as v1.0.0 or 1.0.0-beta.25, without changing your saved channelNot set
OPENWAGGLE_NO_LAUNCHSet to 1 to install without opening the app, like --no-launchNot set
OPENWAGGLE_APPLICATIONS_DIRmacOS only: the folder the app is copied to/Applications
OPENWAGGLE_INSTALL_REPOGitHub repository to install fromOpenWaggle/OpenWaggle
OPENWAGGLE_RELEASES_API_URLAddress the script lists releases fromhttps://api.github.com/repos/<repository>/releases
OPENWAGGLE_RELEASE_API_URLAddress of one release to install, used instead of a channel or tagNot set

The script also does not open the app when CI is set, over SSH (SSH_CONNECTION or SSH_TTY set), or on Linux when neither DISPLAY nor WAYLAND_DISPLAY is set. On Linux it saves the channel under XDG_CONFIG_HOME, ~/.config by default.

Set for agent shell commands

Commands that the agent runs with its bash or powershell tool get these, on top of the Session Host’s environment.

VariableValue
TMPDIR, TMP, TEMPThe session’s private scratch folder
OPENWAGGLE_EVIDENCE_DIRThe session’s evidence folder, for files to show you or another session
OPENWAGGLE_HOST_TMPDIRThe Session Host’s own temporary folder. An openwaggle command started from the agent’s shell uses it for its own temporary files
OPENWAGGLE_PROJECT_ROOTThe project folder
OPENWAGGLE_WORKTREE_PATHThe folder the session works in: its worktree, or the project folder
OPENWAGGLE_AGENT_RUN1. The openwaggle command then refuses to act as you, with exit code 4, unless it names an access profile

Pi also sets PI_SESSION_ID, PI_SESSION_FILE, PI_PROVIDER, PI_MODEL and PI_REASONING_LEVEL for these commands.

Set for project actions and terminals

WhereVariables
Project actions, worktree setup and scheduled task wake checksOPENWAGGLE_PROJECT_ROOT and OPENWAGGLE_WORKTREE_PATH, as above
Built-in terminalTERM=xterm-256color, COLORTERM=truecolor, TERM_PROGRAM=OpenWaggle and TERM_PROGRAM_VERSION set to the app version

A built-in terminal starts from a fresh copy of the app’s environment. OpenWaggle removes every OPENWAGGLE_* variable, the Electron and Node.js variables that can inject code (such as ELECTRON_RUN_AS_NODE, NODE_OPTIONS and NODE_PATH), and, on Linux, the AppImage runtime paths. See Built-in terminal.

Removed for GitHub and GitLab commands

When OpenWaggle runs gh or glab, it removes these so the command uses the account stored in that CLI’s own keyring, for the host of the project’s Git remote:

KindVariables
TokensGITHUB_TOKEN, GH_TOKEN, GITHUB_ENTERPRISE_TOKEN, GH_ENTERPRISE_TOKEN, GITLAB_TOKEN, GITLAB_ACCESS_TOKEN, GITLAB_PRIVATE_TOKEN, OAUTH_TOKEN, CI_JOB_TOKEN
Host and repositoryGH_REPO, GH_HOST, GITLAB_REPO, GITLAB_HOST, GITLAB_API_HOST, GITLAB_SSH_HOST, GITLAB_HEAD_REPO, GITLAB_URI, GITLAB_URL, GLAB_REPO, GLAB_HOST

GH_CONFIG_DIR, GLAB_CONFIG_DIR, XDG_CONFIG_HOME and, on Windows, APPDATA tell OpenWaggle where those CLIs keep their host lists.

Internal

OpenWaggle sets these between its own processes. Do not set them yourself.

VariableUse
OPENWAGGLE_CLI_OUTPUT_FDThe file descriptor the openwaggle command writes its output to. The Linux command sets it to 3
OPENWAGGLE_SHELL_ENVIRONMENT_REFRESHED_SINCETells a Session Host that the desktop app is reading the login shell, so it does not read it again
OPENWAGGLE_STARTUP_TIMINGSSet to 1 for a Session Host started by an app that measures its startup with --openwaggle-startup-timings
OPENWAGGLE_AUTOMATION_*Used by OpenWaggle’s own tests

Building from source

VariableWhat it doesDefault
OPENWAGGLE_RELEASE_CHANNELBuilds a released channel: stable, beta, rc or alpha. Only the release workflow sets itNot set, so the build is a Dev build
OPENWAGGLE_DEV_SLUGNames a Dev build, as in OpenWaggle Dev (<slug>), and its own app data folderThe Git branch, else local
ELECTRON_RENDERER_URLThe development server address bun run dev gives the appSet by bun run dev

See Building from source.