npm / @anthropic-ai/sandbox-runtime
@anthropic-ai/sandbox-runtime
What changed in @anthropic-ai/sandbox-runtime 0.0, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
27 breaking44 security41 new APIs and options7 performance15 behavior and defaults1 tooling38 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@anthropic-ai/sandbox-runtime 0.0173 changes
Breaking changes 27
Linux VM sockets are refused with EPERM wherever the seccomp filter runs.
Only the literal value true allows a connection; other truthy values deny. The callback may also resolve to { allow: false, reason }.
Credential file entries take precedence over allowRead and allowWrite on every platform; paths at or beneath them are not bound back or granted.
On Linux, denyWrite takes precedence over allowWrite regardless of nesting; writes beneath a denied directory fail as read-only.
Adds normalizedRequestTarget and requestTargetIsAmbiguous callback fields; ambiguous targets are refused with 400 by default.
Requires Node or Bun 1.4 or later; initialization throws on older Bun. CONNECT requests over maxTunnels receive 503.
The supported Node.js engine requirement is now >=22.12.0.
On Linux, dangerous names in subdirectories are write-denied one level below the working directory, and unreadable folders are denied whole.
On Linux, a read deny or credential mask on a symlinked allowRead target takes precedence over the carve-out.
Linux refuses to start when root lacks CAP_SETFCAP.
Default write paths now obey a read deny, and interior path spellings are canonicalised.
Configuration now rejects a deny glob written with a trailing separator.
A / write root on Linux or read root on macOS no longer disables deny rules beneath it.
Allow-listed hostnames are refused if they resolve to loopback, link-local, or configured private ranges.
Linux drops a root caller's capabilities in both sandbox modes.
Non-interactive logon types are denied to the sandbox group.
Automatically loads the persistent MITM CA during initialization.
Changes the install and uninstall timeout default to 120 seconds.
Requires an explicit path; the implicit vendored-executable fallback is removed. Pass VENDORED_SRT_WIN_EXE to use the packaged binary.
The HTTP CONNECT proxy is now advertised in GRPC_PROXY instead of socks5h.
The Linux secure bwrap branch now forces --unshare-user and --cap-drop ALL.
Removes same-user mode, including its exec, WFP, and group behavior.
The TypeScript layer now supports sandbox-user as the only mode.
Windows filesystem access uses disk-is-truth file denial, a parent allow-list, and a hash-ACE seal.
Windows exec fails closed when WFP filters are absent.
Tightens leaf certificate validity to 99 days, anchored at notBefore.
Restricts loopback permits to a fixed port range.
Security 44
Warns when the package is installed where a sandboxed command can write it.
On Linux, glob denies now cover descendants on file systems whose directory listings provide no entry types.
Adds opt-in controls to strip response headers, refuse opaque tunnels, and require a Host match.
Processes ending with process.exit() and failed initialize() calls no longer leave library objects, including generated CA keys, in the temp directory.
A path entry containing glob characters is also read as the path it spells, where that path exists, so denies through such folders apply.
Binds a deny path created by another sandbox while the wrapper is looking.
The CLI refuses an unusable control fd or settings file and keeps the fd out of the sandbox.
Linux pins ancestor directories of deny binds to prevent them from being renamed.
Linux keeps a masked file masked when it is a write path or is listed through a symlinked directory.
Forged attribution keys are sanitized, and the Linux monitor receives bubblewrap's write rules.
Unregistered attribution keys are sanitized in every violation producer.
A JVM agent makes Java tools honor the sandbox proxy and credential.
Glob denyRead entries remain denied inside allowRead regions on macOS.
Installation adds write-deny stamps on world-writable system directories.
ACL grant and revoke operations preserve SE_DACL_PROTECTED on Windows.
Decoded proxy commands are sanitized.
Violation lines are sanitized at ingestion.
Query strings are redacted on proxy deny lines.
Persists the MITM CA under the protected state directory using atomic writes and validates its notBefore and notAfter values.
Deny targets that do not yet exist are materialized as placeholders and stamped, closing the create-past-a-deny hole.
Adds claim-level masking inside decoded JWTs, allowing selected claims to be masked.
Adds claim masking for environment variables holding JWTs.
Masked credentials are now substituted in request bodies at the TLS-terminating proxy.
Adds extract for structured masking of environment variable values.
Adds a passive Linux observer for sandbox violations using seccomp USER_NOTIF.
Adds GIT_CONFIG_* injection for safe.directory and Schannel.
Adds environment-based CA trust for TLS termination without using the certificate store.
Windows srt-win performs a behavioral egress-block probe during initialize().
Windows adds a per-session working-tree grant and full filesystem allow/deny under the sandbox user.
Adds per-exec file-read denial on Windows.
Adds per-exec file-write denial on Windows.
Installation provisions a sandbox user and user-SID WFP as a v2 foundation.
Credential files support mode "mask", which masks the whole file with sentinel content and binds it read-only over the real path.
Windows now wires denyWrite to srt-win ACLs.
Per-host excludeDomains lets tlsTerminate skip MITM for mTLS or pinned hosts.
Environment variables support mode:"mask", which uses a sentinel in the sandbox and injects the real value at the proxy.
The egress allowlist remains enforced when allowLocalBinding is set.
Adds configuration to deny credential files and environment variables inside the sandbox.
Adds deny-all as a network restriction option.
Re-applies denyRead file masks after a denyWrite ancestor bind.
Authenticates the loopback proxy.
Adds strictAllowlist as a network restriction option.
Fixes a header bypass on the TLS-terminating proxy.
Runs commands with a restricted token, job, and hardening stack.
New APIs and options 41
On Linux, enables nested user namespaces for the configuration or a single wrap; by default sandboxed commands cannot create their own user or mount namespaces.
Adds askCallbackDenyReason as a member of ISandboxManager.
Can rewrite and observe requests: allows may set or remove headers and provide onResponse, denies may choose a status, and the callback receives request and connection details.
Selects how filterRequest handles a target that names another path after normalization: refuse, preserve its spelling, or normalize it.
TLS termination runs in-process on the tunnel socket; maxTunnels defaults to 256 and handshakeTimeoutMs defaults to 10000.
Adds a new package export named realPathOf.
Adds methods to register and unregister per-command network allow lists of allowed domains.
Adds a standalone HTTP proxy with an external decider process that decides every request; it is also available as a single-file srt-proxy.
A path entry with literal: true is treated as a name regardless of its characters, in any of the four filesystem path lists.
The four filesystem path lists now use FilesystemPathEntry[], defined as string or { path: string; literal: true }, instead of string[].
writeRootsOf() gives every write root.
Adds commandId for command attribution.
Adds a per-exec commandLabel for attributing violations to a command.
Adds commandText for command attribution.
Adds per-entry deniedDomainReasons for model-facing deny reasons.
Allowed and denied domains can include an optional port suffix.
Adds the asynchronous checkDependenciesAsync API while leaving the synchronous API unchanged.
Adds checkWindowsSandboxStatus and a single-spawn srt-win status --json check.
Exports generateCa for working with the persistent MITM CA.
Adds configuration for safe.directory without write grants, fixing dubious-ownership errors on subdirectory launches.
Adds a typed mapped_drive_cwd error with exit code 16 for network-drive working directories; the broker does not stat UNC literals.
Exports validateCaPair for validating the MITM CA pair.
Exports the packaged Windows executable path for callers that want to use the vendored binary.
Adds typed Windows sandbox error codes and a .subcommand property.
Adds a decode option for encoded credential formats, starting with JWT, including environment variables holding JWTs.
Adds the --quiet option to exec.
Adds lib::run_from_args for invoking the Windows runtime from arguments.
Lets users name the provisioned Windows account.
Adds the Windows configuration schema with an argv[1] sentinel multicall override.
Adds an option to also mask captured values outside regex matches.
Adds extraCaCertPaths to configure site-local CA roots for TLS termination.
Adds an option to control credential file extract behavior when there is no match.
Adds structured extract regex support for masked credential files.
Adds a two-hop runner under the sandbox user.
The TLS-terminating proxy adds gcloud and Nix CA trust environment variables.
Set filesystem.disabled to disable the filesystem policy.
The npm release ships a prebuilt srt-win.exe for each architecture.
Git Bash is now supported as a first-class inner shell for srt-win exec.
Adds an opt-in option to allow Apple Events on macOS.
Adds the group subcommand to srt-win.
Sets up the group and WFP in a single step.
Performance 7
Compiles a read rule once and reads brackets in linear time.
On Linux, expanding denyRead and allowRead patterns is about six times faster and uses less memory; rules in one configuration share directory listings.
An unlistable directory is tried once per wrap rather than once per rule, and read lists hold each path once.
On Linux, pattern expansion gives the event loop a turn every 10 ms and stops when the AbortSignal passed to wrapWithSandbox() is aborted.
Linux walks each directory in a read-deny glob once instead of once per name.
The TLS-terminate upstream connection is kept alive per client connection.
The generated macOS sandbox profile is approximately 6–10 times smaller.
Behavior and default changes 15
A refused CONNECT response includes the refusal reason in its 403 status phrase.
Warnings now also identify a credentials.files deny whose pattern is skipped.
Unmatched or empty brackets are treated as literal text, while valid character sets remain patterns; Windows drive and share roots also work as glob bases.
On Linux, a wrap uses one configuration and working directory; if updateConfig(), initialize() or chdir() runs during wrapping, it restarts and rereads disk, then finishes without yielding after two restarts.
Linux collapses read-deny globs to directories and mounts denies where paths resolve.
SSH deny reasons are provided in-band.
Proxy denials are recorded in SandboxViolationStore.
A trailing slash marks a deny target as a directory.
Serves an empty CRL for Schannel and other revocation-checking clients.
Windows now wires denyRead to srt-win ACLs.
HTTP and SOCKS proxies can be served on a single port using first-byte sniffing.
Leaf certificates generated by the TLS-terminating proxy include SKI/AKI extensions.
TypeScript owns generateProxyEnvVars, and srt-win exec passes the variables through.
Sets up the group and WFP in a single step.
SandboxManager is wired to the srt-win network sandbox.
Tooling 1
Adds the wfp subcommand to srt-win.
Fixes and other changes 38
Deep imports globToRegex and denyGlobRegex moved to this file; neither function is a package export.
Git fetch and push now work through the macOS sandbox proxy.
An upstream response larger than its Content-Length no longer causes the entire response to be lost.
A backend-failure 502 is sent in a tunnel only if no response has yet gone back to the client.
Generated certificate serial numbers no longer begin with a zero byte, avoiding rejection by strict parsers.
bubblewrap 0.4 starts again by using one mount per destination.
Binaries built with bun build --compile start again.
The proxy answers 502 Bad Gateway when an upstream responds with an invalid status line or header, rather than throwing and ending the process.
On Linux, a sandboxed command starts only after both in-sandbox relays are listening, preventing its first network call from being refused.
Fixes exit status handling under zsh.
Linux passes over-long bubblewrap profiles through --args so they can be run.
Linux throws a typed error when the bubblewrap profile cannot be run.
Linux removes the deny mount point left on the host by a killed process.
On macOS, a path computed by the library is denied as a literal rather than interpreted as a pattern.
Re-applying a Linux read-deny tmpfs restores read-only behavior, allowing the write deny above it to take precedence.
srt exits after the command when --control-fd is a pipe.
CONNECT clients that abandon a slow permission decision are closed.
The proxy routes and dials the canonical host rather than the client's spelling.
IPv6 literals in allowed and denied domain entries are handled with bracket awareness.
Non-glob path spellings have trailing slashes stripped during normalization.
Clients that cannot be authenticated receive legible refusal messages.
The sandbox now starts when the helper binary is execute-only.
The proxy now honors ignoreViolations.
Skip creating stubs for absent deny paths under a read-only denied directory.
The proxy survives client aborts while preserving abort semantics end-to-end.
Resolves symlinks in deny paths before computing bwrap masks.
The proxy environment overlay no longer includes NO_PROXY on Windows.
Retries password generation when Windows reports NERR_PasswordTooShort, covering any password policy violation.
On schema mismatch, Windows preserves state.db as .bak instead of dropping the table.
Stops corrupting every ! in wrapped commands into \!.
Drops .local from NO_PROXY so *.local traffic routes via the proxy.
Restores the dropped files declaration in getCredentialRestrictions.
Normalizes absolute-form request-targets in the TLS-terminating proxy.
TMPDIR is left untouched when filesystem.disabled is true.
Preserves an explicitly empty allowlist in getNetworkRestrictionConfig.
Re-emits denyRead paths nested under allowRead on macOS.
Prevents denyWrite from unmasking denyRead tmpfs directories.
Disables SSH connection multiplexing in the injected command.