Skip to main content
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_SERVICE_API_KEY) and substitutes the real value at the network layer only when traffic reaches an allowed host.

Typical flow

import m "github.com/superradcompany/microsandbox/sdk/go"

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python:3.12"),
    m.WithSecrets(m.Secret.Env(
        "SERVICE_API_KEY",
        os.Getenv("SERVICE_API_KEY"),
        m.SecretEnvOptions{
            AllowHosts: []string{"api.example.com"},
        },
    )),
)

​
Host matching

Go does not expose the Rust HostPattern enum directly. Exact and wildcard host patterns are represented with the AllowHosts and AllowHostPatterns fields on SecretEntry and SecretEnvOptions.
Runtime patternGo APIMatches
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 there triggers the configured ViolationAction. Allow-list entries are pinned to observed DNS answers and TLS identity. At least one exact or wildcard host is required.

​
Functions

​
WithSecrets()

func WithSecrets(secrets ...SecretEntry) SandboxOption

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python:3.12"),
    m.WithSecrets(
        m.Secret.Env("STRIPE_KEY", os.Getenv("STRIPE_KEY"),
            m.SecretEnvOptions{AllowHosts: []string{"api.stripe.com"}}),
        m.Secret.Env("OPENAI_API_KEY", os.Getenv("OPENAI_API_KEY"),
            m.SecretEnvOptions{AllowHostPatterns: []string{"*.openai.com"}}),
    ),
)
Append credential secrets to the sandbox. Each call appends, so multiple calls accumulate. Secrets never enter the VM; the network proxy substitutes them at the transport layer. Pass to CreateSandbox alongside the other options.

Parameters

secrets…SecretEntry
Secret entries to attach, usually built with Secret.Env.

Returns

SandboxOption
Functional option for CreateSandbox.

​
Methods

The Secret factory is a package-level value. Call its methods to build SecretEntry values without populating struct literals by hand.

​
Secret.Env()

func (secretFactory) Env(envVar, value string, opts SecretEnvOptions) SecretEntry

m.Secret.Env("STRIPE_KEY", os.Getenv("STRIPE_KEY"),
    m.SecretEnvOptions{
        AllowHosts:        []string{"api.stripe.com"},
        AllowHostPatterns: []string{"*.stripe.com"},
        Placeholder:       "$MSB_STRIPE",
    },
)
Build a SecretEntry that maps an environment variable to a real value. The guest sees a placeholder; the real value is substituted by the TLS proxy only when traffic goes to an allowed host. Pass an empty SecretEnvOptions{} when no extra tuning is needed.

Parameters

envVarstring
Environment variable name holding the placeholder inside the sandbox. Must be non-empty and cannot contain = or NUL; shell-identifier syntax is not required.
valuestring
The real secret value. Never crosses the FFI into the guest.
optsSecretEnvOptions
Allowed hosts, placeholder override, TLS requirement, and violation action.

Returns

SecretEntry
Pass to WithSecrets.

​
Types

​
SecretEntrystruct

accepted by WithSecrets() · returned by Secret.Env()

A single credential the network proxy substitutes at the transport layer. The value never reaches the guest VM. Usually produced by Secret.Env; exported for callers that prefer struct literals.
FieldTypeDescription
EnvVarstringEnvironment variable name holding the placeholder inside the sandbox. Must be non-empty and cannot contain = or NUL; shell-identifier syntax is not required
ValuestringReal secret value; never crosses the FFI into the guest
AllowHosts[]stringHosts allowed to receive the real value (exact match)
AllowHostPatterns[]stringWildcard host patterns, e.g. "*.openai.com"
PlaceholderstringCustom placeholder shown inside the sandbox in place of the secret. Auto-generated from EnvVar when empty. Custom values must be non-empty, at most 1024 bytes, and cannot contain NUL, CR, or LF
RequireTLS*boolRequire a verified TLS identity before substituting. Defaults to true when nil
OnViolationViolationActionOverride the sandbox-wide action when this secret is detected going to a disallowed host. The last non-empty value across all secrets wins, since the runtime applies it network-wide

​
SecretEnvOptionsstruct

accepted by Secret.Env()

Tunes Secret.Env beyond the required envVar and value.
FieldTypeDescription
AllowHosts[]stringAllowed hosts (exact match)
AllowHostPatterns[]stringWildcard host patterns
PlaceholderstringCustom placeholder: non-empty, up to 1024 bytes, no NUL/CR/LF
RequireTLS*boolRequire a verified TLS identity before substituting. Defaults to true when nil
OnViolationViolationActionPer-secret violation action

​
ViolationActionstring enum

field of SecretEntry · NetworkConfig

type ViolationAction string
What happens when a secret placeholder is detected going to a host the secret isn’t allowed to talk to. Configure the sandbox-wide default on NetworkConfig.OnSecretViolation; override per-secret with SecretEntry.OnViolation.
ConstantValueDescription
ViolationActionDefault""Leave the runtime default in place (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