Add support for shell commands in environment variables

[dagon666]

I've prepared a change to add support for environment variables values resolved using a shell command.

Within and environment block, the variable can be defined using a literal or with a shell_command key which contains the command used to generate the value e.g.:

environment:  
  FOO:
    shell_command: "echo VALUE_FOR_FOO"
  BAR: "literal_values_work_the_old_way"

This is useful when injecting API keys from a password manager:

environment:  
  MYAPI_KEY:
    shell_command: "pass show MYAPI_KEY"

I've already prepared a branch with a change: https://github.com/dagon666/tmuxp/tree/feat/env-cmd

[tony]

Do you know any other tmux session managers or similar system util / dx applications that allow this kind of concatenation / execution (and do it securely?)

Will fan out to get a lay of the land.

[tony]

#942 has some similar shell execution stuff

[tony]

via Codex Sol 5.6 - Security analysis: command-derived environment values

Conclusion

Yes. Command-derived environment values exist in comparable tools, so the capability is not inherently abnormal or automatically a vulnerability. The safe implementations make execution explicit, establish trust before running project-controlled code, keep static data separate from executable configuration, and handle subprocess failure as a security boundary.

I would not merge the current feature commit as written. Its main problem is not that tmuxp gains another command surface; tmuxp workspace files already execute commands. Its problem is that command execution moves into general configuration expansion with weaker ordering, process control, failure behavior, and secret handling than tmuxp's existing command paths.

What the branch changes

The branch recognizes an environment value containing shell_command, expands it, invokes it through shell=True, captures standard output and standard error, and substitutes stripped standard output into the workspace environment. The relevant implementation is in loader.py and its integration into configuration expansion.

The reviewed branch tip is a single feature commit. I found no unrelated dependency, packaging, workflow, or hidden-payload change. This was source inspection only; I did not execute, import, or load the branch.

Security findings

1. Execution happens too early and in too broad an API. loader.expand() changes from normalization into code execution. In the CLI flow, expansion occurs before later tmux availability, builder, existing-session, and attach decisions in load.py. A command can therefore run even when loading later becomes a no-op or fails, and library callers that only wanted an expanded configuration inherit the side effect. Execution should occur only after validation and the existing-session/no-op decision, immediately before creating the workspace.

2. The subprocess lifecycle can deadlock or escape its timeout. The code creates both pipes, calls wait(), and only then calls communicate(). Python explicitly warns that Popen.wait() can deadlock with pipes when a child fills an OS pipe buffer. The timeout defaults to no limit; on timeout, the code returns without terminating and reaping the child or its descendants. Output is also unbounded in memory. A safe implementation needs a finite default timeout, concurrent draining, an output cap, process-group termination, and guaranteed reap.

3. Failure is fail-open. Timeout, nonzero exit, and other command failure become an empty environment value while workspace construction continues. That can silently turn a missing credential into a blank credential or redirect later behavior. A failed resolver should raise a named configuration error and abort before the session is built.

4. Environment expansion is reparsed as shell syntax. tmuxp expands ambient variables before passing the resulting string to /bin/sh -c. Shell metacharacters introduced by an environment value can therefore become syntax rather than inert data. This differs from ordinary shell variable expansion, where parsing has already identified operators. If the default interface accepts an argument vector and uses shell=False, it avoids this class of injection; an explicitly named shell mode can remain an escape hatch for users who knowingly need pipelines or redirection. Python's subprocess security guidance supports keeping quoting responsibility explicit.

5. Diagnostics can disclose secrets. Failure logging includes the expanded command and captured standard error. An expanded command may contain an ambient secret, and password managers or helper programs can emit sensitive context on standard error. Logs should identify only the environment key, resolver type, exit status, and a redacted diagnostic unless the user explicitly enables unsafe debugging.

6. Interactive secret tools can fail opaquely. Standard error is captured while standard input remains inherited. A password-manager or GPG prompt can be hidden while still waiting for input. The resolver contract should either prohibit interaction or deliberately connect it to a terminal with clear user-facing behavior.

7. The working directory is implicit. The command inherits the invoking process's current directory rather than a documented workspace-relative directory. This makes resolution dependent on how tmuxp was launched and can select attacker-controlled files in a different directory. The working directory should be deterministic and documented.

8. A tmux environment is not a secret store. Session environment values are inspectable through tmux commands and inherited by panes; processes running as the same user may also be able to inspect process environments. The tmux environment model and 1Password's environment-variable warning both matter here. This can be acceptable for process configuration, but it should not be described as protecting secrets from same-user processes or anyone who controls the tmux server.

