Python SDK Secrets reference

See Secrets for usage examples and security boundaries.

Secret

Secret.env()

@staticmethod
def env(
    env_var: str,
    *,
    value: str,
    allow: Sequence[str] = (),
    allow_placeholder_for: Sequence[str] = (),
    passthrough: Sequence[str] = (),  # deprecated alias
    placeholder: str | None = None,
    require_tls_identity: bool = True,
    violation_action: ViolationAction | None = None,
    substitution: SecretSubstitution | None = None,
) -> SecretEntry

Example

import os
from microsandbox import Sandbox, Secret, SecretSubstitution, ViolationAction

secret = Secret.env(
    "SERVICE_API_KEY",
    value=os.environ["SERVICE_API_KEY"],
    allow=["api.example.com", "*.example.com"],
    allow_placeholder_for=["api.anthropic.com"],
    violation_action=ViolationAction.BLOCK_AND_TERMINATE,
    substitution=SecretSubstitution(query=True),
)

sb = await Sandbox.create(
    "worker",
    image="python",
    secrets=[secret],
    secret_violation_action=ViolationAction.BLOCK_AND_LOG,
)

Create a secret entry that maps an environment variable to a real value. The guest sees a placeholder; the TLS proxy substitutes the real value only when traffic goes to an allowed host. Pass the returned entry to Sandbox.create(..., secrets=[...]).

Parameters

env_varstr

Environment variable name. Must be non-empty and cannot contain = or NUL; shell-identifier syntax is not required.

valuestr

The real secret value. Never enters the guest VM. Keyword-only and required. Raw values are persisted in the durable sandbox configuration.

allowSequence[str]

Exact hosts or wildcard patterns allowed to receive the real value. At least one exact or wildcard host is required. Default ().

allow_placeholder_forSequence[str]

Exact hosts or wildcard patterns allowed to receive the unchanged placeholder. Does not grant access to the real value. Default ().

placeholderstr | None

Custom placeholder string: non-empty, up to 1024 bytes, no NUL/CR/LF. Auto-generated as $MSB_<env_var> when None. Default None.

require_tls_identitybool

Only substitute on TLS-intercepted connections. Disable only if you know the traffic is safe. Default True.

violation_actionViolationAction | None

Per-secret blocking action. Default None inherits the network setting, whose default is BLOCK_AND_LOG.

substitutionSecretSubstitution | None

Where in the HTTP request to substitute. None uses SecretSubstitution() defaults. Default None.

Returns

SecretEntry

Secret entry for Sandbox.create(secrets=[…]).

Validation and lifecycle

Sandbox configuration validation rejects empty environment names, names containing = or NUL, missing allowed hosts, every substitution location disabled, and placeholders that are empty, longer than 1024 bytes, or contain NUL/CR/LF. Secret.env() constructs an entry; it does not itself run all native validation. Raw values are persisted at rest. Prefer source references through live modification when the secret is available in the host environment. Rotating or removing an existing secret does not require a restart; adding a secret or changing its guest-visible placeholder does. Live modification is local-only. passthrough= remains a deprecated alias for allow_placeholder_for= and emits a DeprecationWarning when used with hosts. If both are supplied, the host lists are combined. The returned SecretEntry.passthrough field and serialized configuration keep their existing names.

Types

SecretEntry

Returned by Secret.env()

A single secret entry, used in Sandbox.create(secrets=[...]). Construct it with Secret.env() rather than directly.

Field	Type	Default	Description
env_var	`str`	required	Environment variable name (non-empty, no `=` or NUL)
value	`str`	required	Secret value. Never enters the guest
allow	`tuple[str, ...]`	`()`	Exact or wildcard hosts allowed to receive the real value
passthrough	`tuple[str, ...]`	`()`	Exact or wildcard hosts allowed to receive the unchanged placeholder
placeholder	`str \| None`	`None`	Placeholder string: non-empty, up to 1024 bytes, no NUL/CR/LF. Auto-generated as `$MSB_<env_var>` when `None`
require_tls_identity	`bool`	`True`	Only substitute on TLS-intercepted connections
violation_action	`ViolationAction` `\| None`	`None`	Per-secret override; inherits the sandbox-wide action when omitted
substitution	`SecretSubstitution`	`SecretSubstitution()`	Per-request substitution scopes

SecretSubstitution

substitution.headers

headers: bool = True

Substitute in headers, including Basic authentication. Default: True.

substitution.header_fields

header_fields: tuple[str, ...] = ()

Restrict substitution to these header names. An empty list allows all headers. Requires header substitution to be enabled. Prefer only the intended credential header, such as Authorization, to prevent other headers from exposing a secret in a reflected response.

substitution.query

query: bool = False

Substitute in the URL query string. Default: False.

substitution.body

body: bool = False

Substitute in supported HTTP/1 bodies. Default: False. Fixed-length bodies up to 16 MiB update Content-Length; larger bodies are blocked. Chunked bodies are decoded and re-encoded. Encoded bodies pass through unchanged. HTTP/2 body substitution is unsupported, and matching placeholders are blocked. At least one substitution location must remain enabled. On verified allowed hosts, disabled locations forward the placeholder unchanged. Other destinations must match the passthrough policy or follow the violation action. This is a frozen dataclass. Defaults are omitted from serialized configuration; explicit headers=False is preserved. Assigning another type to SecretEntry.substitution raises TypeError when serialized.

ViolationAction

Used by Secret.env() · SecretEntry.violation_action

String enum defining the blocking action when a placeholder cannot be substituted or passed through. Set the sandbox-wide default with Network.secret_violation_action or the top-level Sandbox.create(secret_violation_action=...); the top-level value takes precedence if both are supplied. A secret’s violation_action overrides that default. Passthrough is a host policy, not an enum member.

Member	Value	Description
`ViolationAction.BLOCK`	`"block"`	Silently drop the request. The guest sees a connection reset.
`ViolationAction.BLOCK_AND_LOG`	`"block-and-log"`	Drop the request and emit a warning log on the host side. This is the default.
`ViolationAction.BLOCK_AND_TERMINATE`	`"block-and-terminate"`	Drop the request, log an error, and shut down the entire sandbox.

SecretViolationError

Subclass of MicrosandboxError

Raised when a secret placeholder was sent to a disallowed host. Carries code = "secret-violation".

Getting Started

SDKs

CLI

Secrets

Secret

Secret.env()

Validation and lifecycle

Types

SecretEntry

SecretSubstitution

substitution.headers

substitution.header_fields

substitution.query

substitution.body

ViolationAction

SecretViolationError

​Secret

​Secret.env()

​Validation and lifecycle

​Types

​SecretEntry

​SecretSubstitution

​substitution.headers

​substitution.header_fields

​substitution.query

​substitution.body

​ViolationAction

​SecretViolationError

Secret

Secret.env()

Validation and lifecycle

Types

SecretEntry

SecretSubstitution

substitution.headers

substitution.header_fields

substitution.query

substitution.body

ViolationAction

SecretViolationError