DEV Community: Marçal Albert

Stop passing around .env files: Python secrets from AWS SSM

Marçal Albert — Tue, 04 Aug 2026 12:00:00 +0000

I thought moving secrets to AWS SSM Parameter Store had solved our configuration problem.

It solved storage.

It did not solve distribution.

More precisely, it did not solve how each execution context knew which parameters the application needed.

Across several AI and cloud projects, the same friction appeared whenever I switched repositories or helped someone run one.

A developer requested access. After approval, they still had to find the correct parameters, copy every value and build a local .env. Sometimes someone sent them one, and we had to work out whether it matched the current branch, included the latest variables or predated a secret rotation.

The same mapping also appeared across delivery systems. In one of my projects, developers run the service locally, CI runs in GitHub Actions and CD runs through AWS CodePipeline. Application values or their paths could end up repeated in local files, GitHub configuration and AWS pipeline configuration. Every execution context created another configuration surface to keep aligned.

This created two kinds of drift:

Value drift: AWS contains the current value, but a copied .env or GitHub Secret contains an older one.
Contract drift: the code expects a variable that one or more execution contexts do not provide.

None of this was difficult. It was repetitive, manual and easy to get wrong.

That is why I built Envilder.

Envilder is an open-source secret-resolution toolkit for AWS SSM Parameter Store and Azure Key Vault. It provides runtime SDKs, a CLI and a GitHub Action around one versioned map-file format.

Its core idea is:

Git defines what the application needs.
AWS stores the current values.
IAM decides who can access them.

boto3 is a good baseline

Python can already load SSM parameters with boto3:

import os

import boto3

mappings = {
    "DATABASE_URL": "/my-app/development/database-url",
    "API_TOKEN": "/my-app/development/api-token",
}

ssm = boto3.client("ssm")

for variable_name, parameter_path in mappings.items():
    response = ssm.get_parameter(
        Name=parameter_path,
        WithDecryption=True,
    )
    os.environ[variable_name] = response["Parameter"]["Value"]

This code is small, clear and valid. If one isolated Python service owns a few parameters, I would seriously consider stopping here.

Envilder uses boto3 internally. Its value lies not in replacing get_parameter(), but in turning the mapping into a resolution contract that follows the code and can be reused everywhere the project runs.

The map becomes the resolution contract

Envilder moves the mapping into envilder.json:

{
  "DATABASE_URL": "/my-app/development/database-url",
  "API_TOKEN": "/my-app/development/api-token"
}

The left side is the name expected by the application. The right side is its path in AWS SSM.

The file contains paths, not secret values, so it can live beside the code and be reviewed in pull requests. Parameter paths can still reveal infrastructure information, so review them before publishing the map in a public repository.

Install the Python SDK:

uv add envilder

Then load the mapping during application startup. Basic validation of the resolved result is opt-in:

from envilder import Envilder, validate_secrets

resolved = Envilder.load("envilder.json")
validate_secrets(resolved)

Envilder.load() resolves the available parameters, injects them into os.environ and returns them as a dictionary.

validate_secrets() checks the resolved dictionary, not completeness against the map. It raises SecretValidationError when the dictionary is empty or an included value is empty or whitespace-only.

Missing SSM parameters are omitted before this check, while permission, credential and other provider errors still propagate. The application's normal startup configuration layer therefore remains responsible for required keys, types and semantic validation.

The map defines how application variable names map to provider paths.

Do not log resolved. It contains the secret values.

I named the project Envilder as a blend of env and builder: it builds the process environment from a versioned map.

Branches carry their requirements

Suppose a pull request introduces:

PAYMENTS_API_TOKEN

The same pull request adds its SSM mapping to envilder.json.

Anyone checking out that branch receives the matching resolution contract. A CI/CD workflow using the map receives it from the same commit.

The parameter must still exist in AWS, and each consumer must have permission to read it. Envilder cannot create missing infrastructure, grant access or force someone to update the map.

What it does is make the requirement visible beside the code that needs it. Reviewers can catch a missing or incorrect mapping before another developer encounters a broken local setup or deployment.

Stop replicating application secrets

A common solution is to copy application secrets from AWS into GitHub Secrets.

That works, but the same value now exists in two systems. When the AWS value changes, someone must update the GitHub copy. Adding another repository or environment creates more copies.

If the application already calls Envilder.load() at startup, a workflow that runs the application does not need an Envilder-specific resolution step. It only needs an AWS identity and can start the application as usual. The relevant job fragment is:

# ...workflow trigger, job and runner configuration omitted...

permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/checkout@v7

  - uses: actions/setup-python@v7
    with:
      python-version: "3.12"

  - uses: astral-sh/setup-uv@v9.0.0

  - run: uv sync --locked

  - uses: aws-actions/configure-aws-credentials@v6
    with:
      role-to-assume: ${{ vars.AWS_ROLE_TO_ASSUME }}
      aws-region: ${{ vars.AWS_REGION }}

  - run: uv run python -m my_app

configure-aws-credentials exchanges GitHub's OIDC token for short-lived AWS credentials. boto3 finds those credentials through its default chain, and the Python SDK resolves envilder.json inside the application process.

No application secret needs to be copied into GitHub Secrets, repeated in the workflow or written to a .env in this path. The workflow still selects the correct AWS role, region and application command. Those are execution-context decisions, not application secret values.

CI and CD do not need to live on the same platform. In my case, GitHub Actions runs CI while AWS CodePipeline orchestrates deployment. CodeBuild has its own IAM service role, and the deployed workload can use an ECS task role or Lambda execution role.

The deployment pipeline may not need to read application secrets at all. It can deploy the code and its map together, then let the application resolve the values at startup. If a CodeBuild command genuinely needs a secret, it can use the same map through its own AWS identity instead of maintaining another copy.

If a build or deployment tool specifically requires an environment file, the Envilder CLI and GitHub Action remain available as alternative delivery mechanisms.

Version tags are shown here for readability. In production workflows, pin actions to full commit SHAs according to your supply-chain policy.

The important difference is that DATABASE_URL and API_TOKEN no longer need to be maintained as long-lived GitHub Secrets. AWS remains their source of truth, the map remains part of the code review and the SDK resolves the values only when the process starts.

From handoff to checkout

Envilder does not remove the access request. Any consumer that resolves secrets still needs the correct AWS account and region, the required SSM permissions and, when applicable, KMS permissions.

It removes the manual work that often follows approval.

Before:

Request access
Find every parameter
Copy every value
Build a local .env
Replicate values into CI/CD
Check whether everything matches the branch
Repeat for each project and environment

After:

Request access
Authenticate with AWS
Check out the project
Run the application or pipeline

AWS CLI is not required by the Python SDK, but it is useful for local profiles and AWS SSO. Production applications should normally use runtime IAM roles.

This also answers the rotation question from the opening. A copied .env or GitHub Secret remains stale after a value changes, while Envilder resolves the current value the next time the application starts, whether locally, in CI or in its runtime environment.

It does not refresh an already running process automatically. Live refresh still requires an application-specific strategy.

💡 A supervised refresh mode that re-resolves secrets and restarts an Envilder-managed child process is on the roadmap.

One map, several execution contexts

The same map can travel through different systems while each context keeps its own AWS identity:

Context	AWS identity	What happens
Local development	AWS SSO or profile	The SDK resolves secrets when the application starts
GitHub Actions CI	IAM role assumed through OIDC	Tests or the application resolve secrets inside their process
AWS CodePipeline with CodeBuild	CodeBuild service role	Deployment commands resolve only the secrets they genuinely need
ECS or Lambda runtime	ECS task role or Lambda execution role	The application resolves secrets at startup

The credentials and permissions remain environment-specific. The shared part is the versioned resolution contract between application names and provider paths.

Python, Node.js and .NET SDKs use that resolution contract inside the application process. The Envilder CLI and GitHub Action can generate a .env when a tool explicitly requires one.

Envilder also supports Azure Key Vault, and development, staging and production can use separate map files. Those topics deserve their own posts, so this article stays focused on Python and AWS SSM.

Where the trade-off lands

Envilder is not a secrets manager, proxy or new security boundary. The cloud provider remains the backing store and access boundary.

It also does not remove every environment-specific decision. Any context that resolves secrets must still select the correct map and cloud identity for development, staging or production.

Resolving directly from AWS also means local startup depends on network access and valid AWS credentials. Teams that require fully offline development will need a separate local override or emulation strategy.

The current Python SDK makes one synchronous get_parameter() call per mapping. Each call still inherits boto3's retry and backoff behaviour, but this SDK does not batch or parallelize resolution. For a large mapping or performance-sensitive startup, direct boto3 code using batched get_parameters() calls may be better.

Use boto3 directly when:

One application owns a small mapping
You need complete control over SSM requests
You need custom batching, caching or live-refresh behaviour

These are current boundaries, not permanent ones. Batching for the Python SDK is already tracked, and caching or refresh should evolve from real use cases rather than guesses.

If one of these limits affects your project, open an issue or contribute. With shared experience, we can grow Envilder together and solve common problems once instead of rebuilding the same conventions in every codebase.

Use Envilder when:

Mapping changes should travel with branches and pull requests
Developers should not exchange or rebuild .env files
Local development, CI/CD and multiple runtimes need the same resolution contract

