Monosecret | Blog

Claude Code Stores OAuth Tokens in Plaintext

Wed, 02 Sep 2026 00:00:00 GMT

Claude Code’s MCP documentation says authentication tokens are “stored securely”. On Linux, that currently means plaintext JSON protected by file permissions.

I checked Claude Code 2.1.257 after authenticating to several remote MCP servers. The file ~/.claude/.credentials.json had mode 0600, as it should, but it also contained a top-level mcpOAuth object with the access tokens. Here is the shape of one Cloudflare entry, with every credential value redacted:

~/.claude/.credentials.json

{
  "mcpOAuth": {
    "cloudflare-observability|…": {
      "accessToken": "<redacted>",
      "clientId": "<redacted>",
      "discoveryState": "<redacted>",
      "redirectUri": "<redacted>",
      "serverName": "cloudflare-observability",
      "serverUrl": "<redacted>"
    }
  }
}

This matches Anthropic’s credential-management documentation.

macOS: uses the encrypted macOS Keychain, falling back to ~/.claude/.credentials.json when the Keychain is unavailable.
Linux: uses ~/.claude/.credentials.json with mode 0600.
Windows: uses %USERPROFILE%\.claude\.credentials.json, inheriting the access controls of the user’s profile directory.

That is a much narrower claim than most people hear when a product says a credential is “stored securely.”

OAuth did not solve secret storage

The browser flow makes the secret easy to miss. Run claude mcp login, approve access in the browser, and return to a connected MCP server. Nobody manually created a token, copied it from a dashboard, or pasted it into a configuration file.

But Claude Code still received a credential. It must persist that credential if the connection is to survive a restart.

OAuth is valuable here. Claude Code can discover the authorization server, request specific scopes, complete the authorization-code exchange, refresh an access token, and revoke the grant. Anthropic’s MCP documentation also lets users pin the scopes Claude Code requests.

What OAuth does not specify is a secure local vault.

API tokens can also be scoped, limited to particular resources, assigned an expiry, rotated, and revoked independently. OAuth standardizes delegation and renewal, while avoiding the copy-and-paste ceremony. Those are substantial benefits, but they do not turn the resulting bearer token into something that is safe to leave in plaintext.

Property	OAuth credential	Scoped API token
Must be stored by the client	Yes	Yes
Can have limited permissions	Yes	Yes
Can expire	Yes	Yes
Can be revoked independently	Usually	Yes
Can be replayed if stolen	Yes	Yes
Standard interactive delegation	Yes	Provider-specific
Standard automatic renewal	Often	Usually external

OAuth solves how Claude Code obtains and renews a delegated credential. Secret storage solves what happens to that credential between uses. They are separate concerns.

Claude Code needs a credential-store interface

Claude Code should not decide that every Linux user’s MCP tokens belong in the same plaintext file. The persistence layer should be replaceable:

Claude Code OAuth client
        │
        ▼
credential-store interface
        │
        ▼
Monosecret TypeScript SDK
        │
        ▼
user-selected Monosecret provider

The right integration point is the Monosecret Node.js / TypeScript SDK. It embeds the Rust resolver, so the TypeScript side does not need bespoke code for each backend. Claude Code could serialize one MCP OAuth credential per server and ask Monosecret to load, save, or delete it using the provider the user or organization selected.

Monosecret 0.20 has 33 provider integrations. They cover local keyrings, password managers, encrypted files, cloud secret managers, and deployment destinations. Providers declare their capabilities, so a credential store can require readable and writable storage while still using the same interface everywhere.

The current TypeScript SDK exposes Monosecret’s provider-independent resolver. We would add the small get/set/delete credential-store surface Claude Code needs rather than reimplement 33 integrations in its codebase.

For example, set the system keyring as the default provider in the local user configuration:

$ monosecret config global init --provider keyring --profile default

A team might instead require OpenBao or a cloud secret manager. A headless workstation might use an age-encrypted store. The OAuth flow would stay exactly the same; only persistence would change.

What Codex does: Codex makes MCP OAuth storage configurable. Its configuration reference documents auto, file, and keyring backends. Setting mcp_oauth_credentials_store = "keyring" selects the system keyring. This is not a general secret-provider interface, but it avoids making a plaintext credential file the only option on Linux.

Coming in Monosecret 0.21: We are working on versioned resolver and provider IPC for zero-dependency integrations. Applications will be able to use Monosecret providers over a local protocol without embedding an SDK or provider code.

Making open source software more secure

We are working to make open source tools retrieve credentials from a user-selected secret store instead of copying them into another plaintext file. Monosecret now provides Git and Docker credential helpers, and we have proposed a generic, operation-scoped secret resolver interface for Nix.

Because these projects are open source, we can inspect their credential boundaries and contribute safer ones upstream.

We cannot make the equivalent fix in Claude Code. Its public repository does not include the core CLI implementation, and its license is all rights reserved. We can support the open request for secure, pluggable credential storage and propose a Monosecret TypeScript integration, but only Anthropic can change Claude Code’s MCP OAuth storage today.

That is one of the practical security benefits of open source: when a secret crosses the wrong boundary, users do not have to wait for the vendor to decide that the boundary matters.

We Are Forking dotenvy into dotenv-ng

Sat, 15 Aug 2026 00:00:00 GMT

We have released dotenv-ng 1.0, a modern Rust implementation for loading and rendering .env files. It began as a fork of dotenvy after its parser changed a secret while reading it.

That may sound contradictory. Monosecret is still on a mission to eliminate environment variables as a secrets interface, and we have written about where .env went wrong. It should not be the final home of a secret.

But migrating away from .env starts with reading it correctly.

Why fork dotenvy?

The immediate failure was Monosecret issue #73. A dotenv file contained a value with bcrypt fragments:

TEST="foo:$2a$10$TWoviNHS27HJMw1PKe4tBeIMlms6tWdYS9hKoHANKCQhluDlEt/gu"

The file was intact. Reading it through the dotenv provider returned a different value because dotenvy treated the dollar-prefixed fragments as variable substitutions. The failure appeared later as an authentication error, not a parse error.

An upstream request to make substitution configurable had been open since 2024. A pull request arrived in 2026 but targeted an unreleased API. A migration tool cannot require users to recognize and escape parser syntax inside their secrets.

The maintenance gap

The original Rust dotenv crate stopped releasing in 2020 and was eventually marked unmaintained by RustSec, which listed dotenvy as an alternative.

Dotenvy’s description still calls it “a well-maintained fork.” Its latest published version, 0.15.7, was released on March 22, 2023. A Rust forum discussion noted the two-year release gap in 2025. By the time the bcrypt bug blocked Monosecret, it was more than three years.

There is an uncomfortable irony in a maintained fork repeating its upstream’s release problem. Its maintainers do not owe us a release, but Monosecret needed breaking fixes on a schedule we control.

What does dotenv-ng improve upon?

We first considered a small patch. Auditing the parser uncovered more problems around JSON, Windows paths, Unicode names, precedence, and partial environment mutation.

dotenv-ng therefore starts from dotenvy 0.15.7 but deliberately breaks compatibility where correctness requires it. Version 1.0 adds:

a source-aware parser with structured errors;
literal dollar signs by default, with substitution available only when a caller explicitly enables it;
a broader key grammar that supports dashes, leading digits, leading dots, and Unicode;
a renderer that adds only the quoting and escaping needed to parse a value back unchanged;
validation before process-environment mutation; and
an explicit unsafe boundary around that mutation.

Property tests exercise arbitrary Unicode and syntax-heavy values, check that quoting is used only when necessary, and round-trip complete documents. The parser and renderer, the core of the rewrite, both have 100% line coverage.

The complete compatibility and API changes are recorded in the dotenv-ng 1.0 changelog.

Try dotenv-ng 1.0

The package is available on crates.io. Applications can keep the familiar dotenv crate name with a dependency alias:

[dependencies]
dotenv = { package = "dotenv-ng", version = "1" }

Starting in Monosecret 0.20, dotenv-ng powers dotenv parsing and rendering throughout Monosecret.

Monosecret 0.19: Moving and importing secrets between providers

Tue, 11 Aug 2026 00:00:00 GMT

Secret storage changes as a project grows. Values move from local files to password managers, from one naming convention to another, and sometimes between providers with completely different data models. The application still expects the same API_KEY or DATABASE_URL at the end.

Monosecret 0.19 treats those changes as a normal workflow instead of a one-off migration script.

This release includes:

Provider-specific storage layouts: give each provider its own address, transform stored values, import existing files, and preview exact write references.
Config belongs in secrets: resolve profile-specific config alongside stored secrets, generate ephemeral values, and securely prompt during monosecret run.
Passbolt provider: read and write secrets in a self-hosted Passbolt server, with credentials supplied by another provider when needed.
Faster remote-provider workflows: attach a cache directly to an authoritative provider and batch 1Password field reads.
Smaller improvements: create standalone profiles and install complete pkg-config metadata for native SDK consumers.

Provider-specific storage layouts

API_KEY is the name used by your application. In 1Password, the same value might be the token field of an item named old-api-item.

A ref gives Monosecret this store address. item names the entry. Coordinates such as field, section, and vault locate a value inside structured stores. The providers list still decides which stores to try.

Before 0.19, every provider in a secret’s route received the same ref, even though stores such as 1Password and dotenv organize secrets differently. Now each provider alias can template its usual layout, while refs.<alias> handles exceptions:

monosecret.toml

[providers]
legacy = "onepassword://Legacy"
production = {
  uri = "onepassword://Production",
  ref = { item = "{project}-{profile}", field = "{key}" }
}
local = { uri = "dotenv://.env", ref = { item = "{key}" } }

[profiles.production]
API_KEY = {
  description = "API key",
  providers = ["production", "local"],
  refs = { legacy = { item = "old-api-item", field = "token" } }
}

production reads the API_KEY field from a <project>-production 1Password item. The local fallback reads the dotenv key API_KEY. If legacy is selected explicitly, refs.legacy reads the token field from old-api-item.

For each provider, refs.<alias> takes precedence over the alias’s ref template, which takes precedence over the provider convention. Templates accept {project}, {profile}, and {key} in every address field. Existing route-wide ref declarations remain supported.

