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.

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 (e.g. `"OPENAI_API_KEY"`)
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
Value	`string`	Real secret value (stays on the host)
AllowHosts	`[]string`	Hosts allowed to receive the real value (exact match against TLS SNI)
AllowHostPatterns	`[]string`	Wildcard host patterns (e.g. `"*.googleapis.com"`)
Placeholder	`string`	Custom placeholder. 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
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