The choice is not really boto3 versus Envilder.

Envilder uses boto3.

The choice is whether to maintain your own convention around it or use Envilder's map-file convention.

Push is optional

The Python SDK only reads secrets.

Envilder also includes an optional CLI for importing an existing .env into the mapped provider paths:

npx envilder \
  --push \
  --envfile=.env.bootstrap \
  --map=envilder.json

The CLI requires Node.js. Push is an explicit, one-way operation for bootstrapping or migration, not continuous synchronization.

Treat .env.bootstrap as sensitive migration input: do not commit it and remove it after the import.

If you do not need it, do not use it.

Try it on one service

Pick a small, non-critical Python service that already uses SSM:

Install Envilder.
Commit its envilder.json.
Add Envilder.load() before the application's normal startup configuration validation.
Let the versioned map travel through CI, deployment and the running service.
Ask a teammate who has AWS access but no list of parameter paths or copied .env to run it.

If Envilder adds more ceremony than it removes, keep the boto3 version.

If it shortens the handoff and removes duplicated configuration across execution contexts, I would like to know what worked and what did not.

Open an issue for confusing behaviour, missing documentation or anything that made setup harder than expected.

Honest feedback from a real project is more useful to me than a generic feature request.

Learn more

Envilder is open source under the MIT license.

The storage problem was already solved.

Envilder aims to make configuration handoffs explicit wherever code runs: for developers, coding agents, delivery pipelines and production runtimes.

LocalStack integration tests without .env files

Marçal Albert — Sun, 05 Jul 2026 01:12:45 +0000

A follow-up to How I run LocalStack without committing LOCALSTACK_AUTH_TOKEN. That post used Docker Compose and a generated .env. This one removes the file entirely.

LocalStack's unified image changed the shape of local integration tests. Since LocalStack for AWS moved to a unified image that requires LOCALSTACK_AUTH_TOKEN, getting realistic AWS behavior means you need a real token before the container even starts.

So the test fixture needs a secret before the test environment exists.

The usual fix is a generated .env:

get the token into a secret store in the first place
generate the file before tests
gitignore it
load it into Docker, Testcontainers, or Aspire
keep local and CI aligned

It works.

But now there is a file whose only job is to carry a secret into your tests: something to generate, gitignore, keep in sync and never commit by accident. One more moving part that lives next to your real configuration instead of inside it.

When a tool expects a file (Docker Compose, shell scripts, legacy tooling), a .env is a good bridge.

When the consumer is code, the bridge is unnecessary.

Testcontainers and Aspire start LocalStack from inside your test process, and code can resolve the secret directly:

SSM -> memory -> container environment

Nothing to generate, nothing to gitignore, nothing to go stale.

This is not meant to replace your secrets manager. It just removes the generated .env hop when the consumer is already code.

Why not just call SSM directly?

You can. A direct ssm.getParameter(...) in the fixture is perfectly reasonable, and if your app is AWS-only and already loads Parameter Store through the native config provider (builder.Configuration.AddSystemsManager(...) in .NET), you probably do not need anything else in runtime. Reading secrets is a solved problem.

The part that stays implicit with direct calls is the contract: which logical keys this project needs, where each one lives, and what has to exist before it boots. That knowledge ends up scattered across C# code, SSM paths, GitHub Actions secrets and a stale README. Nobody has the full list in one place.

A committed map surfaces it. It is the list, versioned and reviewable in a PR:

LOCALSTACK_AUTH_TOKEN -> /demo/localstack/auth-token
DATABASE_URL          -> /demo/db/url            # new

Add a key and everyone sees the project grew a dependency. Because the code depends on the logical name and every consumer reads the same map, rotating a value, changing a path, or pointing at a different provider is an edit in one place rather than a hunt across call sites. The consumer still has to use the value it wants; it just never has to learn how to fetch it. In a monorepo, where each service commits its own envilder.json, that visibility compounds: you can see at a glance what every service depends on without reading its code.

That is the trade:

direct SDK call -> resolution logic per call site, contract stays implicit
shared contract -> one versioned map, every consumer resolves the same thing

One contract, many consumers: the .NET fixture, the Python one, the TypeScript setup and every pipeline all resolve the same committed map. It is the same instinct as infrastructure as code, applied to the secret contract: make the implicit explicit and put it under version control. That is a win on a single stack, before any multi-provider story enters the picture.

And if you already centralize this in one config layer, good: that layer is the contract. Envilder just makes it explicit and provider-agnostic instead of hand-rolled per stack.

One honest caveat while we are here: removing the .env is not a stronger runtime secret boundary. The token still ends up in the container environment because LocalStack needs it there. The improvement is operational: there is no intermediate .env file to generate, ignore, sync, clean up or accidentally commit.