Because scoped references also apply to imports, that exception can describe a migration source without joining the normal fallback route:

monosecret import legacy --profile production --delete-source

This reads from refs.legacy and writes through the production template. It also works between distinct entries in one physical store. Monosecret rejects the import if both addresses resolve to the same entry.

Transform stored values

Two new secret fields transform a stored value before it reaches the application.

extract selects a value from JSON with an RFC 6901 JSON Pointer:

monosecret.toml

[providers]
runtime = "file:///run/secrets"

[profiles.production]
DATABASE_PASSWORD = {
  description = "Database password",
  providers = ["runtime"],
  ref = { item = "application.json" },
  extract = { format = "json", pointer = "/database/password" }
}

JSON strings become their unquoted contents. Numbers, booleans, objects, and arrays keep their JSON representation. Extracted declarations are read-only. set, delete, prompting, generation, and import cannot overwrite the source document.

encoding defines the textual representation in provider storage:

monosecret.toml

[profiles.production]
TEXT_CONFIG = { description = "Encoded configuration", encoding = "base64" }
CLIENT_KEYSTORE = {
  description = "Binary client keystore",
  providers = ["runtime"],
  ref = { item = "client.p12.b64" },
  encoding = "base64",
  as_path = true
}

Supported encodings are standard Base64, URL-safe Base64, and hexadecimal. Writes encode the logical value. Reads decode the stored value. Decoded UTF-8 can be returned directly. Set as_path = true to materialize arbitrary bytes in a file.

Transforms run in this order:

provider or cache → encoding decode → JSON extraction → as_path

This allows, for example, one declaration to decode a Base64-encoded JSON document and select one field from it.

Import without reshaping the source

File stores one plaintext UTF-8 file per secret beneath a required root. Convention paths use {project}/{profile}/{key}. ref.item selects an existing relative path, including a file mounted at runtime.

Writes use atomic replacement and create private Unix files and directories. The provider rejects traversal and nested symlinks. It does not encrypt its contents.

The file provider is also a migration adapter for directories that already contain one file per secret. A provider ref template maps the source layout, while the destination alias independently maps the same declarations into its native store:

monosecret.toml

[providers]
legacy_files = {
  uri = "file:./old-secrets",
  ref = { item = "{profile}/{key}" }
}
production = {
  uri = "onepassword://Production",
  ref = { item = "{project}-{profile}", field = "{key}" }
}

[profiles.production.defaults]
providers = ["production"]

[profiles.production]
API_KEY = { description = "Production API key" }

monosecret import legacy_files --profile production --delete-source

For API_KEY, the source is old-secrets/production/API_KEY. The destination is the API_KEY field in the <project>-production 1Password item. The source files do not need to follow the Monosecret convention. With --delete-source, 0.19 preflights every mapped source and destination, verifies every copied value, and only then removes the plaintext source files.

Preflight, write, or verification failures leave every source untouched. A destination with a different existing value keeps its corresponding source.

See the reference before writing

monosecret set and interactive monosecret check now print the resolved write reference before reading a value:

$ monosecret set API_KEY --profile production --provider sops://secrets.enc.yaml
Writing secret 'API_KEY' to sops://secrets.enc.yaml?format=yaml (profile: production)
  target: /work/my-app/secrets.enc.yaml ["my-app"]["production"]["API_KEY"]
Enter value for API_KEY (profile: production): ********

SOPS reports the canonical encrypted file and exact sops set selector. Other providers report their native item or path. A missing profile or unexpected template is visible before Monosecret receives the new value.

Config belongs in secrets

Null always reports a missing value and stores nothing. This lets manifest defaults provide non-sensitive values without adding a storage backend. One resolution can now return profile-specific configuration and provider-backed secrets together. This follows the separation described in Secrets Don’t Belong in Config.

monosecret.toml

[profiles.default]
APP_MODE = { description = "Application mode", default = "local", providers = [
  "null",
] }

[profiles.staging]
APP_MODE = { default = "staging" }

[profiles.production]
APP_MODE = { default = "production" }

APP_MODE resolves to local, staging, or production based on the selected profile. Each override inherits the description and null route from [profiles.default]. Only the value is repeated.

The result is one declaration model for values the application needs, whether they come from a secret store or directly from the manifest. Config can travel through the same profile, scope, SDK, and run workflow without pretending it needs encrypted persistence.

Ephemeral values

The null provider can also generate a fresh value for each resolution. Use it for session tokens, test credentials, and other values that should exist only for one process invocation. Persistent credentials should continue to use a writable provider.

Prompt for missing secrets during run

Set prompt = true on a declaration to let monosecret run securely request its value when the configured providers do not have one:

monosecret.toml

[profiles.default]
DEPLOY_PASSWORD = {
  description = "One-time deployment password",
  prompt = true,
  providers = ["null"]
}

$ monosecret run -- ./deploy
? Enter value for DEPLOY_PASSWORD (profile: default):

A writable provider saves the answer, turning the prompt into first-use provisioning. The null provider keeps it ephemeral and injects it only into that invocation. The hidden prompt reads from the controlling terminal, so the child’s stdin remains available for pipes and redirects. If no controlling terminal exists, run fails before starting the child. Declarations without prompt = true retain the existing fail-on-missing behavior.

