Stop leaking secrets: a guide to secure environment management with Vesper's `env.lua`

We've all done it. You quickly run export MY_API_KEY="supersecret..." in your shell to test something, and then you realize you've just saved a sensitive credential to your shell's history file in plain text. Or you commit a .env file by accident. Managing secrets is a hard problem. Vesper offers a powerful and elegant solution: **startup-loaded environment scripting**.

In this guide, we'll show you how to use a simple env.lua script to securely load secrets into your Vesper panes automatically, keeping them out of your shell history and your git repository.

The goal: secure, automated, context-aware secrets

Our goal is to create a system where the right API keys are automatically available in the right projects, without ever being typed manually into the shell. We will store our secrets in a plain text file, but we will use .gitignore to ensure it's never committed, and Vesper's `env.lua` script will be the intelligent bridge.

Step 1: create your secrets file

In your project directory, create a simple file named .tokens. This file will hold your secrets, one per line.

# Inside my-project/.tokens
GITHUB_API_KEY=ghp_123456789abcdefgh
STRIPE_API_KEY=sk_test_987654321fedcba

Now, the most important step: add this file to your project's .gitignore file to ensure it's never committed.

# Inside .gitignore
.tokens

Step 2: create your intelligent `env.lua` script

This is where the magic happens. In your Vesper configuration directory (~/.config/vesper/), create a file named env.lua. Vesper will run this script **once at startup**. We will write some simple Lua code to check for our .tokens file and load its contents.

-- Inside ~/.config/vesper/env.lua
local env = {}
local token_file_path = vim.fn.getcwd() .. "/.tokens"
local file = io.open(token_file_path, "r")

if file then
  for line in file:lines() do
    local key, value = line:match("([^=]+)=(.*)")
    if key and value then
      env[key] = value
    end
  end
  file:close()
end

return env

How it works: This script gets the current working directory, checks if a .tokens file exists, and if it does, it reads each line, splits it into a key and a value, and adds it to a table named `env`. Finally, it returns that table.

Step 3: the result

That's it. Now, restart Vesper. The script runs once at startup. If you open a new pane while inside `my-project`, the `env.lua` script will find the .tokens file and automatically make `GITHUB_API_KEY` and `STRIPE_API_KEY` available as environment variables in that pane. If you open a pane in a different directory that doesn't have a .tokens file, nothing happens.

You now have a secure, automated, and context-aware system for managing secrets, powered by Vesper's intelligent architecture.