docs/sdk/go/secrets.mdx
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.
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"},
},
)),
)
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 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 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.
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.
The Secret factory is a package-level value. Call its methods to build SecretEntry values without populating struct literals by hand.
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.
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.
| 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; never crosses the FFI into the guest |
AllowHosts | []string | Hosts allowed to receive the real value (exact match) |
AllowHostPatterns | []string | Wildcard host patterns, e.g. "*.openai.com" |
Placeholder | string | Custom 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 | *bool | Require a verified TLS identity before substituting. Defaults to true when nil |
OnViolation | ViolationAction | Override 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 |
Tunes Secret.Env beyond the required envVar and value.
| Field | Type | Description |
|---|---|---|
AllowHosts | []string | Allowed hosts (exact match) |
AllowHostPatterns | []string | Wildcard host patterns |
Placeholder | string | Custom placeholder: non-empty, up to 1024 bytes, no NUL/CR/LF |
RequireTLS | *bool | Require a verified TLS identity before substituting. Defaults to true when nil |
OnViolation | ViolationAction | Per-secret violation action |
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.
| Constant | Value | Description |
|---|---|---|
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 |