Secrets - Microsandbox

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"},
        },
    )),
)

Host Matching

Go does not expose the Rust HostPattern enum directly. Instead, exact and wildcard host patterns are represented with fields on SecretEntry and SecretEnvOptions.

Runtime pattern	Go API	Matches
`HostPattern::Exact("api.example.com")`	`AllowHosts: []string{"api.example.com"}`	That exact SNI host
`HostPattern::Wildcard("*.example.com")`	`AllowHostPatterns: []string{"*.example.com"}`	Hosts matching the wildcard pattern

These fields decide where the real secret value may be substituted. A host that is not matched by either field is disallowed for that secret, so sending its placeholder to that host triggers the configured ViolationAction.

Exact and wildcard allow-list entries are pinned to observed DNS answers and TLS identity. At least one exact or wildcard host is required.

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

Name	Type	Description
envVar	`string`	Environment variable name. Must be non-empty and cannot contain `=` or NUL; shell-identifier syntax is not required
value	`string`	The real secret value. Never enters the guest VM
opts	`SecretEnvOptions`	Allowed hosts, placeholder override, TLS requirement, violation action. Pass `SecretEnvOptions{}` for defaults

Returns

Type	Description
`SecretEntry`	Pass 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.

Field	Type	Description
EnvVar	`string`	Environment variable name holding the placeholder inside the sandbox. Must be non-empty and cannot contain `=` or NUL; shell-identifier syntax is not required
Value	`string`	Real secret value (stays on the host)
AllowHosts	`[]string`	Hosts allowed to receive the real value (exact match)
AllowHostPatterns	`[]string`	Wildcard host patterns (e.g. `"*.googleapis.com"`)
Placeholder	`string`	Custom placeholder: non-empty, up to 1024 bytes, no NUL/CR/LF. Auto-generated as `$MSB_<env_var>` when empty
RequireTLS	`*bool`	Require a verified TLS identity before substituting. Default `true` when `nil`
OnViolation	`ViolationAction`	Override 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.

Field	Type	Description
AllowHosts	`[]string`	Allowed hosts (exact match)
AllowHostPatterns	`[]string`	Wildcard patterns
Placeholder	`string`	Custom placeholder: non-empty, up to 1024 bytes, no NUL/CR/LF
RequireTLS	`*bool`	TLS-identity requirement
OnViolation	`ViolationAction`	Per-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.

Constant	Value	Description
`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