Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 | ViolationPolicy = 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
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_violationViolationAction | ViolationPolicyBLOCK_AND_LOGPer-secret violation behavior
injectionSecretInjection | NoneNoneWhere in the HTTP request to substitute. None uses the defaults.
Returns
TypeDescription
SecretEntrySecret entry for SandboxConfig.secrets

​
Host Matching

Python host settings map to the runtime HostPattern model. Allow-list fields decide where the real secret value may be substituted; passthrough fields decide where the placeholder may be forwarded unchanged.
Pattern kindPython APIMatches
Exact hostallow_hosts=("api.example.com",), ViolationPolicy.passthrough(hosts=("api.example.com",))That exact SNI host
Wildcard hostallow_host_patterns=("*.example.com",), ViolationPolicy.passthrough(host_patterns=("*.example.com",))Hosts matching the wildcard pattern
Any hostViolationPolicy.passthrough(all_hosts=True)Every host for passthrough
Passthrough host patterns do not make a secret eligible for substitution. They only prevent blocking when the guest sends the placeholder to a matching host, so the request is forwarded with the placeholder unchanged.

​
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_violationViolationAction | ViolationPolicyPer-secret violation behavior
injectionSecretInjectionPer-request injection scopes

​
SecretInjection

Frozen dataclass controlling where in the HTTP request the secret value is substituted.
FieldTypeDefaultDescription
headersboolTrueSubstitute the placeholder anywhere it appears in the headers.
basic_authboolTrueDecode Authorization: Basic <base64> credentials, substitute the placeholder in the decoded user:password, and re-encode. Other schemes (Bearer, Digest) are handled by headers.
query_paramsboolFalseSubstitute in the request line’s query string.
bodyboolFalseSubstitute 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.
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.
"passthrough"Forward matching hosts with the placeholder unchanged. Non-matching hosts use the default secret violation action.

​
ViolationPolicy

Frozen dataclass for passthrough host policies. Use ViolationPolicy.passthrough(...) when selected hosts should receive placeholders unchanged. 
ViolationPolicy.passthrough(
    hosts=("api.anthropic.com",),
    host_patterns=("*.example.com",),
    all_hosts=False,
)