The contract

One file, committed at the repo root. Paths, not values:

{
  "$config": {
    "provider": "aws",
    "profile": "default"
  },
  "LOCALSTACK_AUTH_TOKEN": "/demo/localstack/auth-token"
}

The Envilder SDK resolves it at test time. Same pattern in every stack.

TypeScript

const environment = await Envilder.resolveFile('../envilder.json');

localstack = await new LocalstackContainer('localstack/localstack:stable')
  .withEnvironment(Object.fromEntries(environment))
  .start();

Full test: typescript-testcontainers/localstack.test.ts

Python

container = LocalStackContainer("localstack/localstack:stable")
container.env.update(Envilder.resolve_file(str(MAP_FILE)))

container.waiting_for(LogMessageWaitStrategy(re.compile(r"Ready\.")))
DockerContainer.start(container)

The explicit wait for the Ready. log line is there because the built-in wait does not match the consolidated 2026 LocalStack image.

Full test: python-testcontainers/test_localstack.py

.NET

var environment = await Env.ResolveFileAsync("envilder.json");

_container = new LocalStackBuilder("localstack/localstack:stable")
    .WithEnvironment(new Dictionary<string, string>(environment))
    .Build();

await _container.StartAsync();

Full fixture: dotnet-testcontainers/LocalStackFixture.cs

Same pattern, different orchestrator: .NET Aspire

In .NET, you might not be using Testcontainers directly. Aspire can also orchestrate containers, and it has its own LocalStack integration.

The AppHost resolves the token and injects it into the LocalStack resource:

builder.Configuration["LocalStack:UseLocalStack"] = "true";

var localstack = builder
    .AddLocalStack("localstack", configureContainer: c => c.ContainerImageTag = "stable")
    ?? throw new InvalidOperationException("LocalStack is disabled.");

foreach (var (key, value) in await Env.ResolveFileAsync("envilder.json"))
{
    localstack.WithEnvironment(key, value);
}

One gotcha: without that UseLocalStack config flag, AddLocalStack returns null. That is the package's fallback-to-real-AWS mechanism.

aspire run and you have a local AWS, token included, with nothing to export first.

And it is just as testable: Aspire.Hosting.Testing boots the same AppHost from an xUnit fixture, so the round-trip test works identically to the Testcontainers one.

Aspire is not .NET-only either. The same AppHost can orchestrate Python and JavaScript apps next to LocalStack, so a FastAPI service resolving its secrets with the Envilder Python SDK fits in the same graph.

Full AppHost and its test suite: dotnet-aspire/

That is the whole integration. The token travels from AWS SSM into the container's environment without being written to a generated file. When it rotates, I update it in SSM once per environment and every suite picks it up on the next run.

The recursion

This is exactly how Envilder's own test suite works. The SDK resolves the token that starts the LocalStack container used to test the SDK against an emulated SSM.

If Envilder cannot fetch its own secret, the suite fails before a single assertion runs. It is the most honest smoke test in the repo.

CI

The mechanism does not change. The secret does.

Locally, the profile in $config resolves my credentials from ~/.aws/credentials, and the map points to my developer LocalStack token.

In GitHub Actions, OIDC through aws-actions/configure-aws-credentials feeds the default credential chain, and the map can point to a CI Auth Token stored in SSM. LocalStack developer tokens are not meant for pipelines, so CI should use a CI-specific token.

Same contract, different credentials, different secret.

Try it

Minimal, runnable examples live in envilder-examples, one folder per stack and orchestrator:

typescript-testcontainers
python-testcontainers
dotnet-testcontainers
dotnet-aspire
typescript-aspire: Aspire's TypeScript AppHost, where apphost.ts resolves the token with the same @envilder/sdk

Each one resolves the token, boots LocalStack, and does a SecureString round-trip against emulated SSM.

Seeding the token is one command. That is the "get the token into a secret store" step from the top of this post, handled without any manual setup:

npx envilder --push --key=LOCALSTACK_AUTH_TOKEN \
  --value=<your-token> \
  --secret-path=/demo/localstack/auth-token

Where this came from

Envilder started as a fix for my own problem: I wanted the secret mapping in Git and the values out of it, resolved by whatever consumes them. This post is one concrete case where that helped, nothing more. If it turns out other people hit the same wall, there is obvious room to grow it (validating a map in CI, diffing a map against the store, and so on), but that is speculative and feedback-driven, not a promised roadmap. For now it does one thing, and this is that one thing.

Takeaway

secret values outside Git
secret mappings inside Git
resolution at runtime
no generated file when the consumer is code
one contract across every call site