Passbolt provider

Passbolt is the third new provider in 0.19. Monosecret now has 27 providers.

Passbolt reads and writes resources in a self-hosted Passbolt server through go-passbolt-cli. Convention values use the resource monosecret/{project}/{profile}/{key} and its password field. References can select existing resources by UUID or exact name and address the password, username, uri, or description field.

monosecret.toml

[providers]
bootstrap = "keyring://"

[providers.passbolt_team]
uri = "passbolt://?server=https://pass.example.com&folder=a9230ec4-5507-4870-b8b5-b3f500587e4c"
credentials = { private_key = "bootstrap", passphrase = "bootstrap" }

The OpenPGP private key and passphrase can come from another Monosecret provider. Environment fallbacks and the Passbolt CLI configuration are also supported. Folder-scoped providers support declaration discovery with init --from.

Faster remote-provider workflows

Remote secret reads pay for authentication, process startup, and network round-trips before the application can start. Monosecret 0.19 reduces that work both across invocations and within one resolution.

Cache one authoritative provider

A single authoritative provider can now define uri, credentials, and cache on the same alias:

monosecret.toml

[providers]
local = "keyring://monosecret/cache/{project}/{profile}/{key}"
azure = {
  uri = "akv://team-vault",
  credentials = { client_secret = "keyring" },
  cache = { provider = "local", max_age = "8h" }
}

[profiles.development.defaults]
providers = ["azure"]

The cached fallback form introduced in 0.17 remains available when several authoritative providers can answer.

Cache entries now include their absolute expiration time and originating max_age. Monosecret removes an expired entry whenever it encounters one, and changing max_age invalidates entries written under the previous policy.

Fallback resolution also reuses provider instances and handles independent primary misses concurrently. Azure Key Vault reuses its client and serializes initial challenge-based authentication, avoiding repeated Azure CLI processes within one resolution.

Batch 1Password field reads

1Password field references now resolve together through one op inject call, instead of starting op read separately for every field. This reduces CLI startup and repeated unlock overhead when one profile loads several fields. If the batch contains a missing reference, Monosecret falls back to bounded concurrent reads so it can preserve per-secret missing-value behavior without serializing the whole profile.

In the cold-cache benchmark from the implementation PR, a representative profile with 25 field references resolved in 11.890 seconds, down from 96.294 seconds. The batch used 3 op processes instead of 27, making that run 8.10 times faster.

Smaller improvements

Standalone profiles

Profiles inherit [profiles.default] unless their defaults set inherit = false:

monosecret.toml

[profiles.default]
DEV_DATABASE_URL = { description = "Developer database" }
LOCAL_DEBUG_TOKEN = { description = "Local debugging token", required = false }

[profiles.production.defaults]
inherit = false
providers = ["vault://vault.example.com:8200/secret"]

[profiles.production]
DATABASE_URL = { description = "Production database" }
API_KEY = { description = "Production API key" }

production contains only its own declarations and fields. Other profiles in the same manifest can continue to inherit the default profile.

pkg-config metadata for monosecret_ffi

cargo cinstall -p monosecret_ffi now installs the library, C header, and a monosecret_ffi.pc file containing the complete link metadata. Go builds can use the pkgconfig tag, Ruby native extensions accept --enable-pkg-config, and Haskell builds use the use-pkg-config Cabal flag. The same metadata supports installed static or shared libraries.

Haskell now declares its required macOS system frameworks. The Rust SDK’s ProviderAlias type also exposes leaf, credentials, and credentials_mut helpers for configuration tooling.

Upgrading

cargo install monosecret

Existing route-wide ref declarations, inheriting profiles, and cached fallback aliases remain compatible. All new configuration fields and providers are opt-in.

0.19 also:

fixes concurrent keyring initialization.
preserves non-UTF-8 environment values in run on Unix.
renders SOPS path templates in one pass and validates deserialized path templates.
preserves complete multi-segment LastPass templates in route comparisons.
refreshes fallback providers when a Rust Secrets instance is reused.
adds Secrets::resolve_named for resolving one secret without unrelated missing requirements.
rejects credentials embedded in provider URIs. Use alias credentials or provider environment variables instead.

See the full changelog for every change and fix in this release.

Future work

These items are not part of 0.19. They are open work for future releases:

Native Windows ARM64 CLI archive (target: 0.19.1): add monosecret-aarch64-pc-windows-msvc.zip and its checksum to GitHub Releases so the CLI can run natively on Windows ARM64. The static installer will continue to select the x64 build on Windows ARM devices until it supports the native archive, and standalone updates depend on axoupdater supporting Windows ARM64.
WinGet packaging: publish the initial package tracked in microsoft/winget-pkgs#413776, then automate stable updates through Monosecret #297.
Notification and approval integrations: send new secret access requests to services such as email, Slack, or WhatsApp for approval.
JVM SDK: expose the shared Monosecret resolver to Java, Kotlin, and other JVM languages.
Dart SDK: bring the shared resolver to Dart and Flutter applications.

Every team has a secrets story. Come tell us yours on Discord.

Where .env Went Wrong

Thu, 30 Jul 2026 00:00:00 GMT

