DEV Community: Marçal Albert Castellví

How I run LocalStack without committing LOCALSTACK_AUTH_TOKEN

Marçal Albert Castellví — 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 Castellví — 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 Castellví — 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