Skip to main content

Save an environment variable

Use this guide when an AI app reads your dtxWiki access key from an environment variable (ENV). First create an access key, then choose the steps for the computer and environment where the app runs. These settings belong on the AI app’s computer, even if dtxWiki runs on a different server.

Why does the connection disappear after a restart?​

An environment variable is a named value supplied to a running program. Here the name is DTXWIKI_MCP_PAT and the value is your secret dtxWiki access key. It is separate from an OpenAI or Anthropic API key.

In a terminal, export DTXWIKI_MCP_PAT=... sets a value for that shell and programs it starts. It does not save the value for the next login. The MCP registration can remain on disk while the key value disappears when you close that session or restart the computer.

What you saveWhat survives a restart
Only a terminal’s export or PowerShell’s $env:DTXWIKI_MCP_PATThe value is temporary. Prepare it again in a new session.
Codex’s bearer_token_env_var = "DTXWIKI_MCP_PAT"The variable name survives. Supply its value again when Codex starts.
A Windows user environment variableWindows keeps the value for future sessions.
A macOS/Linux key file plus a shell startup settingEach new shell loads the saved value. Launch the app from that shell.

If your organization provides a secrets manager, follow its instructions to supply the variable at launch. The local storage methods below keep a plaintext secret in your Windows user settings or a private file. Use them on your own protected account, and keep the value out of Git, settings sync, shared backups, and screenshots.

Windows: save a user environment variable​

Use these steps for an app running directly in Windows. If your VS Code window uses WSL, follow the WSL section instead.

  1. Open the Start menu and search for Edit environment variables for your account. If you open Edit the system environment variables, select Environment Variables… in that window.
  2. In the upper User variables for your account area, select New…. Use user variables; administrator access is not needed.
  3. Enter DTXWIKI_MCP_PAT as Variable name. Paste the access key copied from dtxWiki as Variable value, without quotes, Bearer, or export.
  4. If this name already exists, select Edit… and update its value. Confirm each dialog with OK.
  5. Close all VS Code windows and terminal apps, then reopen PowerShell from the Start menu. Existing apps can retain an older environment. If the check below still says Missing, sign out of Windows and sign in again, or restart the computer.
  6. Run this check in the new PowerShell window. It prints only whether a nonempty value is available:
if ($env:DTXWIKI_MCP_PAT) { 'Configured' } else { 'Missing' }

Configured means this PowerShell process has a value. It does not check whether the key is correct or still valid. After a computer restart, open a new PowerShell window and repeat the check. Then launch the CLI from that window or VS Code with the saved user environment.

Typing $env:DTXWIKI_MCP_PAT = '...' in a terminal alone changes only that process. The user-variable dialog saves it across restarts. See Microsoft’s persistent environment variable documentation.

macOS and Linux: save a key file and load it at startup​

These steps use Bash or Zsh, the shells that interpret terminal commands. Open Terminal on macOS or your terminal app on Linux. Run each command block separately. Do not type a leading $ prompt.

1. Create a private file​

Run these commands to create a folder and file under your home directory. ~ and $HOME refer to that directory. This file is outside your project:

mkdir -p "$HOME/.config/dtxwiki"
chmod 700 "$HOME/.config/dtxwiki"
(umask 077; touch "$HOME/.config/dtxwiki/mcp-env")
chmod 600 "$HOME/.config/dtxwiki/mcp-env"
nano "$HOME/.config/dtxwiki/mcp-env"

nano opens a text editor inside the terminal. Add this line, replacing PASTE_YOUR_DTXWIKI_ACCESS_KEY_HERE with your actual key. Keep the single quotes and do not add spaces around =:

export DTXWIKI_MCP_PAT='PASTE_YOUR_DTXWIKI_ACCESS_KEY_HERE'

Save with Ctrl+O, press Enter to confirm the filename, and exit with Ctrl+X. On macOS these are Control shortcuts. If nano is unavailable, open this file in VS Code using File → Open File… and save the same line there. Edit the file locally; do not paste the key into an AI chat.

The permissions 700 and 600 restrict the folder and file to your account. They do not encrypt the key or prevent programs running as you from reading it. If the file already contains this variable, replace that line rather than adding another value.

2. Tell new terminals to load the file​

Check which shell this terminal is running:

ps -p $$ -o comm=

Choose the matching startup file. A leading - in a shell name is normal.

ShellStartup file to edit
Zsh (zsh or -zsh), commonly the macOS default~/.zshrc
Bash (bash or -bash), commonly used on Linux and WSL~/.bashrc

Open the chosen file with nano ~/.zshrc or nano ~/.bashrc. Keep its existing contents and add this block at the end once, then save and exit as above:

if [ -f "$HOME/.config/dtxwiki/mcp-env" ]; then
  . "$HOME/.config/dtxwiki/mcp-env"
fi

The dot followed by a space means “load the settings from this file into this shell.” This block contains no key value. Only load the file you created yourself.

Bash login terminals, including Bash on macOS, read the first existing file among ~/.bash_profile, ~/.bash_login, and ~/.profile. Add the same block to that file if it does not already load ~/.bashrc. If none exists, create ~/.bash_profile with the block. For a custom Zsh setup using ZDOTDIR, edit .zshrc in that directory instead. See the Bash startup rules and Zsh startup rules.

3. Apply and check without displaying the key​

Load the file into your current terminal:

. "$HOME/.config/dtxwiki/mcp-env"

Then check:

if [ -n "${DTXWIKI_MCP_PAT:-}" ]; then
  printf 'Configured\n'
else
  printf 'Missing\n'
fi

Open a new terminal window and run the check again without manually loading the file. It should print Configured. Repeat after your next computer restart. If it says Missing, check that you edited the startup file used by that shell. Avoid echo "$DTXWIKI_MCP_PAT", printenv, or a full environment dump when sharing diagnostics: they can reveal the key.

When the check succeeds, run codex or claude from this terminal if you use the CLI. The saved key file is not loaded by every application automatically. Follow the next section for VS Code.

Launch VS Code with the variable available​

An app receives its environment when it starts. Setting a variable in VS Code’s integrated terminal cannot pass it back to an already running extension. A second VS Code window can also reuse the first instance’s environment. See VS Code’s environment inheritance rules.

  1. Save your work and fully quit all VS Code windows. On macOS, use Code → Quit Visual Studio Code (Cmd+Q); closing a window can leave the app running.
  2. Open a new external terminal. On macOS/Linux, use the shell configured above. On Windows, open a new PowerShell after saving the user variable. Run the appropriate Configured/Missing check above.
  3. Use cd to move to your project folder, then run code .. Replace the example path below with the folder where your project already exists. Keep quotes around paths containing spaces:
cd "$HOME/projects/my-project"
code .

The dot means the current folder; this command also works in PowerShell. If macOS reports code: command not found, open VS Code’s Command Palette (Cmd+Shift+P), run Shell Command: Install 'code' command in PATH, fully quit VS Code again, and open a new terminal. See the VS Code command-line setup.

  1. Open the extension panel and start a new conversation. Check the MCP server list and complete the dtxWiki read check.

On macOS/Linux, repeat this terminal launch after a restart when using the shell-file method. Opening VS Code from a desktop icon can use a different environment. A Configured result inside the integrated terminal alone does not prove the extension received the variable.

WSL and remote development​

A WSL: Ubuntu or SSH: … indicator in VS Code’s lower-left corner means the project is open in a Linux environment. Check the Extensions view to see where your AI extension is installed and running. Its configuration and variable must exist in that environment; a Windows user variable alone does not set a Linux variable.

For a CLI in WSL, complete the macOS/Linux steps inside WSL. For an extension running in WSL, also configure VS Code Server to load the same key file:

  1. In a WSL terminal, run mkdir -p "$HOME/.vscode-server", then nano "$HOME/.vscode-server/server-env-setup".
  2. Keep any existing setup. Add the following block once and save. This example is for standard VS Code; Insiders uses ~/.vscode-server-insiders/server-env-setup.
if [ -f "$HOME/.config/dtxwiki/mcp-env" ]; then
  . "$HOME/.config/dtxwiki/mcp-env"
fi
  1. Save your work and close VS Code’s WSL windows. Reboot Windows to restart WSL and its VS Code Server, then reopen the project in WSL and perform the read check. To avoid rebooting, use WSL: Kill VS Code Server from the Command Palette when available, then reconnect.

WSL’s VS Code Server does not run the usual shell startup scripts, so .bashrc alone is insufficient for this launch path. The official WSL environment setup guide documents this file. It is a shell script, not a .env file; a syntax error can prevent the server from starting. Correct or rename it from a normal WSL terminal if that happens. For SSH hosts and Dev Containers, follow the respective remote environment setup and restart that host’s extension process after changes.

If it still fails, or the key changes​

SymptomWhat to check next
Worked before restarting; now MissingSave the Windows user variable or add the shell startup block. MCP registration alone does not save the value.
CLI works; VS Code extension failsQuit all VS Code instances and launch from the configured external terminal. Check the extension’s host in WSL/SSH.
Added a project .env file but still MissingThis guide does not assume automatic .env loading. Use the explicit steps above.
Configured, but authentication failsVerify the key was copied correctly without the placeholder, quotes, or Bearer in its value. Then check expiry and revocation in Settings → MCP access.
Key was renewed but the app still uses the old oneUpdate the existing Windows variable or key-file line, then fully restart the client and VS Code. Restart the WSL server too if used.

Saving the value does not extend the key’s lifetime. Keys created in dtxWiki Settings expire after 90 days. To replace one, create a new key with the required workspace access, update your saved value, restart the client, and verify a read before revoking the old key if it is still active.

To remove local storage, delete the Windows user-variable entry or remove the export DTXWIKI_MCP_PAT=... line from your private file, then restart the apps. To clear the current terminal too, use unset DTXWIKI_MCP_PAT in Bash/Zsh or Remove-Item Env:DTXWIKI_MCP_PAT -ErrorAction SilentlyContinue in PowerShell. Removing a local copy does not revoke the server credential; revoke it in Settings → MCP access when it should no longer work.

Return to AI app setup to finish the extension configuration. These instructions explain configuration and restart behavior; verify an actual read in your installed client before relying on the connection.