.env is one of software’s most successful accidents.

It starts as a shortcut for three export commands. Then it becomes the project’s configuration schema, secret store, environment model, onboarding guide, CI interface, and deployment format.

Environment variables do one job well: deliver strings to a process. .env turned that delivery mechanism into a source of truth.

A convenience became architecture. That is where .env went wrong.

Environment variables only deliver values

Environment variables solve a small problem: getting values into a running process. The application can read DATABASE_URL without knowing whether a developer, CI system, or secrets manager supplied it.

A .env file makes those values easy to save and reload. That is useful. But teams also use the file to describe what the application needs. KEY=value cannot say whether a value is required, secret, safe to commit, available only in production, or restricted to one service.

Those requirements outlive any process and any developer laptop. They belong in a durable project declaration. .env stores values for delivery; it cannot define the application’s secret model.

A string is not a schema

Consider a typical example file:

.env.example

DATABASE_URL=
REDIS_URL=redis://localhost:6379
STRIPE_API_KEY=
DEBUG=false

The file raises more questions than it answers. Does an empty value mean required or optional? Is REDIS_URL a development default? Is STRIPE_API_KEY production-only? Is DEBUG a boolean?

Dotenv cannot encode those answers. Node.js documents that every value becomes a string. A dotenv issue about booleans, opened in 2015, still collects reactions from developers surprised that "false" is truthy.

Teams put the missing information elsewhere: validation code, a README, .env.example, or a teammate’s memory. These sources drift.

The file also makes DEBUG and STRIPE_API_KEY look equivalent. One is an ordinary setting that belongs in Git. The other grants authority and needs access control and rotation. Mixing them makes the whole file sensitive.

Without an explicit declaration, missing values fail late: the application discovers them only when code tries to use them.

Then the file starts to multiply

A new requirement usually creates another file:

.env
.env.local
.env.development
.env.development.local
.env.test
.env.production

The filenames become an environment model. Suffixes define scope, load order defines inheritance, and copying a file becomes deployment.

This reverses the Twelve-Factor App’s guidance. Its point was that environment variables should be independent controls because named environments become brittle as deployments multiply. .env.production recreates that grouping in a filename.

Now every new value must be added to .env.example, documented in a README, validated in code, and copied into the right real files. Miss one and the environments drift.

There is no `.env` spec

.env looks standardized, but every parser defines its own format. Node.js documents the lack of a formal specification, as does python-dotenv. Each loader makes its own choices.

python-dotenv expands ${NAME} but not $NAME. Node dotenv delegates variable expansion to another tool. Docker Compose supports its own shell-style operators. Vite even supports references in reverse order, then warns that the same expression will not work in a shell or Docker Compose.

Comments and quotes differ too. Node dotenv changed the meaning of # in unquoted values in version 15 as a breaking change. One devenv user found that quotes became part of an exported key.

Which value wins?

Parsers also disagree about precedence. Node dotenv normally lets the first file win. Docker Compose lets the last env_file win, then lets the environment section override that. Vite gives an existing process variable priority over its files.

Docker Compose gives two similar names different behavior. env_file: supplies variables to a container but does not use them to interpolate compose.yaml. docker compose --env-file does affect interpolation. In an issue closed as working as designed, a maintainer described the option’s name as unfortunately chosen.

Who loaded `.env` first?

Precedence also depends on timing. Node dotenv’s ES module guidance needs special handling when imported modules read the environment during initialization. Vite warns that Bun’s automatic .env loading can interfere with Vite’s own loading order. VITE_* values are replaced at build time and become part of the client bundle.

The same line can become a runtime secret, a build-time constant, or a public browser value. The loader decides based on timing and context.

At that point .env behaves like a small program, with control flow spread across filenames, flags, working directories, parent processes, and library versions.

An ignored file is still a file

The dotenv project says not to commit .env. .gitignore prevents one accident. It does not add encryption, access control, auditing, or revocation.

The file can still end up in editor backups, chat messages, archives, support bundles, container build contexts, and old laptops. A devenv integration was reported to copy .env contents into the Nix store, where paths are not confidential. When a developer leaves, there is no file access to revoke. Each credential they received is a separate copy.

Even a secret stored in 1Password, Vault, a cloud secret manager, or a system keyring must be copied into plaintext before a dotenv-based application can use it. The local copy has fewer controls than the original.

Environment-variable delivery has limits too. Docker mounts managed secrets as files because environment variables can leak between containers. A process also gets one global map, so a frontend build, worker, migration, and web service often receive the same secrets even when each needs only a few. Dotenv has no way to express that scope.

Let `.env` become small again

The useful part of .env is the short path from “this application needs a value” to “the application can run.”

Keep it as an adapter for tools that expect KEY=value, or use it for ordinary local settings. Do not make it define the project’s requirements, store durable copies of secrets, encode environments in filenames, or decide which services receive which values.

A durable design separates three jobs:

a committed declaration says which secrets the application needs;
protected storage controls who can read their values;
explicit delivery gives each process only the values it needs.

Each piece can then change independently. A team can change storage without rewriting the application, validate requirements before startup, and limit each component to its own secrets.

How Monosecret applies this