.env files are the right bridge when a tool needs a file. Test fixtures are code. Let them resolve secrets through the same contract as everything else.

How I run LocalStack without committing LOCALSTACK_AUTH_TOKEN

Marçal Albert — Mon, 08 Jun 2026 23:13:33 +0000

Using Envilder to keep the LocalStack auth token out of Git while preserving a reproducible local Docker Compose setup.

I wanted a reproducible LocalStack setup without committing LOCALSTACK_AUTH_TOKEN to the repository.

That sounds simple, but it touches a common local development problem:

How do you make a project easy to run without putting real secrets in Git?

LocalStack expects the auth token to be available through the LOCALSTACK_AUTH_TOKEN environment variable when starting it with Docker, Docker Compose, the LocalStack CLI, or CI workflows.

Since LocalStack for AWS 2026.03.0, it ships as a consolidated Docker image and requires an auth token to start, so managing LOCALSTACK_AUTH_TOKEN cleanly is now part of the normal setup path, not just a Pro-only edge case.

That token is a secret, so I did not want to:

commit it to the repository
paste it into docker-compose.yml
duplicate it across helper scripts
rely on a manual export LOCALSTACK_AUTH_TOKEN=... step every time
make the setup work only on my machine

What I wanted instead was a small, repeatable contract:

this project needs LOCALSTACK_AUTH_TOKEN
resolve it from the secret store
inject it locally when needed
do not commit the value

That is the pattern I ended up using with Envilder.

The Pattern

The idea is simple:

secret values stay in a real secret store
the repository contains only the mapping
local development generates a .env file from that mapping
Docker Compose reads the generated .env
the token never gets committed

In this case, the secret is LOCALSTACK_AUTH_TOKEN.

In another project, it could be a database password, webhook secret, API key, or service credential.

Defining the Secret Mapping

Here is a minimal envilder.json example using AWS SSM Parameter Store:

{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "aws",
    "profile": "default"
  },
  "LOCALSTACK_AUTH_TOKEN": "/envilder/localstack/auth-token"
}

This file is safe to commit because it does not contain the token.

It only says:

To produce LOCALSTACK_AUTH_TOKEN, resolve this value from the secret store.

The actual token remains outside the repository.

Generating the Local `.env`

Before starting LocalStack, generate the local environment file:

npx envilder --map=envilder.json --envfile=.env

That produces a local .env file like this:

LOCALSTACK_AUTH_TOKEN=...

The .env file should be ignored by Git:

.env

Now the project contains the setup contract, but not the secret.

Passing the Token to LocalStack

A Docker Compose service can reference the variable as usual:

services:
  localstack:
    image: localstack/localstack:stable
    ports:
      - "4566:4566"
      - "4510-4559:4510-4559"
    environment:
      LOCALSTACK_AUTH_TOKEN: "${LOCALSTACK_AUTH_TOKEN:?Run npx envilder first}"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"

Docker Compose automatically reads a .env file from the project directory for variable interpolation.

If your generated env file lives somewhere else, you can pass it explicitly:

docker compose --env-file path/to/.env up

The payoff is what a new contributor sees after cloning:

npx envilder --map=envilder.json --envfile=.env
docker compose up

Two commands, no Slack message asking "where do I get the token?", no secret in Git.

Why not direnv, 1Password, or chamber?

For one developer, export LOCALSTACK_AUTH_TOKEN=... works, but it creates hidden local state the repo never documents. The interesting comparison is against the tools that already resolve secrets:

direnv loads env vars when you enter a directory, but .envrc is just shell. You still write export LOCALSTACK_AUTH_TOKEN=$(aws ssm get-parameter ...) yourself, per variable, per project. It is a loader, not a resolver, and the mapping lives in bespoke shell instead of a declared contract.
1Password op run injects secrets at runtime and is excellent, but it assumes 1Password is your store. If your secrets already live in AWS SSM or Azure Key Vault, you are adding a vendor, not removing one.
chamber is the closest match for the AWS-only case: chamber exec service -- docker compose up reads straight from SSM. If you never leave AWS and only need secrets at the command line, chamber or a three-line script is genuinely enough.

Envilder's narrow bet is different on three points:

The mapping is an explicit name -> path contract committed as JSON, not a service prefix or shell glue.
The store is your own cloud. No third-party infrastructure holds the secret.
The same map drives the CLI here, CI, and in-process resolution through the SDKs, so local dev and runtime read one contract.

If you only ever touch AWS from a shell, you may not need it. The case shows up when you have more than one provider, more than one language, or want the same declared contract locally, in CI, and at runtime.

The Slightly Meta Part

I ran into this while working on Envilder.

Envilder uses LocalStack for integration testing.

