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. Secrets never enter the VM. The Go SDK passes each SecretEntry to the runtime, which exposes a placeholder string inside the guest (e.g. $MSB_OPENAI_API_KEY) and substitutes the real value at the network layer only when traffic reaches an allowed host. 
sb, err := m.CreateSandbox(ctx, "agent",
    m.WithImage("python:3.12"),
    m.WithSecrets(m.Secret.Env(
        "OPENAI_API_KEY",
        os.Getenv("OPENAI_API_KEY"),
        m.SecretEnvOptions{
            AllowHosts: []string{"api.openai.com"},
        },
    )),
)

​
Secret

Helpers that construct SecretEntry values. Access via the package-level Secret value.

​
Secret.Env()

func (secretFactory) Env(envVar, value string, opts SecretEnvOptions) 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
NameTypeDescription
envVarstringEnvironment variable name (e.g. "OPENAI_API_KEY")
valuestringThe real secret value. Never enters the guest VM
optsSecretEnvOptionsAllowed hosts, placeholder override, TLS requirement, violation action. Pass SecretEnvOptions{} for defaults
Returns
TypeDescription
SecretEntryPass to WithSecrets
m.Secret.Env("STRIPE_KEY", os.Getenv("STRIPE_KEY"),
    m.SecretEnvOptions{
        AllowHosts:        []string{"api.stripe.com"},
        AllowHostPatterns: []string{"*.stripe.com"},
        Placeholder:       "$MSB_STRIPE",
    },
)

​
Types

​
SecretEntry

The value passed to WithSecrets. Usually produced by Secret.Env; exported for callers that prefer struct literals.
FieldTypeDescription
EnvVarstringEnvironment variable name holding the placeholder inside the sandbox
ValuestringReal secret value (stays on the host)
AllowHosts[]stringHosts allowed to receive the real value (exact match against TLS SNI)
AllowHostPatterns[]stringWildcard host patterns (e.g. "*.googleapis.com")
PlaceholderstringCustom placeholder. Auto-generated as $MSB_<ENV_VAR> when empty
RequireTLS*boolRequire a verified TLS identity before substituting. Default true when nil
OnViolationViolationActionOverride the sandbox-wide action when this secret is sent to a disallowed host. The last non-empty OnViolation across all secrets wins (the runtime applies it network-wide)

​
SecretEnvOptions

Tuning struct for Secret.Env.
FieldTypeDescription
AllowHosts[]stringAllowed hosts (exact match)
AllowHostPatterns[]stringWildcard patterns
PlaceholderstringCustom placeholder
RequireTLS*boolTLS-identity requirement
OnViolationViolationActionPer-secret violation action

​
ViolationAction

type ViolationAction string
Action taken when a secret placeholder is detected going to a disallowed host. Configure the sandbox-wide default on NetworkConfig.OnSecretViolation; override per-secret with SecretEntry.OnViolation.
ConstantValueDescription
ViolationActionDefault""Runtime default (currently block-and-log)
ViolationActionBlock"block"Silently drop the request. The guest sees a connection reset
ViolationActionBlockAndLog"block-and-log"Drop the request and emit a warning log on the host side
ViolationActionBlockAndTerminate"block-and-terminate"Drop the request, log an error, and shut down the entire sandbox