Add a secret
SetGITHUB_TOKEN in your host environment, then bind it to api.github.com:
$MSB_GITHUB_TOKEN. Default placeholders preserve the environment variable’s spelling; custom placeholders are optional.
Passing a raw value through an SDK persists it in the host-side sandbox configuration. Stopping the sandbox does not remove that stored value. The CLI example stores an environment reference and reads it at sandbox startup; inline credential values are rejected.
Use a secret
Run the request inside the sandbox:GITHUB_TOKEN holds a placeholder. microsandbox substitutes the real token when the request reaches the allowed host.
Choose substitution locations
Enable only the locations your API needs. For headers, list credential fields such as
Authorization; an empty list permits every header and could let an allowed endpoint echo a substituted secret back to the guest.
Query parameters
Enable query substitution only when the API requires a credential in the URL:Request bodies
Enable body substitution only when the API requires a credential in the body:Substitution limits and disabled locations
Substitution limits and disabled locations
On a destination that passes the secret’s host and TLS checks, placeholders in disabled locations pass through unchanged. Other destinations need explicit passthrough permission or follow the violation action. Disabling headers also disables Basic authentication substitution; a non-empty header list requires header substitution to be enabled.When enabled, body substitution supports fixed-length HTTP/1 bodies up to 16 MiB and chunked HTTP/1 bodies. Larger fixed-length bodies are blocked. Encoded bodies pass through unchanged; HTTP/2 body substitution is unsupported and matching body placeholders are blocked. See body limits.
Violation actions
A secret-policy violation occurs when a request carries a placeholder to a destination that can receive neither the credential nor the unchanged placeholder. Choose what happens to that request:
Per-secret actions override the sandbox default. Placeholder passthrough is a separate host rule. The denial message controls what a blocked HTTP request can show to the caller.
New sandboxes return JSON
403 errors for supported secret-policy violations by default. Locally, set network.http.deny_response: false to disable them, or customize the message with network.http.secret_deny_message. See HTTP denial responses for the response format and limits.
Block
Reject the request without a violation log:Block and log
The default. No additional configuration is needed; to set it explicitly:Block and terminate
Stop the sandbox when a violation occurs:Pass through placeholders
Allow an additional host to receive the unchanged placeholder where substitution does not apply. Credential-allowed hosts already receive unchanged placeholders in disabled locations after passing the secret’s identity checks. This permission does not grant access to the credential; existing substitution permissions still apply. For example, allow the placeholder to appear in an AI request:Custom denial message
Supported secret-policy blocks return JSON403 responses by default. Set the message shown to the caller:
code: secret_policy_denied and the requested domain. The YAML example shows the same setting. See HTTP denial responses for response limits, TLS requirements, and opt-out settings.
Update secrets
A secret’s value, allowed hosts, and removal can apply live when supported. Adding a secret or changing its placeholder, substitution, violation action, TLS identity requirement, or placeholder hosts requires a restart. These examples use a host environment reference and allow a restart if needed:TLS and restart details
TLS and restart details
On a local sandbox, new secrets require TLS identity by default and enable interception if needed. That change requires a restart. Existing secrets that explicitly allow plain-HTTP substitution can still rotate live. Removing the last TLS-dependent secret leaves interception enabled.
--next-start) instead of restart, then stop and start the sandbox.
Updating a sandbox secret does not rotate or revoke it at the issuing service. See Live Modify for restart and TLS behavior.
YAML configuration
You can also declare secrets and the custom denial message in sandbox YAML. An exact environment reference avoids persisting the resolved value:substitution selects where credentials are inserted; passthrough permits unchanged placeholders on additional hosts. A top-level secret_violation_action sets the sandbox-wide default. See CLI configuration for loading configuration and CLI equivalents.
Security boundary
- Destination checks: Injection checks the allowed host against observed DNS and TLS identity, including the HTTP request authority. A forged hostname or hard-coded IP is not enough.
- TLS: Injection requires intercepted TLS by default. Bypassed TLS cannot be inspected for placeholders or receive injected credentials. See TLS inspection.
- Trusted hosts: Allowed endpoints receive the real value and could return it to the guest. Keep allow lists narrow and include redirect destinations only when trusted. Wildcards include the root domain and its subdomains.
- Network access: Secret rules decide where credentials can be injected; network rules still control connectivity.
- Guest-side signing: A placeholder cannot replace raw credentials used to sign requests inside the guest. Supplying the real value as a plain environment variable exposes it to guest code.