LocalStack needs LOCALSTACK_AUTH_TOKEN.

So I used Envilder to inject the token needed to start the LocalStack environment used to test Envilder.

The tool became its own first customer, which is always a useful kind of feedback.

A Note on LocalStack Auth Tokens

LocalStack's documentation is clear that LOCALSTACK_AUTH_TOKEN should be kept confidential and should not be committed to source control.

This post is not about bypassing that requirement.

It is about treating the token like any other secret:

store it safely
resolve it when needed
avoid leaking it into Git
keep the project setup reproducible

For open source maintainers, this matters. A project can require credentials for local or CI workflows and still provide a clean setup path for contributors.

Takeaway

LOCALSTACK_AUTH_TOKEN is just one example of a broader problem.

Projects often need secrets during local development, CI/CD, tests, and runtime. The hard part is not only storing those secrets safely. It is keeping the mapping between "what the app needs" and "where the secret lives" clear and consistent.

The pattern I like is:

secret values outside Git
secret mappings inside Git
one contract for local dev, CI/CD, and runtime

That is the reason I am building Envilder.

Not to add another place to store secrets.

Just to make secret resolution explicit, repeatable, and versionable.

One year of Envilder: from a CLI script to SDKs, push mode, and a website

Marçal Albert — Thu, 07 May 2026 00:11:10 +0000

This is a follow-up to my first post about Envilder, where I introduced it as a simple CLI to generate .env files from AWS SSM. A year later, it has grown quite a bit, and I want to share what changed, why, and what I learned building it almost entirely with AI.

Where we left off

A year ago, Envilder did one thing: pull secrets from AWS SSM Parameter Store and write them to a .env file. That was already useful. It removed the "what's the DB password?" Slack messages and kept onboarding fast.

But real usage exposed real gaps. If you haven't seen Envilder before, here's the basic flow: create secrets via CLI and consume them in your app:

The map file: one contract, every context

Before getting into features, this is the core idea behind Envilder and what makes it different from ad-hoc scripts.

Everything in Envilder revolves around a single JSON file: envilder.json. It's a declarative contract that decouples your application from the secret provider:

{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "aws",
    "profile": "my-profile"
  },
  "DB_PASSWORD": "/my-app/prod/db-password",
  "API_KEY": "/my-app/prod/api-key",
  "STRIPE_SECRET": "/my-app/prod/stripe-secret"
}

Left side: the environment variable name your app expects. Right side: the path in your secret provider. The $config block declares the provider and credentials.

The key point: your application never knows where secrets come from. It depends on envilder.json, not on AWS SSM, not on Azure Key Vault. If you migrate from SSM to Key Vault tomorrow, you change the $config block. Your app code, your CI/CD pipelines, your onboarding scripts don't change at all. The SDKs even let you override the provider at runtime via a fluent builder, without touching the file.

At the SDK level, this goes further: the code depends on an ISecretProvider abstraction, not on AWS or Azure directly. The map file feeds that abstraction. Switch provider in $config, your app code stays the same.

And because envilder.json contains paths, not values, it lives in your repo, versionable, reviewable, shared across the team. When someone joins the project, they run one command and get every secret they need. When someone adds a new secret, the diff in envilder.json is the documentation. The same file is consumed by the CLI, all three SDKs, and the GitHub Action. One contract, every context.

What changed (and why)

1. Push mode: stop switching tools

The first friction: every time someone needed to add a new secret, they had to open the AWS Console or use the AWS CLI directly. Envilder was a read-only tool.

Now you can push secrets to the cloud directly from Envilder. The powerful part: it accepts an .env file and your envilder.json, and pushes everything in one go:

envilder --push --env-file=.env --map-file=envilder.json

This reads the .env values, maps them through envilder.json to the right provider paths, and creates (or updates) all secrets at once. New project? Define your envilder.json, write your .env locally, push. Done. No clicking through the AWS Console, no running 15 aws ssm put-parameter commands.

You can also push a single key when needed:

envilder --push --key=DB_PASSWORD --value=12345 --ssm-path=/my-app/db/password

One tool for reading and writing. No context switching.

One detail worth noting about pull: when generating your .env, Envilder only overwrites the keys declared in envilder.json. Any other variables already in your .env are left untouched. This means you can safely mix Envilder-managed secrets with local-only variables (like DEBUG=true or LOG_LEVEL=verbose) without losing them on every pull.

2. SDKs: because `.env` files are a liability

Generating .env files was the original goal, but it's inherently insecure: secrets land on disk, they get accidentally committed, they go stale. The safer approach is resolving secrets at runtime, directly in your application.

Envilder now has SDKs for three platforms:

Python (pip install envilder):

from envilder import Envilder

