Skip to content
Source
Sign inSign up

Give each workspace its env values

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 .env file 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:

  1. .env
  2. .env.development
  3. .env.local
  4. .env.development.local

The value of a variable comes from the first of these sources that has it:

  1. --env KEY=VALUE on exec.
  2. The ports of the workspace.
  3. The variables of the layers and caches.
  4. The vault values.
  5. 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.
  • restore and sync copy an env file again when the workspace does not have it.
  • Checkpoints, diff and accept leave out every untracked .env* file, the env files, and the paths in secrets. 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:

KindNames
Name starts withLD_, DYLD_, GIT_, SRC_WS_, NPM_CONFIG_, YARN_, PNPM_, BUN_, LUA_INIT, DOTNET_, COMPLUS_, CORECLR_, UV_, PIP_, CARGO_, RUSTC_
Loaders and runtimesNODE_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
ShellsBASH_ENV, ENV, ZDOTDIR, PATH, PATHEXT, COMSPEC, SHELL, IFS, GCONV_PATH, SHELLOPTS, PS4, PROMPT_COMMAND
Programs that tools startBROWSER, EDITOR, VISUAL, PAGER, SSH_ASKPASS, GIT_ASKPASS, SUDO_ASKPASS
Connections and certificatesHTTP_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 foldersHOME, USERPROFILE, APPDATA, LOCALAPPDATA, TMPDIR, TEMP, TMP
Set by src ws execTURBO_CACHE_DIR, NX_CACHE_DIRECTORY, SCCACHE_DIR, RUSTC_WRAPPER, and the variables of your named ports
  • The names match in any case, so Path and http_proxy are left out too.
  • A key that is not a variable name is left out.
  • Other names pass, for example DATABASE_URL. src ws trust lists each name that passes before you allow it.