TypeScript SDK Secrets reference

See Secrets for usage examples and security boundaries.

SecretBuilder

Builder for one secret configuration.

secret.env()

env(varName: string): this

Set the environment variable name that holds the placeholder inside the guest. The guest sees $MSB_<varName> (or a custom placeholder), never the real value. Names must be non-empty and cannot contain = or NUL; shell-identifier syntax is not required. Required.

Parameters

varNamestring

Environment variable name (non-empty, no = or NUL).

secret.value()

value(value: string): this

Set the real secret value. This is the string that replaces the placeholder when a request reaches an allowed host. It never enters the guest VM. Required.

Parameters

valuestring

The actual credential or token.

secret.placeholder()

placeholder(placeholder: string): this

Override the auto-generated placeholder string. By default microsandbox generates $MSB_<envVar>. Use this when you need a specific format or when the placeholder must match a particular byte length. Placeholders must be non-empty, at most 1024 bytes, and cannot contain NUL, CR, or LF.

Parameters

placeholderstring

Custom placeholder string: non-empty, up to 1024 bytes, no NUL/CR/LF.

secret.allow()

allow(host: string): this

Example

.secret((s) =>
  s.env("STRIPE_KEY")
    .value(process.env.STRIPE_KEY!)
    .allow("api.stripe.com")
    .allow("files.stripe.com"),
)

Add an exact host or wildcard pattern allowed to receive the real secret value. A *.suffix pattern matches the suffix itself and its single- or multi-label subdomains. The proxy checks the host against the connection’s verified TLS identity and observed DNS history. Can be called multiple times to allow several hosts. At least one allowed host (exact, pattern, or any) is required.

Parameters

hoststring

Hostname or wildcard pattern, e.g. “api.example.com” or “*.example.com” (ASCII case-insensitive).

secret.allowAnyHostDangerous()

allowAnyHostDangerous(iUnderstand: boolean): this

Allow substitution on any host. Every server the guest connects to can then receive the real secret, which effectively disables host-based protection. The call is a no-op unless iUnderstand is true. Only use this when the secret is not sensitive or the sandbox network is fully locked down. This is the one allow-list pattern that skips DNS and TLS-identity pinning.

Parameters

iUnderstandboolean

Must be true to take effect.

secret.requireTlsIdentity()

requireTlsIdentity(enabled: boolean): this

When true, the secret is only substituted on TLS-intercepted connections where the proxy has verified it is performing MITM and the SNI matches an allowed host. Bypassed TLS is opaque and never receives substitution. Disable only when you know the traffic path is safe and explicitly supports non-TLS substitution. Default: true.

Parameters

enabledboolean

Require verified TLS identity. Default: true.

secret.substituteInHeaders()

substituteInHeaders(enabled: boolean): this

Control whether the placeholder is replaced anywhere in HTTP headers, including decoded and re-encoded Basic authentication credentials. This is the most common injection scope, covering Authorization: Bearer $MSB_... and similar patterns. Default: true.

Parameters

enabledboolean

Substitute in headers. Default: true.

secret.substituteInQuery()

substituteInQuery(enabled: boolean): this

Control whether the placeholder is replaced in the URL query string (the ?key=value portion of the request line). Default: false.

Parameters

enabledboolean

Substitute in query parameters. Default: false.

secret.substituteInBody()

substituteInBody(enabled: boolean): this

Control whether the placeholder is replaced in inspectable request bodies. When enabled, fixed-length HTTP/1 bodies up to 16 MiB are rewritten with an updated Content-Length; larger fixed-length bodies are blocked. Chunked HTTP/1 bodies are decoded and re-encoded with fresh chunk sizes. Encoded bodies pass through unchanged. HTTP/2 DATA-frame body substitution is unsupported, and matching body placeholders are blocked. Default: false.

Parameters

enabledboolean

Substitute in request bodies. Default: false.

secret.allowPlaceholderFor()

allowPlaceholderFor(host: string): this

Allow an exact host or wildcard pattern to receive the placeholder unchanged when it cannot be substituted. Repeat this method for multiple hosts. allowPassthroughFor() remains a deprecated alias. This never grants permission to receive the real secret; use allow() for substitution. Credential-allowed hosts already permit unchanged placeholders outside enabled substitution locations once the secret’s host and TLS identity checks pass. Without either permission, the configured blocking action applies.

secret.violationAction()

violationAction(action: "block" | "block-and-log" | "block-and-terminate"): this

Override the sandbox-wide action for this secret. Omitting this method inherits the network setting, whose default is "block-and-log". Invalid action strings throw an error. Passthrough is a separate per-secret host policy, not a violation action.

Example

.secret((s) =>
  s.env("API_KEY")
    .value(process.env.API_KEY!)
    .allow("api.github.com")
    .allowPlaceholderFor("api.anthropic.com")
    .substituteInBody(true)
    .violationAction("block-and-terminate"),
)

secret.build()

build(): SecretEntry

Materialize the SecretEntry. Called for you by SandboxBuilder.secret, so you rarely call it directly. If placeholder was not set, it defaults to $MSB_<envVar>. Consumes the builder; do not reuse it afterward. Throws if env or value was not set, or if the allow-list is empty. Sandbox configuration validation also rejects invalid environment names or placeholders and configurations with every substitution site disabled.

Returns

SecretEntry

The materialized secret entry.

SandboxBuilder

Two methods on SandboxBuilder for adding secrets without reaching into a NetworkBuilder. Both automatically enable TLS interception.

sandbox.secret()

secret(configure: (s: SecretBuilder) => SecretBuilder): this

Example

await using sb = await Sandbox.builder("payments-worker")
  .image("python")
  .secret((s) =>
    s.env("STRIPE_KEY")
      .value(process.env.STRIPE_KEY!)
      .allow("api.stripe.com")
      .allow("*.stripe.com")
      .substituteInHeaders(true)
      .substituteInQuery(false),
  )
  .create();

Add a secret with full configuration via a SecretBuilder closure. The builder’s build() is called for you.

Parameters

configure(s: SecretBuilder) => SecretBuilder

Configure the secret.

sandbox.secretEnv()

secretEnv(envVar: string, value: string, allowedHost: string): this

Example

await using sb = await Sandbox.builder("agent")
  .image("python")
  .secretEnv("OPENAI_API_KEY", process.env.OPENAI_API_KEY!, "api.openai.com")
  .create();

Three-argument shorthand. Auto-generates the placeholder as $MSB_<envVar> and allows substitution only on allowedHost. The default injection scopes apply (headers and Basic Auth enabled, query and body disabled).

Plaintext at rest. The value is persisted verbatim in the durable sandbox config until a later modify rotate migrates the entry to a source reference. Use this path when you hold only a value; use source references through the live-modify API when the value is available in the host environment.

Parameters

envVarstring

Environment variable name (non-empty, no = or NUL).

valuestring

Secret value.

allowedHoststring

Allowed destination host (exact match).

NetworkBuilder

The same secret configuration is available inside SandboxBuilder.network(n => ...) for callers who are already configuring networking. These methods set the secrets and the sandbox-wide violation policy directly on the network.

network.secret()

secret(configure: (s: SecretBuilder) => SecretBuilder): this

Example

await using sb = await Sandbox.builder("agent")
  .image("python")
  .network((n) =>
    n.secret((s) =>
      s.env("OPENAI_API_KEY")
        .value(process.env.OPENAI_API_KEY!)
        .allow("api.openai.com"),
    ),
  )
  .create();

Add a secret with full configuration via a SecretBuilder closure. Identical in behavior to SandboxBuilder.secret.

Parameters

configure(s: SecretBuilder) => SecretBuilder

Configure the secret.

network.secretEnv()

secretEnv(envVar: string, value: string, placeholder: string, allowedHost: string): this

Four-argument shorthand. Same as the SandboxBuilder form but lets you provide the placeholder explicitly instead of auto-generating $MSB_<envVar>.

Parameters

envVarstring

Environment variable name (non-empty, no = or NUL).

valuestring

Secret value.

placeholderstring

Explicit placeholder: non-empty, up to 1024 bytes, no NUL/CR/LF.

allowedHoststring

Allowed destination host (exact match).

network.secretEnvSimple()

secretEnvSimple(envVar: string, value: string, allowedHost: string): this

Three-argument shorthand on NetworkBuilder. Auto-generates the placeholder as $MSB_<envVar>, matching SandboxBuilder.secretEnv. Like NetworkBuilder.secret() and NetworkBuilder.secretEnv(), it enables TLS interception while preserving other TLS settings. The guest receives only the placeholder. Earlier SDK versions incorrectly exposed the supplied secret as the placeholder in this helper. Code that intentionally needs a raw guest environment value should use ordinary environment configuration; this helper keeps the credential on the host. Updating the SDK does not rewrite existing sandbox configurations; recreate or explicitly reconfigure sandboxes created with the affected helper.

Parameters

envVarstring

Environment variable name (non-empty, no = or NUL).

valuestring

Secret value.

allowedHoststring

