AWS Workload Credentials Provider: a localhost cache for Secrets Manager and ACM

The problem: every process calling Secrets Manager directly

If ten processes on one EC2 instance each call Secrets Manager at startup, that is ten API calls, ten sets of retry logic, and ten places where credentials handling can go wrong. The Workload Credentials Provider replaces that pattern with a single local agent. Applications read from localhost over HTTP instead of calling AWS directly, and the agent holds the values in memory. It only reads secrets; the README is explicit that it cannot modify them.

The intended audience is teams running the same workload shape across several compute environments. The README lists AWS Lambda, Amazon ECS, Amazon EKS and Amazon EC2 for the Secrets Manager capability, and Amazon EC2 and on-premise hosts for certificate management. The second capability is the reason the project was renamed: it exports certificates from AWS Certificate Manager as PEM files to the local filesystem, which is useful when a web server on the host expects a file path rather than an API call. The README names NGINX and Apache as the web servers it works with.

How the agent works: in-memory cache, TTL refresh, no invalidation

The agent uses the AWS credentials present in its environment to call Secrets Manager. Values are cached in memory and returned in the same format as the GetSecretValue response. The cache is not encrypted, and it is lost when the agent restarts.

Refresh is lazy rather than scheduled. The README states the refresh happens when you try to read a secret after the TTL has expired, and the default TTL is 300 seconds. There is no cache invalidation, so a secret that rotates before its entry expires may be returned stale. That is the single most important operational property of this project, and it should drive your TTL choice more than any performance consideration.

The README also documents two features that address specific gaps. A refreshNow parameter lets a caller force a fresh read for a given request rather than waiting for the TTL. Pre-fetching is documented as a way to populate the cache ahead of first use. Role chaining is documented for cross-account access, where the agent assumes a configured role before calling ACM.

Two security properties are stated in the README. The agent offers protection against Server Side Request Forgery, and it uses the post-quantum ML-KEM key exchange as the highest-priority key exchange by default. The repository layout matches the two capabilities: separate crates for aws_secretsmanager_provider, aws_secretsmanager_caching, and aws_certificatemanager_provider, with aws_workload_credentials_provider as the binary and a common crate underneath.

Installing it and making a first secret request

The README documents both a quick install script and a build-from-source path. The quick install uses install.sh on Linux and install.ps1 on Windows. If you prefer to build, the workspace is a plain Cargo workspace, so a release build produces the aws-workload-credentials-provider binary:

cargo build --release

The repository also ships a Dockerfile for container use. It builds with cargo build --release and copies the binary into a scratch image, with the entrypoint already set to the Secrets Manager subcommand:

FROM rust:alpine as builder
WORKDIR /app
RUN apk add build-base ca-certificates
RUN update-ca-certificates
COPY . .
RUN cargo build --release
FROM scratch
COPY --from=builder /app/target/release/aws-workload-credentials-provider .
ENTRYPOINT [ "./aws-workload-credentials-provider", "sm", "start" ]

To change the default port, TTL, connection limit or cache size, write a TOML configuration file and pass it at startup. The README gives this command line:

sm start --config /path/to/config.toml

Once the agent is running, retrieval is an HTTP GET against localhost. The README documents curl and Python examples for this step. The response body is formatted like a GetSecretValue response, so existing parsing code should transfer. If you need a value that may have rotated, append the refreshNow parameter to the request rather than restarting the agent.

Certificate export and the elevated permissions it requires

The certificate capability is opt-in through configuration, not enabled by default. The agent assumes the role configured for each certificate, calls ACM to export it, and writes a PEM file to the local filesystem. It checks for updated certificates every 24 hours and can run a user-configured command after each successful refresh, which is how you would reload NGINX or Apache.

Each certificate runs as an independent background task, so one certificate failing does not stop the others. The README caps this at 50 certificates.

The cost of this capability is privilege. Writing certificate files and executing refresh commands requires elevated permissions, and the README says the install script configures them automatically and is the recommended setup path. If you must manage permissions yourself on Linux, the documented escape hatches are the --no-privileges and --no-sudoers flags, and the README advises using those rather than bypassing the install script entirely. On Windows the configuration flag is spelled differently depending on how you invoke it: -Config for the PowerShell scripts and --Config for the binary. Reloading a configuration re-applies permissions and restarts the ACM service, so a config change is not a no-op.

Where this is the wrong tool

The absence of cache invalidation is a real boundary, not a footnote. If your secrets rotate on a schedule shorter than your TTL, the agent can serve a value that is no longer valid, and nothing in the README describes a push notification or event that would clear an entry early. Lowering the TTL reduces the window but increases calls to Secrets Manager, which erodes the reason to run the agent at all. If your application needs a secret immediately after rotation with no window of staleness, call Secrets Manager directly or read from a store that pushes updates.

The in-memory cache is also unencrypted and process-local. Restarting the agent empties it, so a cold start means a burst of upstream calls. There is no documented persistence layer to fall back on.

Finally, the certificate capability is scoped to Linux and Windows on EC2 or on-premise hosts. The README does not claim support for other platforms, and the elevated permissions requirement makes it a poor fit for hosts where you deliberately keep the application process unprivileged.

How it compares with calling Secrets Manager directly or using SSM Parameter Store

The direct alternative is the AWS SDK in each application. That approach has no extra process, no local port, and no cache to reason about, and rotation is visible immediately on the next call. What it gives up is the fan-in: every process makes its own calls, and each one needs its own retry and error handling. The Workload Credentials Provider trades that per-process work for one local dependency and a staleness window you control through the TTL.

The other comparison people reach for is SSM Parameter Store, which is a different service with different pricing and limits, and the README does not discuss it. The relevant distinction for this project is narrower: the agent is a cache and a certificate exporter, not a configuration store. It reads secrets and writes PEM files. It does not give you a general key-value interface, and it does not manage the lifecycle of what it reads.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-02. Releases are versioned and frequent enough to suggest active change: v3.0.0 on 2026-06-10, v3.1.0 on 2026-07-15, and v3.1.1 on 2026-07-21. The rename from AWS Secrets Manager Agent to AWS Workload Credentials Provider happened within this line, so older documentation and search results may use the previous name for the same project.

Upgrading across a major version is the cost to plan for. The v3.0.0 release is a major bump, and the README documents platform-specific flag spellings and an install script that configures permissions, so an upgrade is not just a binary swap. On Linux and Windows, re-running the install path is the documented way to get permissions right, and a config reload re-applies permissions and restarts the ACM service.

The project is licensed under Apache-2.0, with a NOTICE file in the repository root alongside the LICENSE. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also carries notice and attribution obligations, and the NOTICE file exists for that reason. If you redistribute a modified binary, read the licence text and the NOTICE rather than relying on a summary; this is not legal advice.

Editorial conclusion

Adopt it if your applications already run on Lambda, ECS, EKS or EC2 and you want secret reads to stop being per-process API calls, or if you run NGINX or Apache on EC2 or an on-premise host and want ACM certificates refreshed to disk automatically. Do not adopt it if your secrets rotate on a schedule shorter than your TTL, because the README states there is no cache invalidation and a rotated secret can be served stale until the entry expires. Before rollout, verify three things: the port and TTL you set in config.toml, the IAM permissions the install script grants on Linux or Windows, and whether the certificate capability's elevated permissions are acceptable on the host.

Frequently asked questions

Official sources

1. aws/aws-workload-credentials-provider on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases