Encrypted environment variables
Stop copying .env files between machines. Set a value once; every command that should have it finds it in its environment, and
nobody in the middle can read it.
$ pb env set STRIPE_API_KEY$ pb env run -- ./charge.sh$ pb env names
DATABASE_URL
STRIPE_API_KEY- 1
A hidden prompt asks for the value. It is encrypted on this computer before anything is sent.
- 2
The script finds STRIPE_API_KEY in its environment, here or on any of your machines.
- 3
Names only. No command ever prints a value.
Encryption
Each machine has its own key and gets only its own values. Your master password unlocks them, on your device.
How a value travels
Your device encrypts it with a key only your devices hold. Our server stores and forwards ciphertext. The machine decrypts it with its own key and hands it to your command.
- Encrypted between your machines. Nothing in the middle can read it.
- Stays on the machine.
Your laptop encrypts the value. The server stores ciphertext. The target machine decrypts it and passes it to your command's environment.
Scopes
A machine override beats your own value, which sits alongside the team's. pb env list shows what is set where, never the values.
| Scope | You run | Who gets it |
|---|---|---|
| Yours | pb env set NAME | Your terminals and commands on every machine of yours. |
| One machine | pb env set NAME --machine studio | The same name, a different value on that machine. Overrides yours there. |
| A team | pb env set NAME --team acme | Teammates who were granted the team's ENV. Your own values stay private inside the team. |
Where the values show up
A locked vault, a stopped daemon or no network never blocks your shell: it starts on time without the values and says so in one line.
Values are never written to logs, diagnostics or disk by Paperboat. What your own programs do with them is up to you.
| Paperboat terminals and pb exec | Automatically, when the session or command starts. |
|---|---|
| Scripts and CI | pb env run -- <command>. If the values cannot be loaded, the command does not run. |
| Plain ssh and your own shell | pb env hook --install once per machine, for bash, zsh or fish. |
| VS Code Remote-SSH terminals and tasks | The same hook. Restart the VS Code server on the host after installing it. |
Secrets for agents
A coding agent needs to know that STRIPE_API_KEY exists, not what it is. pb env names lists names;
pb env run puts the values into the child process and nowhere else.
A workspace owner can turn name listing off. More on running agents with Paperboat
$ pb env names | grep -q '^STRIPE_API_KEY$' && pb env run -- ./charge.sh$ printf %s "$SECRET" | pb env set NAME --value-stdin- 1
Check the name exists, then run with it.
- 2
Store a value without it appearing in a command line.
Questions
Can Paperboat read my secrets?
No. Values are encrypted on your device, and our servers only ever hold ciphertext. The keys are protected by a master password that never leaves your device, so we cannot decrypt them and cannot hand them to anyone else.
What if I forget the master password?
Use the recovery code you saved when you created the vault. If you lose both, the values cannot be recovered by you or by us; you reset the vault and set them again. That is the cost of us not having a copy.
Where is the key kept on each machine?
In the operating system's credential store: Keychain on macOS, Secret Service on Linux desktops. On a headless Linux server with no such store, an unlocked vault is held in memory for 15 minutes and never written to disk.
How is this different from a .env file or a secrets manager?
A .env file has to be copied to every machine and tends to end up in a repository. A secrets manager is an API your code calls. ENV is neither: values simply appear in the environment of commands on your machines, and are changed in one place.
What happens when I remove a machine?
It stops receiving values. Because it may have seen the old ones, pb tells you to rotate the keys, and pb env rotate does that without losing the values. Change the secrets themselves at their source too.
Can I give a command only some of the variables?
Not today. pb env run gives a command the whole set for the active workspace. Keep sets apart by using a team workspace or per-machine overrides.
Related
Start with the machine in front of you
Install Paperboat here, then on a second machine. Free for personal use, no card needed.
$ curl -fsSL https://get.pprbt.dev/install | bash > irm https://get.pprbt.dev/install.ps1 | iex