Allowed destination host (exact match).

network.secretViolationAction()

secretViolationAction(action: "block" | "block-and-log" | "block-and-terminate"): this

Set the sandbox-wide blocking action for placeholders that cannot be substituted or passed through. SecretBuilder.violationAction() overrides it per secret. This method belongs to NetworkBuilder, so configure it through SandboxBuilder.network().

Example

await using sb = await Sandbox.builder("agent")
  .image("python")
  .network((n) =>
    n.secretEnvSimple("OPENAI_API_KEY", process.env.OPENAI_API_KEY!, "api.openai.com")
      .secretViolationAction("block-and-log"),
  )
  .create();

Types

SecretEntry

Returned by SecretBuilder.build()

The materialized object produced by SecretBuilder.build(). Configure secrets through the builder; its output is not the sparse live-modification input.

Field	Type	Description
`envVar`	`string`	Environment variable name (non-empty, no `=` or NUL)
`value`	`string`	Real secret value (stays on the host; raw values are persisted)
`placeholder`	`string`	Guest-visible placeholder; defaults to `$MSB_<envVar>`, non-empty, at most 1024 bytes, no NUL/CR/LF
`allowedHosts`	`string[]`	Exact allowed hosts
`allowedHostPatterns`	`string[]`	Wildcard allowed hosts
`allowAnyHost`	`boolean`	Permit substitution to any host
`passthroughHosts`	`string[]`	Hosts or patterns allowed to receive the unchanged placeholder
`requireTlsIdentity`	`boolean`	Require verified TLS identity before substitution
`substitution`	`SecretSubstitution`	Enabled request locations

SecretSubstitution

Used by SecretEntry.substitution

The materialized substitution settings. Set them through the substituteIn* methods on SecretBuilder. At least one location must remain enabled. On credential-allowed hosts that pass the secret’s identity checks, disabled locations forward the placeholder unchanged. Other destinations require explicit placeholder permission or follow the violation action.

Field	Type	Builder default	Description
`headers`	`boolean`	`true`	Substitute in headers, including Basic authentication.
`query`	`boolean`	`false`	Substitute in URL query parameters.
`body`	`boolean`	`false`	Substitute in supported bodies; see limits.

ViolationAction

Used by SecretBuilder.violationAction() · NetworkBuilder.secretViolationAction()

The ViolationActions array enumerates these values. Per-secret settings override the network default; passthrough is configured separately.

type ViolationAction = "block" | "block-and-log" | "block-and-terminate";

Value	Description
`"block"`	Block the request without logging.
`"block-and-log"`	Block and emit a warning on the host. This is the default.
`"block-and-terminate"`	Block, log an error, and shut down the sandbox.

Getting Started

SDKs

CLI

Secrets

SecretBuilder

secret.env()

secret.value()

secret.placeholder()

secret.allow()

secret.allowAnyHostDangerous()

secret.requireTlsIdentity()

secret.substituteInHeaders()

secret.substituteInQuery()

secret.substituteInBody()

secret.allowPlaceholderFor()

secret.violationAction()

secret.build()

SandboxBuilder

sandbox.secret()

sandbox.secretEnv()

NetworkBuilder

network.secret()

network.secretEnv()

network.secretEnvSimple()

network.secretViolationAction()

Types

SecretEntry

SecretSubstitution

ViolationAction

​SecretBuilder

​secret.env()

​secret.value()

​secret.placeholder()

​secret.allow()

​secret.allowAnyHostDangerous()

​secret.requireTlsIdentity()

​secret.substituteInHeaders()

​secret.substituteInQuery()

​secret.substituteInBody()

​secret.allowPlaceholderFor()

​secret.violationAction()

​secret.build()

​SandboxBuilder

​sandbox.secret()

​sandbox.secretEnv()

​NetworkBuilder

​network.secret()

​network.secretEnv()

​network.secretEnvSimple()

​network.secretViolationAction()

​Types

​SecretEntry

​SecretSubstitution

​ViolationAction

SecretBuilder

secret.env()

secret.value()

secret.placeholder()

secret.allow()

secret.allowAnyHostDangerous()

secret.requireTlsIdentity()

secret.substituteInHeaders()

secret.substituteInQuery()

secret.substituteInBody()

secret.allowPlaceholderFor()

secret.violationAction()

secret.build()

SandboxBuilder

sandbox.secret()

sandbox.secretEnv()

NetworkBuilder

network.secret()

network.secretEnv()

network.secretEnvSimple()

network.secretViolationAction()

Types

SecretEntry

SecretSubstitution

ViolationAction