Skip to main content
See Secrets for how placeholder substitution works and usage examples.

​
Secret

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

​
Secret.env()

@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,
) -> 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
NameTypeDefaultDescription
env_varstr-Environment variable name (e.g. "OPENAI_API_KEY")
valuestr-The real secret value. Never enters the guest VM. Required.
allow_hostsSequence[str]()Hosts allowed to receive the real value (exact match). The TLS proxy matches against the SNI.
allow_host_patternsSequence[str]()Wildcard host patterns (e.g. "*.googleapis.com")
placeholderstr | NoneNoneCustom placeholder string. Auto-generated as $MSB_<env_var> if not set.
require_tlsboolTrueOnly substitute on TLS-intercepted connections. Disable only if you know the traffic is safe.
on_violationViolationActionBLOCK_AND_LOGAction when the placeholder is sent to a disallowed host
Returns
TypeDescription
SecretEntrySecret entry for SandboxConfig.secrets

​
Types

​
SecretEntry

Frozen dataclass returned by Secret.env() and used in SandboxConfig.secrets.
FieldTypeDescription
env_varstrEnvironment variable name
valuestrSecret value
allow_hoststuple[str, ...]Allowed hosts (exact match)
allow_host_patternstuple[str, ...]Wildcard patterns
placeholderstr | NonePlaceholder string
require_tlsboolTLS requirement
on_violationViolationActionViolation action

​
ViolationAction

String enum (StrEnum) defining the action taken when a secret placeholder is sent to a disallowed host.
ValueDescription
"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.