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 now needs an auth token: getting it into Testcontainers without a .env file

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

Since March 2026, the LocalStack image won't start without LOCALSTACK_AUTH_TOKEN. Here's how I feed it to Testcontainers (TypeScript, Python, .NET) and Aspire straight from AWS SSM, with no .env file in between.

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:

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.

The contract

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

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

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.

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
STRIPE_API_KEY        -> /demo/stripe/api-key    # 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 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.

LocalStack now requires an auth token: keeping it out of Git with Docker Compose

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

How I run LocalStack without committing LOCALSTACK_AUTH_TOKEN

Updated October 2026: This article now includes envilder exec, Azure Key Vault, and LocalStack for Azure. The original .env workflow is still here, just no longer the default approach I recommend.

Since LocalStack for AWS 2026.03.0, starting the AWS emulator requires an auth token. With Docker Compose, that means supplying LOCALSTACK_AUTH_TOKEN.

Fair enough. What I didn't want was another secret pasted into a Compose file, copied between scripts, or remembered as an undocumented export command.

I wanted the repository to explain what the project needs, without containing the actual credential.

I ran into this while building Envilder. The solution turned out to be slightly recursive. We'll get to that.

The pattern

The part I want in Git is the answer to this question:

Where does this project get LOCALSTACK_AUTH_TOKEN?

Envilder reads that answer from a JSON mapping and retrieves the value from AWS SSM Parameter Store or Azure Key Vault. It can then either start a command with the secret in its environment (exec mode) or generate a local .env file (pull mode).

Same tool, same mapping, two ways to deliver the value.

For starting LocalStack, I now prefer exec mode. No need to create a file just so another process can read it.

Choose where the token lives

Pick one of these configurations for your envilder.json. You don't need both clouds.

With 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"
}

Store your token at that parameter path as a SecureString, and give your AWS identity permission to read it.

With Azure Key Vault:

{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-development-vault.vault.azure.net"
  },
  "LOCALSTACK_AUTH_TOKEN": "localstack-auth-token"
}

Store the token as a secret named localstack-auth-token in that vault. For local development, Envilder can use your az login session, provided your identity has permission to read the secret.

In both cases, the mapping contains a reference, not the credential. That's what goes into Git. You'll also need Docker Compose and Node.js 22.12+; the setup guide covers authentication.

One important detail: Developer Auth Tokens are personal. Each developer must resolve their own token, for example through separate accounts or vaults, or a per-user mapping. CI needs a separate CI Auth Token. A shared setup must not become a shared personal credential.

Let Compose do the rest

Here's a minimal compose.yaml for LocalStack for AWS:

services:
  localstack:
    image: localstack/localstack:stable
    ports:
      - "127.0.0.1:4566:4566"
    environment:
      LOCALSTACK_AUTH_TOKEN: "${LOCALSTACK_AUTH_TOKEN:?Start Compose through envilder exec}"

Then run:

npx envilder exec -- docker compose up -d

That command works with either mapping above.

Envilder resolves the token and starts Docker Compose with it in the process environment. Compose interpolates the variable and passes it to LocalStack.

No manual export. No .env generated by Envilder. And if the secret is missing, empty, or unreadable, exec mode refuses to start Compose rather than hoping for the best.

This is a minimal startup example. Add service-specific ports or Docker socket access only when your workload needs them, and pin a tested image version for reproducible CI runs.

And LocalStack for Azure?

For the same basic setup, replace the image with:

image: localstack/localstack-azure:latest

LocalStack for Azure also uses LOCALSTACK_AUTH_TOKEN and port 4566 by default. The same token can activate either emulator when your account has the corresponding access. At the time of this update, Azure is in private preview and requires access to be enabled.

Where you store the token and which emulator you run are independent choices. Azure Key Vault can supply the token for LocalStack for AWS. AWS SSM can supply it for LocalStack for Azure.

Just use a real cloud secret store for this bootstrap credential. Asking an emulated Key Vault for the token needed to start that same emulator is a chicken-and-egg problem.

Still need a .env file?

The original approach remains available:

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

Add .env to .gitignore. Use this when a tool genuinely needs a file; otherwise, exec mode saves a step and avoids another plaintext copy.

When switching, remove any old secret-bearing .env you no longer need. Exec mode doesn't delete it, and Compose can still load it independently.

What this does not protect

No generated .env does not mean the token never touches disk.

Docker retains container environment variables in its configuration metadata. Someone with sufficient Docker access can read them through docker inspect. Likewise, docker compose config can print resolved values, so don't paste its output into a public issue without checking it.

The command you start, and its child processes, can also read the injected secrets. Exec mode is not a sandbox, and it resolves values once at startup rather than continuously refreshing them.

The improvement is specific: one fewer plaintext secret file in the working directory. Useful, but not magic.

The slightly meta part

I originally ran into this while working on Envilder's integration tests.

Envilder uses LocalStack. LocalStack needs a token. So I used Envilder to resolve the token needed to start the LocalStack environment used to test Envilder.

At that point, the meme was unavoidable.

Originally, that meant generating a .env file. Exec mode now offers another way to deliver the same secret without changing the mapping.

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

Why not lstk, direnv, 1Password, or chamber?

For running LocalStack by itself, I'd start with lstk. It handles login and normally stores the token in the system keyring. You don't need to add a cloud secret store just to try LocalStack.

There are good options for larger workflows too. direnv can run your secret-retrieval commands when you enter a directory. 1Password op run injects secrets from 1Password. chamber already handles AWS SSM and command execution.

Envilder isn't claiming to have invented environment injection.

What I'm building around is the explicit variable name -> secret path mapping: one JSON contract format shared by the CLI, GitHub Action, and .NET, Python, and Node.js SDKs, using AWS SSM or Azure Key Vault.

If a small script already solves your problem, keep it. The contract becomes useful when you would otherwise maintain the same mapping in several different places.

Takeaway

The original goal was to keep the token out of Git. Exec mode goes a little further: I no longer need to generate a local .env just to hand that token to Docker Compose.

The secret stays managed in my cloud provider. The repository describes where to find it. LocalStack receives the variable it already expects.

That's why I'm building Envilder: not to create another place to store secrets, but to make resolving them explicit and repeatable.

How are you handling this in your own projects? I'd be interested in hearing where your setup differs, especially where this approach wouldn't fit.

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 now needs an auth token: getting it into Testcontainers without a .env file

The contract

TypeScript

Python

.NET

Same pattern, different orchestrator: .NET Aspire

Why not just call SSM directly?

The recursion

CI

Try it

Where this came from

Takeaway

Links

LocalStack now requires an auth token: keeping it out of Git with Docker Compose

How I run LocalStack without committing LOCALSTACK_AUTH_TOKEN

The pattern

Choose where the token lives

Let Compose do the rest

And LocalStack for Azure?

Still need a .env file?

What this does not protect

The slightly meta part

Why not lstk, direnv, 1Password, or chamber?

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

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