Skip to content

Document shell environment configuration for macOS GUI app #701

Closed

Description

@mdrxy

Problem

When launching Superset as a macOS desktop app, user shell aliases and environment variables are not available in workspace terminal sessions. This is because:

  1. Superset uses tmux new-session -d -s "${sessionName}" "${command}" to launch agents
  2. This executes the command directly without spawning an interactive login shell
  3. macOS GUI apps don't inherit shell environment variables (they're launched by launchd, not the user's shell)

Users with custom shell configurations (aliases in .zshrc, .bashrc, custom ZDOTDIR, etc.) will find their setup missing in Superset workspaces.

Solution

Superset supports the SUPERSET_AGENT_LAUNCH_<TYPE> environment variables to customize agent launch commands. To wrap the agent in a login shell:

export SUPERSET_AGENT_LAUNCH_CLAUDE="zsh -lic 'claude'"

However, since macOS GUI apps don't read shell profile files, users must set this via launchctl:

launchctl setenv SUPERSET_AGENT_LAUNCH_CLAUDE "zsh -lic 'claude'"

Then restart Superset.

To persist across reboots, add the launchctl setenv command to ~/.zprofile or ~/.bash_profile.

I'd suggest adding a section to the README or docs covering this.

Activity

  1. Kitenite commented on Jan 10, 2026

    @Kitenite
    Member

    Superset uses tmux new-session -d -s "${sessionName}" "${command}" to launch agents
    This executes the command directly without spawning an interactive login shell

    I'm not sure this is true, we don't spawn sessions with tmux, we actually spawn with login shell for zsh or bash so your terminals.

    https://github.com/superset-sh/superset/blob/64987a8c4d492c1ca043618284eed175aebe5722/apps/desktop/src/main/lib/agent-setup/shell-wrappers.ts#L83

    @mdrxy are you having specific problems with missing path bindings in the terminal?

  2. mdrxy commented on Jan 11, 2026

    @mdrxy
    Author

    Sorry, I was mistaken about tmux. The issue appears to involve custom ZDOTDIR detection.

    My shell config uses ZDOTDIR=~/.config/zsh (set in ~/.zshenv). When the desktop app launches, getShellEnv() does:

    SUPERSET_ORIG_ZDOTDIR: process.env.ZDOTDIR || os.homedir(),
    

    Since macOS GUI apps don't inherit shell environment variables process.env.ZDOTDIR is undefined and it falls back to $HOME.

  3. Kitenite commented on Jan 12, 2026

    @Kitenite
    Member

    @mdrxy that makes sense, I can take a look today

  4. added a commit that references this issue on Jan 12, 2026
    e9b8d78
  5. Kitenite commented on Jan 13, 2026

    @Kitenite
    Member

    @mdrxy #720 should solve the issue but will need to test with a custom shell config

  6. added a commit that references this issue on Jan 13, 2026
    4a41f05
  7. Kitenite commented on Jan 13, 2026

    @Kitenite
    Member

    @mdrxy let me know if the issue still persists in the latest release

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions