docs: document the 128 KiB size limit for Warp-managed secrets

[hongyi-chen]

Summary

Warp-managed secrets are injected as environment variables, so they're bounded by the OS per-variable limit. Warp validates that bound when you create or update a secret, but the secrets page didn't mention any size limit — so the first time a user learns about it is when a create fails.

Found by the missing_docs drift-watch audit (changelog item #14219) and verified against crates/managed_secrets/src/secret_value.rs.

Changes

src/content/docs/platform/secrets.mdx

• Added a Secret size limit subsection under "How secrets are made available to cloud agents", covering:
  • the 128 KiB (131,072 byte) ceiling and why it exists,
  • that the limit applies to the whole NAME=value string, so the name eats into the usable value length,
  • that validation happens at create/update time rather than mid-run,
  • that multi-variable secrets such as AWS credentials are validated per variable,
  • a workaround for payloads that genuinely exceed the limit.

Source verification

MAX_SECRET_FIELD_BYTES = 128 * 1024 - 1 in crates/managed_secrets/src/secret_value.rs, one less than Linux's MAX_ARG_STRLEN to leave room for the trailing NUL. validate_field_sizes computes max_value_len = MAX_SECRET_FIELD_BYTES - env_key.len() - 1 for the =, and runs check() once per env var a secret expands into (AnthropicBedrockAccessKey checks four).

Verification

• npm run build passes.
• Internal link check passes (0 broken links).

Deferred findings from this audit run

None specific to this page. Run-wide deferrals are listed in the companion audit-bookkeeping PR.

Conversation: https://staging.warp.dev/conversation/53c4f3f8-39bb-46c1-a5c0-66b467db0439
Run: https://oz.staging.warp.dev/runs/019fb91e-74a0-73f4-ac72-f2d88c32fab5

This PR was generated with Oz.

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Jul 31, 2026 11:49pm

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR adds a Secret size limit subsection to explain the 128 KiB environment-variable bound for Warp-managed secrets. The added section is generally scoped to the right place, but one central sizing formula can mislead users for typed secrets that expand into provider-specific environment variables.

Concerns

• The size calculation currently tells readers to subtract the Warp secret's name, but typed secrets are validated against the generated environment variable names they expand into, so the documented calculation can be wrong for multi-variable secrets.

Verdict

Found: 0 critical, 1 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

⚠️ [IMPORTANT] This points users to subtract the Warp secret's name, but typed secrets like AWS credentials are validated against generated env var names (AWS_ACCESS_KEY_ID, etc.), so the calculation can be wrong. Use the environment variable name instead.

Suggested change

Because secrets are injected as environment variables, each one has to fit inside the operating system's per-variable limit of 128 KiB (131,072 bytes). Warp counts the full `NAME=value` string against that limit, so the usable value length is 128 KiB minus the secret's name, the `=` sign, and the terminating null byte.

Because secrets are injected as environment variables, each resulting `NAME=value` entry has to fit inside the operating system's per-variable limit of 128 KiB (131,072 bytes), including the terminating null byte. Warp counts the environment variable name, the `=` sign, the value, and that null byte against the limit, so the usable value length is slightly less than 128 KiB and depends on the environment variable name.