Monosecret puts the declaration in a file that is safe to commit:

monosecret.toml

[project]
name = "payments"
revision = "1.0"

[profiles.default]
DATABASE_URL = { description = "Postgres connection string" }
REDIS_URL = { description = "Redis connection string", required = false }
STRIPE_API_KEY = { description = "Stripe API key" }

[profiles.development]
REDIS_URL = { default = "redis://localhost:6379" }

This file records requirements, defaults, and descriptions without containing secret values. Providers choose where values live, and profiles describe real differences in requirements.

Existing programs can adopt Monosecret without code changes:

$ monosecret run -- ./server

This command injects resolved secrets into the child process environment. It is useful during migration, while the preferred integration is a Monosecret SDK.

With an SDK, the application resolves its declaration directly. This removes the environment-variable handoff used by monosecret run. Values stored in a keyring, password manager, or Vault never enter the global process environment. Applications that require a file can receive a temporary file instead. Scopes (0.2+) let each component resolve only the secrets it declares.

Migration can be gradual. Monosecret initializes a declaration from an existing file:

$ monosecret init --from dotenv:.env

This copies names without copying values. The current file can remain a provider during the transition:

$ monosecret check --provider dotenv:.env

$ monosecret run --provider dotenv:.env -- ./server

Values can then move to a system keyring, password manager, Vault, or another provider without changing the names the application reads.

.env can remain for ordinary local settings. Existing applications can keep environment-variable delivery while they migrate. Applications using an SDK or file-based delivery can remove secrets from their process environments.

Monosecret aims to eliminate environment variables for secrets altogether.

But I Use SOPS

Thu, 23 Jul 2026 00:00:00 GMT

Whenever I show someone Monosecret, I often hear the same response:

But I use SOPS.

SOPS is good. It encrypts files so they can live in Git without exposing their plaintext values.

But Monosecret solves a different problem: how applications declare, find, and consume secrets.

How does your application use the secret?

Once you have encrypted secrets.yaml, how does your Python service consume it? What about your Go worker or Node.js app?

You still need to decrypt the file, inject its values, select the right file for each environment, validate required keys, and repeat that integration for every language.

And if you release the project as open source, that choice does not stay yours. With SOPS baked into the setup, everyone who runs or contributes to the project must adopt SOPS and its key management, whatever secrets tooling they already use.

Monosecret starts at the other end. The project declares what the application needs without storing any values:

monosecret.toml

[project]
name = "payments"
revision = "1.0"

[profiles.default]
DATABASE_URL = { description = "Postgres connection string" }
STRIPE_API_KEY = { description = "Stripe secret key" }

The same secret can come from a developer’s system keyring or CI environment variables, while a more sensitive production environment resolves it from Vault. Applications use the same declaration through nine SDKs for Rust, Python, Go, Ruby, Node.js/TypeScript, Haskell, PHP, C#, and Swift (0.2+) without knowing the provider.

Encrypted files also make the key workflow a project-wide requirement. Adding a teammate means adding their key to .sops.yaml and re-encrypting every file; removing one means rekeying and rotating the affected secrets, since their key already saw the plaintext. Monosecret leaves identity and access to the provider: onboarding to Vault or a cloud secrets manager is granting a role, and offboarding is revoking it.

SOPS may be enough today. As your team grows more sensitive to how secrets are handled, you may want Vault’s access policies and centralized audit trail. If applications know about SOPS, each one needs migrating. If they know only Monosecret, you change the provider configuration; SDK calls and secret names stay the same.

The same resolver provides profiles, required-secret checks, per-secret provider routing and fallback, provider-native references, temporary files, and metadata-only audit logs. You build the integration once, not once per provider and language.

Different layers, different jobs

SOPS protects a file. Monosecret gives applications a provider-independent interface. The selected provider remains responsible for storage, encryption, identity, access control, and availability.

I wrote a fuller Monosecret comparison showing exactly where Monosecret ends, where providers begin, and which responsibilities belong to each layer.

Where Monosecret goes next

Because applications talk to an interface instead of a file, the interface can grow without touching them. Three open proposals point where it is heading:

Project security requirements would let a project declare the guarantees a provider must meet, such as encryption at rest or an audit trail, and reject providers that fall short.
Lease-aware refresh would let running applications follow key rotation and short-lived credentials instead of restarting for a new value.
The SOPS provider (0.2+) brings SOPS itself behind the same SDK interface, making your encrypted files one more place secrets can come from.

With that provider, perhaps “But I use SOPS” just needs two more words:

But I use SOPS with Monosecret.

If encrypted files fit your workflow, keep using SOPS. Just recognize the boundary: encryption at rest is not an application secrets interface.

Secrets Don’t Belong in Config

Mon, 20 Jul 2026 00:00:00 GMT

Applications should not require passwords, API keys, or tokens in their configuration files.

Configuration describes behavior. It belongs in git, code review, bug reports, and developer machines.

A secret grants authority. It needs restricted access and independent rotation.

Putting both in one file couples different lifecycles and audiences. If rotating a password requires regenerating application configuration, the interface has coupled them too tightly.

NixOS contains 110 workarounds for this

We audited all 445 NixOS modules that handle a real secret in nixpkgs at commit 141f212, classifying each by where its secret value ends up.