How this compares with tmuxp's existing trust model

• Pane shell_command, shell_command_before, and related workspace commands already make a loaded workspace executable. They run as part of intentional workspace construction, where command execution is the declared purpose.
• before_script is a closer parent-process precedent, but it runs after session creation, avoids shell=True, and treats failure as fatal by cleaning up the partial session in builder.py.
• Plugins and custom workspace builders execute Python, but installation or import is a separate trust decision. tmuxp's custom-builder documentation explicitly says to use only trusted workspaces.
• Existing shell-string expansion means tmuxp is not free of shell-injection hazards. This proposal extends that inherited behavior into the tmuxp parent process and into credential resolution, where early execution and redaction matter more.
• A prompt or trust check limited to command-derived environment values would give false assurance because other workspace fields are already executable. If tmuxp adds a trust gate, it should cover the entire workspace file and be invalidated when the file changes.

Relative to current tmuxp behavior, this branch does not create the first route from a malicious workspace to code execution. It does create a more surprising route: a generic expansion helper runs code earlier than the established workspace-build phase and fails less safely than before_script.

Comparable tools and their security patterns

• dotenvx command substitution is the closest direct analogue: an environment value can be produced by a command. Its syntax visibly marks substitution as executable. This proves the capability is used in environment tooling, not that arbitrary project files should be auto-trusted.
• mise templates expose an exec(command) function. mise pairs executable project configuration with config trust, and its safe mode disables templates, hooks, and environment-file injection. That is the strongest directly relevant design precedent: executable configuration is treated as a whole-file trust decision.
• direnv intentionally executes a directory's .envrc, but blocks a new or changed file until the user runs direnv allow. Approval is tied to content, so a later modification requires another decision.
• systemd environment generators are executable programs whose standard output becomes environment assignments, but systemd separates them from static environment files and discovers them only from defined generator paths. The executable nature is architectural, not hidden inside a scalar value.
• 1Password op run resolves declarative secret references and injects them only into the launched process. This keeps secret retrieval outside the workspace parser and is a safer current answer for tmuxp load, although the resulting environment still has the normal same-user exposure.
• tmux session managers provide many comparable execution surfaces even when they do not implement this exact environment-value syntax. tmuxinator supports ERB in configuration as well as pane and hook commands; Smug combines literal environment values with commands and hooks; Teamocil defines commands in layouts; and Zellij models executable commands and arguments explicitly. These tools reinforce that session definitions are often executable, while also showing the value of keeping executable nodes visibly distinct from plain environment data.

The recurring security patterns are explicit executable syntax, whole-file trust, separation between static data and code, argument arrays where a shell is unnecessary, process-scoped injection, deterministic execution context, redacted errors, and fail-closed subprocess handling.

Would this produce a CVE?

The unmerged fork branch is not a tmuxp vulnerability because released tmuxp users are not exposed to it. Even after merge, an explicitly documented command resolver in a workspace that users knowingly load would usually be classified as an unsafe feature design or hardening issue, not automatically a CVE, because tmuxp workspace files already contain executable commands.

It becomes CVE-shaped when execution crosses a reasonable trust boundary: a preview, search, conversion, validation, CI, editor integration, or library call unexpectedly executes an untrusted workspace; an existing-session/no-op path executes before consent; attacker-controlled environment data is reparsed as shell syntax; or a supposedly safe/trusted mode fails to suppress execution.

Adjacent advisories show where maintainers and CNA reviewers draw that line. CVE-2026-50187 / GHSA-3rgh-p3mg-rjqg covers automatic execution of directory-controlled .env content by the Oh My Zsh dotenv plugin, where changing directories could cross the trust boundary. CVE-2026-44114 / GHSA-hxvm-xjvf-93f3 covers workspace-controlled dotenv values overriding security-sensitive runtime variables. Neither is identical, but both show that environment configuration earns an advisory when untrusted project content gains unexpected execution or control over privileged runtime behavior.

I did not find a directly analogous published advisory for tmuxp, tmuxinator, or direnv. That is weak negative evidence, not proof of safety: explicit execution and trust prompts usually prevent the behavior from being considered a boundary violation.

Recommendation

The safest design is to keep tmuxp environment values declarative and recommend external injection such as op run -- tmuxp load ..., direnv, mise, or a pre-populated environment. That reuses tools with established trust and secret-resolution models and keeps loader.expand() free of side effects.

