Bootstrap — secret-gate and token export¶

Live hub: https://conductor-konstant.hectorsanchez.eu/connect.md
Offline: docs/guides/connect/bootstrap.md in a cloned conductor repo.

Follow this algorithm once per shell before configuring any MCP client.

Agents on the live host: do not follow relative links like ../connecting.md (they 401). Always use absolute /connect/... URLs.

Decision matrix (quick)¶

Check	Action
OS Windows?	Use `pwsh` (7.2+). Stop if only Windows PowerShell 5.1 is available.
Shell bash/zsh/fish?	Use the bash path below.
`uv` or `pip` missing?	Install uv first, then secret-gate.
`secret-gate` missing?	Install (below).
`secret-gate status` unauthenticated?	Run `secret-gate auth` in a visible terminal.
Token already set (length > 0)?	Skip refresh; proceed to client config.

Windows: PowerShell 7 required¶

Windows default powershell.exe is 5.1 and breaks secret-gate.

# Must be pwsh 7.2+
$PSVersionTable.PSVersion
if ($PSVersionTable.PSVersion.Major -lt 7) {
  throw "Install PowerShell 7+ and re-run in pwsh.exe (not Windows PowerShell 5.1)"
}

Launch with pwsh, not powershell.

Install secret-gate¶

Prefer uv (works even without system pip):

if command -v uv >/dev/null 2>&1; then
  uv tool install --force \
    'git+https://github.com/Konstant-Ventures/secret-gate.git@main'
elif python3 -m pip --version >/dev/null 2>&1; then
  python3 -m pip install --user --upgrade \
    'git+https://github.com/Konstant-Ventures/secret-gate.git@main'
else
  echo "Install uv or Python pip, then retry." >&2
  exit 1
fi
secret-gate status

PowerShell (pwsh):

if (Get-Command uv -ErrorAction SilentlyContinue) {
  uv tool install --force 'git+https://github.com/Konstant-Ventures/secret-gate.git@main'
} else {
  python -m pip install --user --upgrade 'git+https://github.com/Konstant-Ventures/secret-gate.git@main'
}
secret-gate status

Do not leave a durable source checkout of secret-gate behind for routine use. Legacy secret-gate.ps1 / secret-gate.sh paths are obsolete.

Authenticate¶

secret-gate auth

Agent terminals that hide prompts: on Linux desktops, secret-gate may open a zenity dialog when DISPLAY/WAYLAND_DISPLAY is set. If no visible dialog is available, stop and ask the human to run secret-gate auth in a visible terminal. Never request the master password in chat or pass it on the CLI.

Export token (happy path — secret-gate only)¶

Bash:

# Child process cannot mutate parent env — eval the export lines.
eval "$(secret-gate refresh --set ci --print-env)"

if [ -n "${CONDUCTOR_MCP_AUTH_TOKEN:-}" ]; then
  printf 'CONDUCTOR_MCP_AUTH_TOKEN present (%s chars)\n' \
    "${#CONDUCTOR_MCP_AUTH_TOKEN}"
else
  echo "CONDUCTOR_MCP_AUTH_TOKEN missing" >&2
  exit 1
fi

PowerShell (pwsh only):

Invoke-Expression (& secret-gate refresh --set ci --print-env --shell pwsh)
if ($env:CONDUCTOR_MCP_AUTH_TOKEN) {
  Write-Host "CONDUCTOR_MCP_AUTH_TOKEN present ($($env:CONDUCTOR_MCP_AUTH_TOKEN.Length) chars)"
} else {
  throw "CONDUCTOR_MCP_AUTH_TOKEN missing"
}

The ci set includes CONDUCTOR_MCP_AUTH_TOKEN. Never echo, preview, or paste the value into an agent transcript. --print-env may put the token on stdout — prefer length checks afterward; avoid re-running print-env in logged agent tools when the variable is already set.

Token lifecycle¶

Topic	Rule
Who creates the secret	Lab operator in Bitwarden Secrets Manager (`CONDUCTOR_MCP_AUTH_TOKEN`)
Agents	Retrieve via secret-gate; do not invent or scrape host `.env`
Missing secret	Stop. Ask the human to create/update the Bitwarden secret, then retry
Rotation / expiry	Re-run `secret-gate auth` / `refresh` after rotation; restart MCP clients
Session persistence	Env export lasts for the current shell only unless your OS session manager persists it

Break-glass (not the happy path)¶

Use only if secret-gate cannot run. Still Bitwarden-authoritative — never treat host .env as source of truth.

export PATH="$HOME/.local/bin:$PATH"
source ~/.local/state/secret-gate/session.env 2>/dev/null || true
KEY=$(bws secret list -o json | python3 -c '
import json,sys
wanted="CONDUCTOR_MCP_AUTH_TOKEN"
for s in json.load(sys.stdin):
    if s.get("key")==wanted:
        print(s.get("value",""))
        break
')
if [ -z "$KEY" ]; then
  echo "CONDUCTOR_MCP_AUTH_TOKEN not found in Bitwarden" >&2
  exit 1
fi
export CONDUCTOR_MCP_AUTH_TOKEN="$KEY"
printf 'CONDUCTOR_MCP_AUTH_TOKEN present (%s chars)\n' "${#KEY}"
unset KEY

Next¶

Open your client-specific guide (absolute URLs):

Client	URL
Codex	https://conductor-konstant.hectorsanchez.eu/connect/codex.md
OpenCode	https://conductor-konstant.hectorsanchez.eu/connect/opencode.md
Cursor	https://conductor-konstant.hectorsanchez.eu/connect/cursor.md
Claude Code	https://conductor-konstant.hectorsanchez.eu/connect/claude-code.md
Others	https://conductor-konstant.hectorsanchez.eu/connect/others.md

Troubleshooting: https://conductor-konstant.hectorsanchez.eu/connect/troubleshooting.md