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 = ViolationAction.BLOCK_AND_LOG,
injection: SecretInjection | None = None,
) -> SecretEntry
| 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. |
| 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. |
