Skip to content

regression(mcp): support file-based secrets in env config (restore shell-expansion behavior) #2334

Description

@malikwirin

Description

Background

This is a feature request to restore functionality that regressed in a recent Crush version.

Previously, Crush spawned MCP servers through a shell, which allowed env values using shell command substitution to be evaluated at runtime:

"env": {
  "FORGEJO_ACCESS_TOKEN": "$(cat /run/secrets/codeberg_token)"
}

This made it straightforward to integrate with secret managers that expose secrets as files on disk (e.g. sops-nix, pass, systemd credentials, Docker secrets). Since Crush no longer evaluates shell expressions in env values, this pattern is silently broken — the literal string $(cat ...) is passed as the token value instead. The ability to reference file-based secrets in MCP server configuration is now lost.

The regression has a subtle failure mode: MCP servers that validate tokens eagerly on startup (e.g. forgejo-mcp) crash immediately with a broken pipe during the initialize handshake, while servers with lazy validation (e.g. github-mcp-server) appear to initialize successfully but silently fail when tools are actually invoked.

Proposed Feature

Introduce a env_files key (or similar) in the MCP server config to explicitly map environment variable names to file paths, which Crush reads at process startup:

"codeberg": {
  "command": "/path/to/forgejo-mcp",
  "args": ["transport", "stdio", "--url", "https://codeberg.org"],
  "env_files": {
    "FORGEJO_ACCESS_TOKEN": "/run/secrets/codeberg_token"
  }
}

Crush would read the file contents and set the environment variable before spawning the process — no shell required, no security regression.

Why not use $(echo $VAR)?

The currently documented workaround ($(echo $HOST_ENV_VAR)) does not help here: secrets managed by sops-nix, systemd, or similar tools are decrypted at runtime and are only available as files on disk — they are never present as host environment variables in the Crush process.

Alternatives Considered

  • Wrapper shell scripts per MCP server — functional but requires boilerplate outside the config and complicates NixOS/Home Manager module integration
  • Storing secrets as host env vars — not possible with file-based secret managers

