bug: install.sh ignores XDG_CONFIG_HOME for the local gateway config

[mpereira]

User Story

As someone whose shell exports XDG_CONFIG_HOME,
I want install.sh to use the same config directory as the openshell CLI,
so that installing and reinstalling OpenShell just work.

Problem Statement

The CLI keeps each gateway's entry and client certificates under $XDG_CONFIG_HOME/openshell when that variable is set. The installer always uses ~/.config/openshell instead, in two places:

• The readiness check, which connects to the gateway with the client certificates it expects to find there.
• The cleanup that removes an old openshell entry before adding it again.

With the variable set, the installer and the CLI look in different directories.

Impact / Why This Matters

With XDG_CONFIG_HOME pointing somewhere other than ~/.config:

• On macOS, the install fails whenever ~/.config/openshell has no client certificates for the gateway, or has old ones. The installer waits 30s and exits 1.
• On macOS and Linux, running the installer a second time exits 1 with "Gateway 'openshell' already exists". When the gateway is already registered, the installer removes the entry and adds it again. But it removes it from ~/.config/openshell, and the CLI's entry is under $XDG_CONFIG_HOME/openshell. That entry is still there, so adding it again fails.

The gateway itself keeps running in both cases. On Linux the first run works only because the gateway service also writes a copy of its client certificates to ~/.config/openshell when it starts, so the readiness check happens to find current ones there.

The workarounds don't really work. Unsetting XDG_CONFIG_HOME just for the install puts the gateway entry under ~/.config, so the CLI in your normal shell can't find it afterwards. Running openshell gateway remove openshell before a reinstall avoids the "already exists" error, but not the certificate check on macOS. And nothing in the installer's output mentions the variable.

Acceptance Criteria

With XDG_CONFIG_HOME set and XDG_STATE_HOME unset:

• The installer exits 0 when ~/.config/openshell has no client certificates for the gateway, and when it has old ones.
• After the install, openshell status in the same shell shows the gateway.
• Running the installer a second time exits 0.

In general:

• With XDG_CONFIG_HOME unset or empty, the installer keeps using ~/.config/openshell.
• mise run test:install-sh covers unset, empty, set, and set-with-spaces values.

With both XDG_CONFIG_HOME and XDG_STATE_HOME set, the Linux install fails for a different reason, that maybe is not as important, and not described in this issue.

Reproduction Steps

1. export XDG_CONFIG_HOME="$(mktemp -d)", and make sure ~/.config/openshell/gateways/openshell doesn't exist.
2. Run curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh.
3. On macOS it waits 30s, prints mTLS client bundle is not ready under ~/.config/..., and exits 1. On Linux it succeeds.
4. Run it again. Both platforms stop with Gateway 'openshell' already exists.

Environment

• OpenShell 0.1.2, installer from main at 9cb72baa2. The installer code involved is the same on current main.
• macOS 26.2 arm64, Homebrew 7.0.7, run as the logged-in user
• Ubuntu 26.04 x86_64, deb package, run as root, Docker 29.1.3

Logs

# macOS, no certificates under ~/.config
mTLS client bundle is not ready under ~/.config/openshell/gateways/openshell/mtls
openshell: error: local gateway listener did not become reachable at https://localhost:17670/ within 30s

# macOS, old certificates under ~/.config
curl: (60) SSL certificate problem: unable to get local issuer certificate

# macOS and Linux, second run
openshell: local gateway already exists; removing and re-adding it...
Error:   × Gateway 'openshell' already exists.

[efegokdemir]

I'd like to work on this. I'll reproduce the installer path mismatch against current main and add coverage for unset, empty, set, and set-with-spaces XDG_CONFIG_HOME values.

[elezar]

📋 triage-agent

Triage Assessment

Classification: validated-bug

Summary

Confirmed an installer/CLI configuration-directory mismatch for nonempty XDG_CONFIG_HOME. The report supplies sufficient reproduction, environment, impact, and observable acceptance criteria. Both hardcoded paths remain on current main at 1ad4e428a67c2a0869fd2043159acacea5d4683e.

Investigation

• install.sh:1023 probes client certificates under ${TARGET_HOME}/.config/openshell; install.sh:1092 cleans registration from that same default root. CLI gateway metadata and imported client certificates instead use the XDG configuration root through openshell-bootstrap and openshell-core. Same-user installer invocations preserve the exported XDG setting.
• An isolated shell harness sourced the current-main installer using OPENSHELL_INSTALL_SH_TEST=1, a temporary target home, and a custom XDG path containing spaces, with XDG_STATE_HOME unset. Certificates present only in the custom root did not satisfy readiness: it emitted the reported missing-bundle diagnostic and timed out (timeout reduced to one second; sleep/diagnostics stubbed). Registration cleanup left custom-root metadata.json and active_gateway intact. With stale default-root fixtures, a mocked curl invocation received the default CA path despite the custom-root bundle being present. These checks validate path selection and cleanup directly; they are not a full Homebrew/Debian installation or a live TLS handshake.
• The macOS ordering registers/imports the CLI bundle before readiness. Linux startup also publishes client materials, which explains why a service using its default environment can mask the first-install mismatch. Exact service environment determines that masking; it is not guaranteed for every Linux deployment. Gateway startup preceding registration/readiness is consistent with the reported gateway remaining running after installer failure.
• Latest stable release is v0.1.2, matching the report. PR #4043 proposes a fix but is closed and unmerged, so it does not establish a released fix. No canonical duplicate found; #1593 concerns a different systemd TLS state-directory mismatch.
• Acceptance-criteria caveat: xdg_config_dir() currently accepts an explicitly empty XDG_CONFIG_HOME as an empty path, yielding a relative openshell root. The requested empty-value fallback therefore needs consistent handling between installer and invoked CLI; changing only the two hardcoded paths does not establish consistency for that case. This caveat does not invalidate the nonempty-value defect. The separate XDG_STATE_HOME failure remains outside this issue.

Impact Signals

• Affected users/scope: Users installing or reinstalling through the native Homebrew/Debian paths with a custom exported XDG configuration directory; macOS first-install readiness and macOS/Linux re-registration are affected. Snap has a separate registration path and was not validated here.
• Regression: Unknown; the defect remains present on current main. No introduction point established.
• Workaround: Removing registration can avoid duplicate-registration failure, but does not correct macOS certificate probing. Unsetting XDG only for installation leaves normal-shell CLI discovery inconsistent.
• Evidence quality: High for the path mismatch and cleanup defect, based on current code and isolated execution; platform-wide package/service behavior relies on the reporter's reproduction plus supporting code, without fresh end-to-end installs.

Human Decision Required

Decide whether OpenShell should address this issue. If yes, apply state:accepted, associate it with a roadmap item, or both. Roadmap placement additionally records sequencing. Decide whether work remains human-owned; agent:plan-requested can queue unattended investigation/planning, or a direct request can invoke create-spike or build-from-issue. If declining, close as not planned with a rationale. Technical validation alone does not record product acceptance.