If native support is still desirable:

• Keep parsing and expansion pure; resolve commands only after validation and existing-session decisions, immediately before workspace construction.
• Make an argument vector with shell=False the default. Put shell parsing behind a separately named, explicit field and do not pre-expand ambient values into shell source.
• Set a finite timeout and output limit; drain pipes safely; kill and reap the complete process group on timeout or cancellation.
• Fail closed with a dedicated exception. Do not replace failures with an empty value.
• Log the destination key and status, never the expanded command, output, or raw standard error by default.
• Define a deterministic workspace-relative working directory and a noninteractive policy.
• Document that workspace files are executable and that tmux/session/process environments are not secret stores.
• If adding trust approval, approve the entire workspace by content hash and require reapproval after any change.
• Add tests for nonzero exit, timeout, descendant cleanup, pipe saturation, output limits, hostile ambient-variable interpolation, redaction, working-directory behavior, interactive helpers, malformed configuration, existing-session/no-op ordering, and direct library use.

With those constraints, this can be a defensible executable-configuration feature. Without them, the branch broadens tmuxp's trusted-code surface in a way that is avoidably early, fail-open, and difficult to reason about.

[tony]

Will look at this over the weekend. Other tools are doing it and they aren't blowing up with CVEs.

• https://mise.jdx.dev/templates.html#functions has an exec()

my initial take: I like it best when shell that exec / eval's is very explicit. Like a mistake couldn't be made to run it. But also open to see what other tools are doing.

[tony]

AI-assisted (Claude) - Security analysis: peer gating, CVE shape, and the design collision

Conclusion

Agreed on both counts, with one correction and one addition.

Other tools do this and are not generating CVEs — because documented config-file execution is consistently classified as working-as-intended, not because the implementations are equivalent. And explicit-so-a-mistake-cannot-run-it is exactly what the peer set converged on, but they put the explicitness in a different place than a shell_command key does: every peer that resolves secrets uses an inert reference resolved by a trusted binary, and every peer that executes config gates the whole file rather than the one executable field.

The correction: shell_command is the wrong spelling for this. Everywhere else in the schema that key means "commands to run in the pane." Reusing it inside environment to mean "command whose stdout becomes a value" makes the executable node less visually distinct, not more — the opposite of the property you want.

The addition, and the part I would settle before any of the security detail: #942 and this branch both add shell evaluation to loader.py with different key names and different semantics, and #1014 drafts a -D KEY=VALUE / --var substitution that solves most of the dynamic-value need with zero execution. Three uncoordinated designs against one file. Whichever lands first sets the vocabulary by accident.

Where the peer comparison actually lands

The tools split cleanly by what they are resolving.

Secrets — nobody uses a config-authored command.

1Password op run resolves inert op:// references and injects them only into the subprocess for its lifetime, and conceals any secret the subprocess prints to stdout by default, requiring an explicit flag to see plaintext. Vault Agent resolves env_template blocks that name a secret path; its exec stanza runs after render as a side effect and cannot source a value. systemd credentials go further: "Unlike environment variables the credential data is not propagated down the process tree. Instead each time a credential is accessed an access check is enforced by the kernel." envchain states the principle as "Don't give any credentials implicitly!"

The pattern is inert reference plus trusted resolver, every time. Which is why op run -- tmuxp load myproject works today, with no tmuxp change, and gets stdout masking that a native resolver would have to build from scratch.

Executable config — gated per file, not per field.

mise is the closest precedent to what is being proposed here, and worth reading in full, because it has exec() in templates and two independent boundaries around it. Untrusted configs require mise trust. Separately, safe mode blocks exec() and read_file() in templates, hooks, tool-level postinstall, tasks, asdf plugin scripts, and plugin installs, and ignores environment and shell configuration from project config. Its own framing: "Safe mode is a code-execution boundary; it does not replace the trust system." Trust controls which configs load; safe mode controls what they can do. Paranoid mode adds content-bound trust for every non-global config.

direnv blocks a new or changed .envrc until direnv allow, keyed to content, so an edit revokes approval. Its VS Code extension stacks a second gate and says why: "Only allow .envrc files from sources you trust since direnv executes arbitrary shell script." VS Code Workspace Trust names tasks specifically — "task definitions are defined in the workspace .vscode folder, they are part of the committed source code for a repo, and shared to every user of that repo" — and gates running or even enumerating them.

systemd environment generators solve the same problem structurally instead: generators are executables discovered from fixed paths such as /etc/systemd/system-environment-generators/, whose stdout is parsed into assignments. The executable nature is architectural. Nothing is hidden inside a scalar.