Activity

  1. tunnckoCore commented on Mar 6, 2026

    @tunnckoCore

    Or just support .env or .env.local or .env.charm?

    This does actually seem to work (set -a; source .env.crush; crush -y) - yes including the parens, and ye bash/zsh.

    Image
  2. malikwirin commented on Mar 6, 2026

    @malikwirin
    Author

    Or just support .env or .env.local or .env.charm?

    This does actually seem to work (set -a; source .env.crush; crush -y) - yes including the parens, and ye bash/zsh.

    Image

    I dont unterstand. Where would I (set -a; source .env.crush; crush -y)?

  3. changed the title [-]feat(mcp): support file-based secrets in env config (restore shell-expansion behavior)[/-] [+]WIP: feat(mcp): support file-based secrets in env config (restore shell-expansion behavior)[/+] on Mar 24, 2026
  4. changed the title [-]WIP: feat(mcp): support file-based secrets in env config (restore shell-expansion behavior)[/-] [+]fix: (mcp): support file-based secrets in env config (restore shell-expansion behavior)[/+] on Mar 24, 2026
  5. changed the title [-]fix: (mcp): support file-based secrets in env config (restore shell-expansion behavior)[/-] [+]fix(mcp): support file-based secrets in env config (restore shell-expansion behavior)[/+] on Mar 24, 2026
  6. changed the title [-]fix(mcp): support file-based secrets in env config (restore shell-expansion behavior)[/-] [+]regression(mcp): support file-based secrets in env config (restore shell-expansion behavior)[/+] on Mar 24, 2026
  7. malikwirin commented on Apr 9, 2026

    @malikwirin
    Author

    I am finally able to actually use crush again after building a workaround.
    The following workaround wraps every command with its args and env files as a shell script using Nix Home-Manager.
    It expects charmbracelet/nur#60 to be merged and yants to be set per overlay to pkgs.lib.yants.

    {
      config,
      lib,
      pkgs,
      ...
    }:
    
    let
      inherit (pkgs.lib.yants)
        defun
        option
        struct
        string
        list
        attrs
        ;
    in
    {
      programs = {
        mcp = {
          enable = true;
          servers =
            let
              McpServer = struct "McpServer" {
                command = string;
                args = list string;
                env = option (attrs string);
                envFiles = option (attrs string);
              };
    
              McpServerCfg = struct "McpServerCfg" {
                command = string;
                args = list string;
                env = option (attrs string);
              };
    
              wrapMcpServer = defun [ McpServer McpServerCfg ] (
                srv:
                let
                  inherit (srv) envFiles;
                  outputSrv = builtins.removeAttrs srv [ "envFiles" ];
                in
                if envFiles == null || envFiles == { } then
                  outputSrv
                else
                  let
                    exports = lib.concatStringsSep "\n" (
                      lib.mapAttrsToList (var: file: ''export ${var}="$(cat ${file})"'') envFiles
                    );
                    wrapper = pkgs.writeShellScript "mcp-wrapper" ''
                      ${exports}
                      exec ${srv.command} ${lib.escapeShellArgs srv.args} "$@"
                    '';
                  in
                  outputSrv
                  // {
                    command = toString wrapper;
                    args = [ ];
                  }
              );
    
              gitea =
                { url, tokenPath }:
                wrapMcpServer {
                  command = lib.getExe pkgs.forgejo-mcp;
                  args = [
                    "transport"
                    "stdio"
                    "--url"
                    url
                  ];
                  envFiles.FORGEJO_ACCESS_TOKEN = tokenPath;
                };
            in
            {
              # TODO: add youtube trancribtion mcp & nixos discourse mcp
              backlog = {
                command = pkgs.lib.getExe pkgs.backlog-md;
                args = [
                  "mcp"
                  "start"
                ];
              };
    
              codeberg = gitea {
                url = "https://codeberg.org";
                tokenPath = config.sops.secrets.codeberg_token.path;
              };
    
              fetch.command = pkgs.lib.getExe pkgs.mcp-server-fetch;
              markitdown.command = pkgs.lib.getExe pkgs.markitdown-mcp;
              nixos.command = "${pkgs.mcp-nixos}/bin/mcp-nixos";
    
              perplexity = wrapMcpServer {
                command = "${lib.getExe pkgs.perplexity-mcp}";
                args = [ ];
                envFiles.PERPLEXITY_API_KEY = config.sops.secrets.perplexity-api-key.path;
              };
    
              github = wrapMcpServer {
                command = pkgs.lib.getExe pkgs.github-mcp-server;
                args = [ "stdio" ];
                envFiles.GITHUB_PERSONAL_ACCESS_TOKEN = config.sops.secrets.github_token.path;
              };
            };
        };
      };
    }

    This is a workaround and I still believe crush should be compatible with secret managers that only provide paths at configure time

  8. malikwirin commented on Apr 9, 2026

    @malikwirin
    Author

    A clean solution for this would be to adopt the same variable substitution approach that opencode implements. Opencode supports a {file:/path/to/secret} syntax directly in config values, which allows file-based secrets to be injected into MCP server environment variables without shell expansion:

    "codeberg": {
      "command": "/path/to/forgejo-mcp",
      "args": ["transport", "stdio", "--url", "https://codeberg.org"],
      "env": {
        "FORGEJO_ACCESS_TOKEN": "{file:/run/secrets/codeberg_token}"
      }
    }

    This would cover secret managers like sops-nix, systemd credentials, and Docker secrets, where secrets are only available as files at runtime and never as host environment variables. The opencode implementation could serve as a reference.

  9. dcunited001 commented on May 1, 2026

    @dcunited001

    @malikwirin you can still use sops with environment variables, though it's not the intended usage for long running processes.

    https://github.com/getsops/sops#passing-secrets-to-other-processes

    running shell commands that are stored in config files isn't hygienic. IMO, it would be better if there were a way to just use procsub. that's how i got here.

  10. dcunited001 commented on May 1, 2026

    @dcunited001

    avoiding nodejs is how i got to charm lol

    another option is to integrate with the OS secrets store.

    the standard .env support would be great as well. just please do not store current login info in ~/.config like opencode or in ~/.local/share like other software (podman).

  11. malikwirin commented on May 1, 2026

    @malikwirin
    Author

    avoiding nodejs is how i got to charm lol

    another option is to integrate with the OS secrets store.

    the standard .env support would be great as well. just please do not store current login info in ~/.config like opencode or in ~/.local/share like other software (podman).

    opencode does support secrets files and ~/.local/share and ~/.config are actually standards defined in the free desktop specifications

  12. dcunited001 commented on May 1, 2026

    @dcunited001

    it's true that they're defined in the XDG desktop standard, but they're only as secure as your user, file system or disk device.

    for Windows and MacOS, the desktop-environment integration that most software uses causes them to store secrets in the OS keyring, where they're usually only available to specific applications.

    googling for site:https://opencode.ai/docs encrypt shows no results. plain-text API tokens are a no-go for me. anomalyco/opencode#4318 mentions a need to address this or support OS keyring.

    these tools manage orchestration of agents which need access to APIs or at least your computer's own resources. The tasks are often delegated under the OS identity of the user themselves. the option for encrypted credentials should not be an afterthought. it should be considered a primary requirement, esp for these agent harnesses.

    ideally, the CLI would support .env files, but also a CLI method using some -x LLM_SERVICE_TOKEN=<(cmd proc sub) which doesn't set the env var, but instead opens the file descriptor, then releases it.

    nodeJS is used widely bc it deploys to many platforms easily, but package authors often don't know the first thing about system integation. this results in poor CLI choices, where tools typically don't examine file paths or file descriptors to determine whether <(cmd proc sub) was used.

    on the other hand, Go emerged as a systems programming lang, so its culture & extension authors tend to handle CLI args properly.

    I don't bother with NodeJS CLI tools (i also use NixOS btw... i haven't quite crossed off sops.nix though)

  13. meowgorithm commented on May 2, 2026

    @meowgorithm
    Member

    Hey! Two issues here and both are good ones:

    1. There was a regression with shell expansion
    2. We should store secrets in a more secure fashion

    We hear you on both. Looking into the regression first.

  14. meowgorithm commented on May 2, 2026

    @meowgorithm
    Member

    Alright, so we have a PR for this one: #2782. We're using the embedded Bash interpreter now, which is way, better, so you can do things like "$(cat /run/secrets/codeberg_token)" and "$(vault kv get my/little/secret)".

  15. meowgorithm commented on May 10, 2026

    @meowgorithm
    Member

    Thanks for your patience, everyone. This one's merged and will be available in the next release, likely Monday.

    Also, it's using a the embedded bash interpreter for shell expansion now, so it should generally be way better than before.

  16. dcunited001 commented on May 12, 2026

    @dcunited001

    Thanks for your patience, everyone. This one's merged and will be available in the next release, likely Monday

    Thanks for looking into this. I'm just a bit paranoid about things.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions