Work with agents / Local workspaces
Give each workspace its env values
Your app needs its .env values in each workspace, and you do not want a copy of your secrets in every folder. Keep the .env file in the vault of the repository, and src ws exec puts its values into the environment of the command, without a .env file.
4 min read
You need:
- A login:
src auth login. - A checkout with a git remote on TanStack Source.
- Your
.envfile in the vault of the repository:src vault put .env.
1. Allow the vault values
src ws trust
It lists the vault files and the names of their variables, and asks you to allow them. It never shows a value.
2. Run a command
src ws exec api -- pnpm dev
The command gets the values of the vault in its environment. src writes no .env file.
Warning
src keeps the vault values off the disk and out of git and checkpoints. It does not hide them from the process. A command that runs with a value can read it, print it or write it to a file.
Done
Each workspace gets the same .env values from the vault, and src writes no copy of them into the workspace folders.
Which values the command gets
The vault files that exec reads are at the top of the repository, in this order. A later file wins:
.env.env.development.env.local.env.development.local
The value of a variable comes from the first of these sources that has it:
--env KEY=VALUEonexec.- The ports of the workspace.
- The variables of the layers and caches.
- The vault values.
- The environment of your shell.
The setup and teardown hooks get the same environment. A prepare that a git hook starts never reads the vault. src hides the vault values in the output of a hook that failed.
When exec cannot use the vault
The command still runs without the vault values, and exec prints one line that says why. This happens when:
- You have no login.
- The checkout has no remote on TanStack Source.
- You did not allow the vault values.
--no-vault skips the vault and calls no server.
Copy env files into each workspace
Some files that a workspace needs are not in git and not in the vault, for example .env.local or .dev.vars. Name them in envFiles, and create copies them from your checkout into each new workspace:
envFiles: [.env.local, "apps/*/.dev.vars"]
secrets: ["certs/**"]
- Each env file is a copy, never a link. A change in a workspace does not change your checkout.
restoreandsynccopy an env file again when the workspace does not have it.- Checkpoints,
diffandacceptleave out every untracked.env*file, the env files, and the paths insecrets. So an agent cannot bring a change of them into your checkout. - A file that git tracks stays in checkpoints, as git has it.
Names that the vault never sets
A vault value never sets a variable that changes how programs load or run, where they connect, or which programs they start. Else, a person who can write the vault can run code on your computer. exec and src ws trust leave these names out, and name them without their values:
| Kind | Names |
|---|---|
| Name starts with | LD_, DYLD_, GIT_, SRC_WS_, NPM_CONFIG_, YARN_, PNPM_, BUN_, LUA_INIT, DOTNET_, COMPLUS_, CORECLR_, UV_, PIP_, CARGO_, RUSTC_ |
| Loaders and runtimes | NODE_OPTIONS, NODE_PATH, PYTHONPATH, PYTHONSTARTUP, PYTHONHOME, PERL5OPT, PERL5LIB, PERLLIB, PERL5DB, RUBYOPT, RUBYLIB, PHPRC, PHP_INI_SCAN_DIR, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, _JAVA_OPTIONS, RUSTFLAGS, GOFLAGS |
| Shells | BASH_ENV, ENV, ZDOTDIR, PATH, PATHEXT, COMSPEC, SHELL, IFS, GCONV_PATH, SHELLOPTS, PS4, PROMPT_COMMAND |
| Programs that tools start | BROWSER, EDITOR, VISUAL, PAGER, SSH_ASKPASS, GIT_ASKPASS, SUDO_ASKPASS |
| Connections and certificates | HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY, SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED |
| Your folders | HOME, USERPROFILE, APPDATA, LOCALAPPDATA, TMPDIR, TEMP, TMP |
Set by src ws exec | TURBO_CACHE_DIR, NX_CACHE_DIRECTORY, SCCACHE_DIR, RUSTC_WRAPPER, and the variables of your named ports |
- The names match in any case, so
Pathandhttp_proxyare left out too. - A key that is not a variable name is left out.
- Other names pass, for example
DATABASE_URL.src ws trustlists each name that passes before you allow it.