Envilder.load('envilder.json')
# secrets are now in os.environ, no file on disk

.NET (dotnet add package Envilder):

// Via IConfiguration (ASP.NET)
var config = new ConfigurationBuilder()
    .AddEnvilder("envilder.json")
    .Build();

// Or one-liner
Envilder.Load("envilder.json");

The .NET SDK targets .NET Standard 2.0, so it works from .NET Framework 4.6.1 all the way to .NET 10. It integrates natively with IConfiguration and IServiceCollection. It feels like a first-class .NET library, not a wrapper.

TypeScript/JavaScript (@envilder/sdk):

import { Envilder } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');

All three SDKs support a fluent builder for runtime overrides (switch profile, provider, or vault URL without touching the map file), environment-based loading, and secret validation.

3. Azure Key Vault support

This is the payoff of the abstraction. The SDK architecture already had a provider interface (ISecretProvider), so adding Azure Key Vault was a natural extension. Same envilder.json, different $config:

{
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "DB_PASSWORD": "db-password"
}

Your app code doesn't change. You can even implement your own provider (HashiCorp Vault, GCP Secret Manager) by plugging in the interface.

4. LocalStack supports Envilder, and Envilder uses itself

LocalStack supports the Envilder project, which means the acceptance tests run against a local AWS emulation with full SSM support.

The fun part: LocalStack now requires an auth token to run. How does Envilder manage that token? With itself. The CI pipeline uses Envilder to resolve the LOCALSTACK_AUTH_TOKEN from SSM before running the tests that validate Envilder against LocalStack. It references itself as a dependency of its own test infrastructure.

I wrote up this pattern in full, from the envilder.json mapping to the Docker Compose wiring that keeps the token out of Git: How I run LocalStack without committing LOCALSTACK_AUTH_TOKEN.

5. GitHub Action

CI/CD was always the primary use case, so there's now an official GitHub Action:

- uses: macalbert/envilder/github-action@v0.7.9
  with:
    map-file: envilder.json
    env-file: .env

6. A website

envilder.com: documentation, schema references, and a landing page. Nothing fancy, but it makes the project feel real and gives the SDKs a proper home.

Where Envilder fits

Doppler and Infisical are full platforms with their own infrastructure. Your secrets are stored on their servers, managed through their dashboards. That's a valid choice, but it comes with cost (Doppler Team at $21/user/month, Infisical Pro at $18/identity/month) and a trust trade-off.

Envilder has no infrastructure. Zero. Your secrets stay in your cloud (AWS SSM or Azure Key Vault) and never pass through a third party. Audit trails? CloudTrail or Azure Monitor. Access control? IAM or Azure RBAC. Encryption at rest, versioning? Already there. You're not giving anything up. Those capabilities come from the provider you already pay for.

Envilder just makes them easy to consume everywhere: local dev, CI/CD, application runtime. One envilder.json, one command, SDKs for three platforms. No servers, no middleman, no SaaS fees. MIT licensed.

The AI part (brief version, full post coming)

I built most of this project with AI assistance. Started with GPT-4 a year ago, went through several Claude models (Sonnet, Haiku), and the real leap came with Claude Opus 4.5 for planning and architecture decisions. For implementation with good skill definitions, Sonnet remains excellent and more cost-effective.

I also use CodeRabbit for automated code review on every PR. It catches things I miss and forces consistency.

I'm writing a dedicated post about what worked, what didn't, and where AI genuinely accelerated the project versus where it got in the way. Stay tuned.

Numbers (honest ones)

350 commits, 39 releases
8 contributors: 1 human, 7 bots (Copilot, Gemini, CodeRabbit, Jules, Dependabot, GitHub Advanced Security)
SDKs published on npm, PyPI, and NuGet with full CI/CD pipelines
Used internally across multiple projects at M47 AI Company
Trusted Publishing enabled on PyPI (Sigstore attestations)

What's next

The roadmap includes drift detection (check mode), auto-discovery for bulk parameter fetching, and more provider backends. But the priority is adoption: making it easy for people to try, and making sure it works perfectly for the simple use cases it targets.

If you manage secrets with AWS SSM or Azure Key Vault and the big platforms feel like overkill, give Envilder a try:

🌐 envilder.com
🔧 GitHub
📦 npm (CLI) · npm (SDK) · PyPI · NuGet

I'd love feedback, especially from people who tried the first version.

A special thanks to Brian Rinaldi and the LocalStack team for accepting Envilder into the LocalStack for Open Source program. Their fully subsidized Ultimate tier license is what powers our acceptance test suite against a local AWS emulation.

From chaos to consistency: how we centralized secrets with AWS SSM and a simple CLI