Where the secret value ends up	Modules	Share
Merged into a config file at runtime	110	25%
Inlined into a config in `/nix/store`	42	9%
Delivered as an environment variable	161	36%
Left in a dedicated file opened by the app	58	13%
Loaded through systemd credentials	53	12%
Passed as a command-line argument	19	4%
Classification uncertain	2	—

The interesting number is 110. A quarter of the modules retrieve a secret safely, then copy it into configuration because that is the only interface the application accepts.

These modules use envsubst, replace-secret, jq, yq, sed, or custom code to assemble a restricted file at startup. The result can be secure, but every module now owns application-specific, security-sensitive glue just to combine two inputs that should have remained separate.

This is not unique to NixOS. The same workaround appears as an entrypoint script, Helm template, init container, or CI interpolation step on other platforms.

As a side note, 42 modules can inline secrets into the world-readable /nix/store. That direct security problem is tracked in nixpkgs issue #24288. The 110 runtime mergers make the broader point: even when deployment authors avoid the leak, the missing separation still creates work.

Give secrets their own interface

Applications should accept secret values through a dedicated runtime channel, such as:

a password_file or token_file setting;
a systemd credential;
a narrowly scoped environment variable;
or an external secret provider.

These mechanisms are not equally safe: environment variables can be inherited, arguments can appear in process listings, and files still need correct permissions. What separation does guarantee is that the deployer no longer has to manufacture a second, secret-bearing version of the configuration.

The principle is simple; implementing it across environments is not. Local development might use a system keyring, CI environment variables, and production 1Password or Vault. Without a shared abstraction, each environment needs its own naming, lookup, validation, and injection glue.

How I got it wrong in Cachix

Cachix historically stored its auth token and per-cache signing keys in ~/.config/cachix/cachix.dhall, alongside cache names and other configuration. It was convenient, but the file had to be treated as a secret even though much of it was ordinary configuration.

A typical file mixed them directly:

~/.config/cachix/cachix.dhall

{ authToken = "XXX-AUTH-TOKEN"
, binaryCaches =
    [ { name = "mycache"
      , secretKey = "XXX-SIGNING-KEY"
      }
    ]
}

The cache name is configuration; the auth token and signing key are secrets. You could not share the cache configuration without also sharing credentials.

devenv 2.2 separates the token through its declarative secrets integration. The project declares CACHIX_AUTH_TOKEN, devenv resolves it from the configured provider, and the value is passed to Cachix without being added to devenv’s configuration.

Cachix PR #737 brings the same boundary into the client through the Monosecret Haskell SDK. It resolves CACHIX_AUTH_TOKEN and CACHIX_SIGNING_KEY from Monosecret and can store them in the user’s chosen provider instead of cachix.dhall. Existing environment variables and config files remain higher-priority fallbacks for compatibility. The PR is still open.

That is the problem Monosecret is designed to solve: configuration declares the requirement, while each environment chooses where the value lives.

Declare once, resolve anywhere

Monosecret applies that separation by making monosecret.toml a declaration of what an application needs, without storing the values:

monosecret.toml

[project]
name = "myapp"

[profiles.production]
DATABASE_URL = { description = "Postgres connection string" }
STRIPE_API_KEY = { description = "Stripe secret key" }

Providers decide where the values live. A developer can use the system keyring, CI can use environment variables, and production can use 1Password, Vault/OpenBao, or a cloud secret manager without changing the declaration.

An existing application can receive the resolved values at startup:

$ monosecret run -- ./myapp

Applications can also resolve them directly through the Monosecret SDKs for Rust, Python, Go, Ruby, Node.js/TypeScript, Haskell, PHP, C#, and Swift (0.2+), all sharing the same resolver so behavior stays consistent across languages.

Providers own where secret values come from. SDKs give applications an idiomatic way to consume them. Configuration remains a shareable declaration of what is required.

Making the boundary practical

If you maintain an application, stop adding passwords and tokens to ordinary configuration schemas. Accept a file reference, credential, environment variable, or provider instead.

For NixOS, Monosecret issue #65 tracks how an official integration could declare and resolve secrets without per-module substitution glue.

Consistent secret handling across developer machines, CI, and production used to require infrastructure that only dedicated platform teams could build. A project of any size should be able to separate secrets from configuration without building its own secrets platform first.

Monosecret 0.12: audit logs and coding agents

Mon, 08 Jun 2026 00:00:00 GMT

A coding agent reaches for the same secrets you do, but on its own initiative and many times a session: a read looks identical whether it came from you running a deploy or an agent exploring the codebase.

Monosecret 0.12 makes that access accountable. It ships three things:

Audit log — every secret read and write is appended to a local, per-user JSONL log. On by default. Values are never recorded.
Reason-on-access — secret access can require a human-readable reason, enforced for coding agents by default.
monosecret audit command — filter and summarize the log, or pipe raw JSON Lines to jq.

The audit log

Every secret read and write, from the CLI and the Rust SDK, is appended to a local log as JSON Lines, one event per line. Secret values are never written, only metadata: the secret name, the profile, the provider that served it (with any embedded credentials redacted), the outcome, the reason, and who was asking, including the detected coding agent.

{
  "v": 1,
  "ts": "2026-06-04T17:04:00.893Z",
  "action": "get",
  "project": "my-app",
  "profile": "production",
  "key": "DATABASE_URL",
  "provider": "keyring://",
  "outcome": "found",
  "reason": "deploy web frontend",
  "actor": { "user": "alice", "agent": "claude-code", "is_agent": true },
  "version": "0.12.0"
}

The log lives in your per-user state directory (~/.local/state/monosecret/audit.log) and is created readable only by you. Read it with any tool, or use the new monosecret audit command for filtering and a readable summary:

# Last 20 entries, formatted
monosecret audit -n 20

# Only `run` events for one project
monosecret audit --project my-app --action run

# Raw JSON Lines, piped to jq
monosecret audit --json | jq 'select(.outcome == "missing")'

It is configured in your user-global config (~/.config/monosecret/config.toml), not the project’s monosecret.toml, so a repository you clone can’t quietly turn off or redirect your audit log. The log is a single file capped at 1 MiB, a size-bounded recent record rather than permanent compliance history; forward it to a central system if you need that. To turn it off entirely:

~/.config/monosecret/config.toml

[audit]
enabled = false

See Audit Logging for the full record schema and options.

Supplying a reason

When a coding agent like Claude Code reaches for a secret without a reason, the access is refused and the agent is told exactly what to do next:

$ monosecret run -- npm test
Error: Accessing secrets requires a reason. Provide one with --reason
"<why you are accessing these secrets>", the MONOSECRET_REASON environment
variable, or Secrets::with_reason() in the SDK. (Policy: require_reason in
[project] of monosecret.toml — defaults to "agents"; set it to false to
disable.)

Claude Code reads that message, states why it needs the secret, and retries:

monosecret run --reason "run the test suite before opening a PR" -- npm test

Both the refusal and the successful retry land in the audit log, so the reason is tied to the access. There are three ways to supply a reason:

Source	Scope	Precedence
`--reason` flag	CLI	highest
`Secrets::with_reason()`	SDK	overrides env
`MONOSECRET_REASON`	CLI + SDK + derive	lowest

# CLI: the most explicit option, overrides the others
monosecret run --reason "deploying release 0.12" -- ./deploy.sh

// SDK: the programmatic equivalent of --reason
let secrets = Secrets::load(/* ... */)?.with_reason("nightly backup job");

# Env: lowest precedence, but honored everywhere
export MONOSECRET_REASON="nightly backup job"

MONOSECRET_REASON is resolved by Secrets::load / load_from, which means monosecret_derive-generated code and other library callers satisfy the policy and supply an audit reason without any code changes.

Whichever path you use, blank or whitespace-only reasons are ignored, so they can’t quietly satisfy the policy. Under the hood this is backed by a new Provider::set_reason trait method (a no-op by default), so existing providers keep working unchanged.

Configuring when a reason is required

The new require_reason policy in the [project] table controls when a reason is mandatory:

[project]
name = "my-app"
require_reason = "agents" # require it from agents (default), or true / false

"agents" (the default): require a reason only when a coding agent is detected.
true: require it from every caller.
false: never require it.

Because the policy lives in monosecret.toml and is enforced by Monosecret, it applies to everyone and every CI runner, and is inherited through extends. Coding agents are spotted by the detect-coding-agent crate (Claude Code, Cursor, Codex, Gemini CLI, Copilot, and more); set MONOSECRET_AGENT for a harness it doesn’t recognize.

Upgrading

cargo install monosecret

Remember the new default: agents must pass a reason: set require_reason = false to opt out.

Questions or feedback? Join us on Discord.

Monosecret | Blog

Claude Code Stores OAuth Tokens in Plaintext

OAuth did not solve secret storage

Claude Code needs a credential-store interface

Making open source software more secure

We Are Forking dotenvy into dotenv-ng

Why fork dotenvy?

The maintenance gap

What does dotenv-ng improve upon?

Try dotenv-ng 1.0

Monosecret 0.19: Moving and importing secrets between providers

Provider-specific storage layouts

Transform stored values

Import without reshaping the source

See the reference before writing

Config belongs in secrets

Ephemeral values

Prompt for missing secrets during run

Passbolt provider

Faster remote-provider workflows

Cache one authoritative provider

Batch 1Password field reads

Smaller improvements

Standalone profiles

pkg-config metadata for monosecret_ffi

Upgrading

Future work

Where .env Went Wrong

Environment variables only deliver values

A string is not a schema

Then the file starts to multiply

There is no .env spec

Which value wins?

Who loaded .env first?

An ignored file is still a file

Let .env become small again

How Monosecret applies this

But I Use SOPS

How does your application use the secret?

Different layers, different jobs

Where Monosecret goes next

Secrets Don’t Belong in Config

NixOS contains 110 workarounds for this

Give secrets their own interface

How I got it wrong in Cachix

Declare once, resolve anywhere

Making the boundary practical

Monosecret 0.12: audit logs and coding agents

The audit log

Supplying a reason

Configuring when a reason is required

Upgrading

There is no `.env` spec

Who loaded `.env` first?

Let `.env` become small again