Secrets - Microsandbox

See Secrets for how placeholder substitution works and usage examples.

Secret

Static factory for creating secret entries used in SandboxConfig.secrets.

Secret.env()

python

@staticmethod
def env(
    env_var: str,
    *,
    value: str,
    allow_hosts: Sequence[str] = (),
    allow_host_patterns: Sequence[str] = (),
    placeholder: str | None = None,
    require_tls: bool = True,
    on_violation: ViolationAction = ViolationAction.BLOCK_AND_LOG,
    injection: SecretInjection | None = None,
) -> SecretEntry

Create a secret entry that maps an environment variable to a real value. The guest sees a placeholder - the real value is only substituted by the TLS proxy when traffic goes to an allowed host.

Parameters

Name	Type	Default	Description
env_var	`str`	-	Environment variable name (e.g. `"OPENAI_API_KEY"`)
value	`str`	-	The real secret value. Never enters the guest VM. Required.
allow_hosts	`Sequence[str]`	`()`	Hosts allowed to receive the real value (exact match). The TLS proxy matches against the SNI.
allow_host_patterns	`Sequence[str]`	`()`	Wildcard host patterns (e.g. `"*.googleapis.com"`)
placeholder	`str \| None`	`None`	Custom placeholder string. Auto-generated as `$MSB_<env_var>` if not set.
require_tls	`bool`	`True`	Only substitute on TLS-intercepted connections. Disable only if you know the traffic is safe.
on_violation	`ViolationAction`	`BLOCK_AND_LOG`	Action when the placeholder is sent to a disallowed host
injection	`SecretInjection` `\| None`	`None`	Where in the HTTP request to substitute. `None` uses the defaults.

Returns

Type	Description
`SecretEntry`	Secret entry for `SandboxConfig.secrets`

Types

SecretEntry

Frozen dataclass returned by Secret.env() and used in SandboxConfig.secrets.

Field	Type	Description
env_var	`str`	Environment variable name
value	`str`	Secret value
allow_hosts	`tuple[str, ...]`	Allowed hosts (exact match)
allow_host_patterns	`tuple[str, ...]`	Wildcard patterns
placeholder	`str \| None`	Placeholder string
require_tls	`bool`	TLS requirement
on_violation	`ViolationAction`	Violation action
injection	`SecretInjection`	Per-request injection scopes

SecretInjection

Frozen dataclass controlling where in the HTTP request the secret value is substituted.

Field	Type	Default	Description
headers	`bool`	`True`	Substitute the placeholder anywhere it appears in the headers.
basic_auth	`bool`	`True`	Decode `Authorization: Basic <base64>` credentials, substitute the placeholder in the decoded `user:password`, and re-encode. Other schemes (`Bearer`, `Digest`) are handled by `headers`.
query_params	`bool`	`False`	Substitute in the request line's query string.
body	`bool`	`False`	Substitute in the request body. Adjusts `Content-Length` automatically.

ViolationAction

String enum (StrEnum) defining the action taken when a secret placeholder is sent to a disallowed host.

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