Go SDK Secrets reference

See Secrets for usage examples and security boundaries.

Functions

WithSecrets()

func WithSecrets(secrets ...SecretEntry) SandboxOption

Example

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python:3.12"),
    m.WithSecrets(
        m.Secret.Env("STRIPE_KEY", os.Getenv("STRIPE_KEY"),
            m.SecretEnvOptions{Allow: []string{"api.stripe.com"}}),
        m.Secret.Env("OPENAI_API_KEY", os.Getenv("OPENAI_API_KEY"),
            m.SecretEnvOptions{Allow: []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.

Secret

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

Example

m.Secret.Env("STRIPE_KEY", os.Getenv("STRIPE_KEY"),
    m.SecretEnvOptions{
        Allow:        []string{"api.stripe.com", "*.stripe.com"},
        Passthrough:  []string{"api.anthropic.com"},
        Substitution: m.SecretSubstitution{Body: true},
        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. Supply at least one exact or wildcard host in Allow; an empty allow-list is rejected when the sandbox configuration is validated.

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. Passed to the native host runtime, never exposed inside the guest.

optsSecretEnvOptions

Allowed hosts, placeholder override, TLS requirement, and violation action.

Returns

SecretEntry

Pass to WithSecrets.

Validation and lifecycle

Sandbox configuration validation rejects invalid environment names (empty or containing = or NUL), an empty allow-list, all substitution locations disabled, and invalid placeholders. Secret.Env() constructs a value; errors surface when the configuration is validated. Raw values are persisted in the durable sandbox configuration. See source references and live modification to rotate or remove secrets without restarting. Adding a secret or changing its guest-visible placeholder requires a restart. Live modification is local-only.

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.

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, including across the native FFI boundary
`Allow`	`[]string`	Exact hosts or wildcard patterns allowed to receive the real value
`Passthrough`	`[]string`	Exact hosts or wildcard patterns allowed to receive the unchanged placeholder
`Substitution`	`SecretSubstitution`	Enabled request locations; zero value enables headers only
`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
`RequireTLSIdentity`	`*bool`	Require a verified TLS identity before substituting. Defaults to `true` when `nil`
`ViolationAction`	`ViolationAction`	Override the sandbox-wide action when this secret is detected going to a disallowed host. This overrides the network default for this secret only

SecretEnvOptionsstruct

accepted by Secret.Env()

Tunes Secret.Env beyond the required envVar and value.

Field	Type	Description
`Allow`	`[]string`	Exact hosts or wildcard patterns allowed to receive the real value
`Passthrough`	`[]string`	Hosts allowed to receive the unchanged placeholder
`Substitution`	`SecretSubstitution`	Zero value enables headers only
`Placeholder`	`string`	Custom placeholder: non-empty, up to 1024 bytes, no NUL/CR/LF
`RequireTLSIdentity`	`*bool`	Require a verified TLS identity before substituting. Defaults to `true` when `nil`
`ViolationAction`	`ViolationAction`	Per-secret violation action

SecretSubstitutionstruct

Used by SecretEntry · SecretEnvOptions

Field	Type	Default	Description
`Headers`	`*bool`	`true` when `nil`	Substitute in headers, including decoded Basic authentication.
`Query`	`bool`	`false`	Substitute in URL query parameters.
`Body`	`bool`	`false`	Substitute in supported HTTP/1 request bodies.

Use a pointer to distinguish an explicit false from the default:

headers := false
secret := m.Secret.Env("GH_TOKEN", os.Getenv("GH_TOKEN"), m.SecretEnvOptions{
    Allow:           []string{"github.com", "api.github.com"},
    Passthrough:     []string{"api.anthropic.com"},
    Substitution:    m.SecretSubstitution{Headers: &headers, Body: true},
    ViolationAction: m.ViolationActionBlockAndTerminate,
})
sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithSecrets(secret),
    m.WithNetwork(&m.NetworkConfig{
        SecretViolationAction: m.ViolationActionBlockAndLog,
    }),
)

At least one substitution location must remain enabled. Disabled locations block placeholders unless the destination matches Passthrough. Fixed-length HTTP/1 bodies up to 16 MiB update Content-Length; larger fixed-length bodies are blocked. Chunked bodies are decoded and re-encoded. Encoded bodies pass through unchanged. HTTP/2 DATA-frame body substitution is unsupported, and matching body placeholders are blocked.

ViolationActionstring enum

field of SecretEntry · NetworkConfig

type ViolationAction string

What happens when a secret placeholder cannot be substituted or passed through. Passthrough is a separate per-secret host policy, not a violation action. Configure the sandbox-wide default on NetworkConfig.SecretViolationAction; override per-secret with SecretEntry.ViolationAction.

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

Getting Started

SDKs

CLI

Secrets

Functions

WithSecrets()

Secret

Secret.Env()

Validation and lifecycle

Types

SecretEntrystruct

SecretEnvOptionsstruct

SecretSubstitutionstruct

ViolationActionstring enum

​Functions

​WithSecrets()

​Secret

​Secret.Env()

​Validation and lifecycle

​Types

​SecretEntrystruct

​SecretEnvOptionsstruct

​SecretSubstitutionstruct

​ViolationActionstring enum

Functions

WithSecrets()

Secret

Secret.Env()

Validation and lifecycle

Types

SecretEntrystruct

SecretEnvOptionsstruct

SecretSubstitutionstruct

ViolationActionstring enum