Secrets

TypeScript secret substitution and placeholder passthrough

Secrets expose a placeholder to the guest and substitute the real value only for an allowed host and enabled request location. A placeholder in any other location is blocked unless the destination is explicitly allowed to receive it unchanged.

await using sandbox = await Sandbox.builder("worker")
  .secret((s) =>
    s.env("GH_TOKEN")
      .value(token)
      .allow("github.com")
      .allow("api.github.com")
      .substituteInHeaders(false)
      .substituteInQuery(false)
      .substituteInBody(true)
      .allowPassthroughFor("api.anthropic.com")
      .requireTlsIdentity(true)
      .violationAction("block-and-terminate"),
  )
  .secretViolationAction("block-and-log")
  .create();

allow() accepts exact hosts and wildcard patterns such as *.example.com. Use allowAnyHostDangerous(true) only when every destination may receive the real secret.

Substitution defaults to headers enabled, query disabled, and body disabled. Basic authentication follows the header setting. Disabling substitution does not make a placeholder inert: the placeholder is still blocked unless the request host matches allowPassthroughFor().

Violation actions are block, block-and-log, and block-and-terminate. The per-secret action overrides the sandbox-wide action. Passthrough is a host policy, not a violation action.

See Secrets for CLI and YAML syntax.