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.