Placement instead of permission — the cheapest answer, and the one closest to tmuxp's problem.

asdf is worth a paragraph precisely because it has no trust gate — searching its source for trust, allowlist, or permission concepts turns up nothing relevant — and is safe anyway. Its executable surface is user-scoped: hooks come from ~/.asdfrc, never from the project. The file a repo actually ships, .tool-versions, is inert — its parser contains no execution path at all.

When a hook does run, asdf is more permissive than this branch:

command = fmt.Sprintf("fn() { %s; }; fn %s", c.Expression, formatArgString(c.Args))
cmd := exec.Command("bash", "-c", command)

No gate, no timeout, no prompt (execute.go). It gets away with it because a cloned repo cannot reach that code. The one path from project data to execution is the parse-legacy-file plugin callback, and installing a plugin is already a separate, explicit trust decision — the same reasoning tmuxp's own custom-workspace-builder docs use.

This is the option I would weigh first, because it is not a gate at all. -D/--var keeps the executable surface on the command line, where the person typing it is the person authorizing it, and leaves the workspace file inert. Nothing to bypass, nothing to maintain, no re-prompt semantics to get right.

dotenvx is the one genuine counter-example — DATABASE_URL="postgres://$(whoami)@localhost/my_database" — and it is worth noting the page carries no security warning and no trust gate. It is precedent for the capability, not for a way of shipping it.

The one peer that shipped this ungated, and what happened.

Zellij's plugin system launched in June 2023 letting plugins "programmatically manage the user's workspace (panes, tabs, commands, editors)", while stating a permission system was future work. Tracking issue zellij-org/zellij#1395 stayed open until zellij-org/zellij#2624 merged the permission system on 2023-08-12 — about six weeks later. No CVE. The gate arrived retroactively, which is the ordinary outcome, and the argument for deciding the gate question before the syntax question rather than after.

What it settled on is the one peer precedent that treats session environment access as its own capability. The Permission enum has 17 variants, and ReadSessionEnvironmentVariables — shown to the user as "Read environment variables present upon session creation" — gates exactly one call, GetSessionEnvironmentVariables. Enforcement is a single match mapping every command onto one permission, so RunCommand, ExecCmd, and all the OpenCommandPane variants collapse to RunCommands.

Two caveats on borrowing it. The grant is keyed by plugin location, not content, so a plugin updated in place at a stable URL keeps its grant — weaker than direnv, which folds path and file content into a SHA-256 so any edit revokes approval. And a capability ACL is only enforceable because plugins call a host API through one chokepoint. tmuxp's shell_command reaches the pane through send_keys; there is no host boundary to enforce at. That asymmetry probably decides it: direnv's and mise's file-level model fits tmuxp's architecture, Zellij's capability model does not.

On CVEs specifically

Two shapes, and the boundary between them is sharp.

Documented execution over config content is not a CVE. GitHub withdrew the lodash template advisory (GHSA-8p5q-j9m2-g8wr) saying "GitHub has chosen to publish this CVE as a withdrawn advisory due to it not being a security issue", with the vendor position that "it's the developer's responsibility to ensure that a template does not evaluate code that originates from untrusted input."

A bypass of a gate is a CVE. Git added safe.directory as the fix for CVE-2022-24765; a hole in that gate then earned CVE-2022-29187 on its own. The two advisories already cited in this thread fit the same shape and both check out — GHSA-3rgh-p3mg-rjqg (CVE-2026-50187, High, oh-my-zsh dotenv plugin executing directory-controlled .env content) and GHSA-hxvm-xjvf-93f3 (CVE-2026-44114, High, workspace dotenv overriding runtime-control variables).

So the feature as such is not CVE-shaped. The thing that would make tmuxp CVE-eligible is adding a gate — because then there is something to bypass. That is still the right trade, but it is a maintenance commitment, not a free win.

Relative to what tmuxp already trusts

before_script is the house pattern for tmuxp running a command in its own process, and the contrast is systematic rather than cosmetic.

run_before_script splits with shlex.split into an argv list; the branch uses shell=True. It decodes with errors="backslashreplace"; the branch hardcodes UTF-8. It streams output to the terminal or the progress panel; the branch captures and discards. It drains pipes in a poll-and-readline loop; the branch calls wait() then communicate(). Missing target raises BeforeLoadScriptNotExists; non-zero exit raises BeforeLoadScriptError carrying command, returncode, and stderr.