Marçal Albert — Sat, 10 May 2025 16:18:29 +0000

At M47, security is one of our concerns across all our AI and cloud-native projects. That’s why we store all sensitive configurations in a secure and centralized place like the AWS SSM Parameter Store. While our repositories are private, that’s not enough. Secrets don’t belong in code.

We deliberately use Parameter Store over Secrets Manager because our needs don’t require secret rotation or tight lifecycle policies, and SSM gives us all the flexibility and control we need for storing tokens, API keys, and service credentials.

But then comes the friction:

Every time we onboard someone, clone a project, create/update a new CD pipeline, or adjust a Dockerfile, we have to manually fetch and sync secrets. This leads to overhead, mistakes, and inconsistencies between local and CD pipelines.

That’s why I built Envilder. A CLI tool to automate the generation of .env files from a single source of truth: AWS SSM.

It helps us:

Keep secrets in one place (SSM)
Stay consistent across teams and environments
Avoid copy-pasting or writing fragile scripts

Since we often work with multiple AWS CLI profiles, Envilder also supports switching profiles easily to handle multi-account setups.

👉 GitHub repo

👉 [Full guide continues below ⬇️]

💡 What does it do?

Envilder reads a mapping file that links environment variable names to AWS SSM parameter paths. Then it fetches the values securely and writes a clean .env file.

🧩 Example

Your param-map.json might look like this:

{
  "DB_HOST": "/my-app/dev/DB_HOST",
  "DB_PASSWORD": "/my-app/dev/DB_PASSWORD"
}

Run:

envilder --map=param-map.json --envfile=.env

And you get:

DB_HOST=mydb.cluster-xyz.rds.amazonaws.com
DB_PASSWORD=supersecret

You can also use different AWS CLI profiles:

AWS_PROFILE=staging envilder --map=param-map.json --envfile=.env

👥 Why it helps teams

This small tool makes a big difference when:

🧑‍💻 Onboarding new team members: no more “what’s the DB password?”
🔄 Keeping environments in sync: any change in SSM is reflected across the team
⚙️ CI/CD pipelines always up-to-date: e.g. GitHub Actions, CodeBuild, GitLab
🧼 Centralized configuration: avoid duplication and keep secrets in one secure place
🧭 Supports multiple AWS profiles: ideal for multi-account or multi-env setups

✅ Features

Works with SecureString and plain parameters
CLI-first, fast, and script-friendly
Compatible with any CI/CD system
Supports static values and fallbacks
AWS profile support (AWS_PROFILE)

📦 Install

npm install -g envilder

Or:

envilder --map=param-map.json --envfile=.env --profile=aws-account

🙌 I’d love your feedback

It’s still an early-stage project, but already helpful in several real-world teams.

If this sounds familiar, or you’ve solved this differently, I’d love to hear from you.

GitHub: https://github.com/macalbert/envilder

Update (2026): That was stage 1: a CLI that writes .env files. Envilder has since leveled up with SDKs for three languages, push mode, and Azure support. → Next level: One year of Envilder

DEV Community: Marçal Albert

Stop passing around .env files: Python secrets from AWS SSM

boto3 is a good baseline

The map becomes the resolution contract

Branches carry their requirements

Stop replicating application secrets

From handoff to checkout

One map, several execution contexts

Where the trade-off lands

Push is optional

Try it on one service

Learn more

LocalStack integration tests without .env files

Why not just call SSM directly?

The contract

TypeScript

Python

.NET

Same pattern, different orchestrator: .NET Aspire

The recursion

CI

Try it

Where this came from

Takeaway

Links

How I run LocalStack without committing LOCALSTACK_AUTH_TOKEN

Using Envilder to keep the LocalStack auth token out of Git while preserving a reproducible local Docker Compose setup.

The Pattern

Defining the Secret Mapping

Generating the Local .env

Passing the Token to LocalStack

Why not direnv, 1Password, or chamber?

The Slightly Meta Part

A Note on LocalStack Auth Tokens

Takeaway

One year of Envilder: from a CLI script to SDKs, push mode, and a website

Where we left off

The map file: one contract, every context

What changed (and why)

1. Push mode: stop switching tools

2. SDKs: because .env files are a liability

3. Azure Key Vault support

4. LocalStack supports Envilder, and Envilder uses itself

5. GitHub Action

6. A website

Where Envilder fits

The AI part (brief version, full post coming)

Numbers (honest ones)

What's next

From chaos to consistency: how we centralized secrets with AWS SSM and a simple CLI

💡 What does it do?

🧩 Example

👥 Why it helps teams

✅ Features

📦 Install

🙌 I’d love your feedback

Generating the Local `.env`

2. SDKs: because `.env` files are a liability