The branch returns "" for all of it. Reading the branch's evaluate_env_value directly, three separate inputs produce a silent empty string: a non-zero exit, a YAML integer such as SERVER_PORT: 8010, and a typo'd key such as shell_commnd. The middle one is a behaviour regression — on master, expandshell(8010) raises TypeError; on the branch the same workspace file loads with the variable silently set to empty.

To be fair to the branch, the house pattern is not flawless either: run_before_script has no timeout at all, and its readline loop blocks on a silent child. The branch noticed the timeout problem. It just implemented it in a way that leaves the child unkilled. The house pattern's virtue is that it is loud.

Worth stating plainly, since it cuts against the security framing: this is not the first route from a malicious workspace file to code execution. shell_command and before_script already provide that, and tmuxp load . reads a repo-local .tmuxp.yaml with no trust prompt. What is new is that this is the first silent one — resolved at parse time, output captured into a variable, nothing drawn to the terminal, failures invisible.

Two Python details worth fixing regardless of the design outcome

Both are from CPython's own docs and are independent of the trust question.

Popen.wait(): "This will deadlock when using stdout=PIPE or stderr=PIPE and the child process generates enough output to a pipe such that it blocks waiting for the OS pipe buffer to accept more data. Use Popen.communicate() when using pipes to avoid that." The branch calls wait() first, so a command emitting more than a pipe buffer hangs tmuxp load indefinitely.

On timeout: "The child process is not killed if the timeout expires, so in order to cleanup properly a well-behaved application should kill the child process and finish communication." The branch catches the timeout and moves on, leaving the child running and unreaped. subprocess.run(timeout=...) kills and waits before re-raising, so most of this is a one-line change.

Also: the branch runs expandshell() on the command and then hands the result to shell=True, so metacharacters arriving from an ambient variable get parsed as syntax rather than treated as data. expand_cmd() already does this to pane commands, so it is the established loader convention rather than a new hazard — but it is a reason to prefer an argv vector by default here, where the output becomes a credential.

Lint, against this repo's ruff config: D103 (no docstring on a public function in a module where every other public function has a numpy-style one), BLE001 (blind except Exception), TRY400 (logger.error where logger.exception is meant). And the error log interpolates the full command and its stderr at ERROR level, which for password-manager tooling is the exact class of program that puts sensitive material on stderr.

That last one has a worked solution if native support does land. mise registers every resolved secret with a Redactor that compiles them into a single Aho-Corasick automaton — one linear pass over output regardless of how many secrets exist, rather than a str::replace per secret — and routes task output and logging through it, so a stray echo $SECRET prints a redaction marker. Its placement rule is the more important half: secrets exist as plaintext only in the environment of the process mise launches, never in a config file and never in a log line.

Suggested order

1. Land the flaky-test fix (f3f1659) as its own PR. It is independently correct and unrelated to the feature. It also removes a latent IndexError: capture_pane()[1] assumes a second line exists, so under a slow shell the current test can fail with an index error rather than an assertion diff.
2. Decide -D/--var versus config-time execution, across Implements if conditions for pane and window #942, docs: tmuxinator/teamocil parity analysis and feature comparison #1014, and this branch together.
3. If native execution is wanted, name the key so it cannot be misread as a pane command, default to an argv vector with shell=False, fail closed with a named exception, log only the destination key and status, and resolve after the existing-session decision rather than during expansion.
4. If a trust gate is wanted, scope it to the whole workspace file by content hash, the way mise and direnv do — a gate on this one field would give false assurance while shell_command and before_script stay open.

What this is

Static source inspection of the fork branch against master at 6286b4a, plus the linked upstream sources. Nothing from the branch was executed, applied, or cherry-picked; it was fetched read-only. The three fail-open cases above were confirmed by calling the branch's evaluate_env_value in isolation. The branch forks at v1.70.1 and is currently around 170 commits behind master, so a rebase would be needed regardless.

Peer coverage is uneven and stated as such: mise, direnv, VS Code, Zellij, dotenvx, systemd, Vault, 1Password, envchain, asdf, and sops were checked against primary sources or source code at a pinned tag. tmuxinator, teamocil, smug, and tmuxifier were not verified to the same standard here, so the earlier ERB comparison in this thread should be taken as README-level rather than confirmed.

Edited once after posting to add the asdf placement precedent, Zellij's ReadSessionEnvironmentVariables capability, and mise's redaction design — all three found after the original comment and none of them contradicting it.