claude_code_settings/sandbox.rs
1//! `sandbox`: the sandboxed Bash environment.
2
3use alloc::collections::BTreeMap;
4use alloc::string::String;
5use alloc::vec::Vec;
6
7use serde::{Deserialize, Serialize};
8
9use crate::Extra;
10use crate::enums::{CredentialMode, ExtractNoMatch, Platform, Sigv4Action, TokenDecode};
11use crate::walk::walk;
12
13/// `sandbox`.
14///
15/// Isolate the Bash commands Claude runs from your filesystem and network with
16/// [sandboxing](https://code.claude.com/docs/en/sandboxing). Turn the sandbox on with
17/// `enabled`, then narrow or widen what sandboxed commands can touch with the `filesystem`,
18/// `network`, and `credentials` sub-objects.
19///
20/// Docs: [`sandbox`](https://code.claude.com/docs/en/settings-reference#sandbox).
21#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
22#[serde(rename_all = "camelCase")]
23#[non_exhaustive]
24pub struct Sandbox {
25 /// Turn on [sandboxing](https://code.claude.com/docs/en/sandboxing) for Bash commands. When
26 /// you pick a mode in the `/sandbox` panel, Claude Code writes this key to
27 /// `.claude/settings.local.json` for the current project; set it in
28 /// `~/.claude/settings.json` to sandbox every project.
29 ///
30 /// - **Values**: Boolean
31 /// - `true`: Claude Code sandboxes Bash commands
32 /// - `false`: Bash commands run unsandboxed
33 /// - **Default**: `false`
34 /// - **Scope**: any settings file, with [limits on project and local
35 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
36 ///
37 /// Docs: [`enabled`](https://code.claude.com/docs/en/settings-reference#sandbox-enabled).
38 #[serde(skip_serializing_if = "Option::is_none")]
39 pub enabled: Option<bool>,
40 /// Let Claude Code run sandboxed Bash commands without a permission prompt. Commands that
41 /// can't run in the sandbox still go through the regular permission flow, and `deny` rules
42 /// and content-scoped `ask` rules such as `Bash(git push *)` still apply; a bare `Bash` ask
43 /// rule is skipped for sandboxed commands. Set it to `false` to send sandboxed commands
44 /// through the regular permission flow too, which the `/sandbox` **Mode** tab calls regular
45 /// permissions mode.
46 ///
47 /// - **Values**: Boolean
48 /// - `true`: Claude Code runs sandboxed Bash commands without a permission prompt, except
49 /// in the cases that [Auto-allow
50 /// mode](https://code.claude.com/docs/en/sandboxing#auto-allow-mode) describes;
51 /// `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` turns auto-allow off
52 /// - `false`: sandboxed commands go through the regular permission flow, so your allow
53 /// rules and permission mode decide. The `/sandbox` **Mode** tab calls this regular
54 /// permissions mode
55 /// - **Default**: `true`
56 /// - **Scope**: any settings file.
57 ///
58 /// Docs: [`autoAllowBashIfSandboxed`](https://code.claude.com/docs/en/settings-reference#sandbox-autoallowbashifsandboxed).
59 #[serde(skip_serializing_if = "Option::is_none")]
60 pub auto_allow_bash_if_sandboxed: Option<bool>,
61 /// Name commands that Claude Code runs outside the sandbox, such as tools that don't work
62 /// under it. Each entry uses the same syntax as the content of a `Bash(...)` [permission
63 /// rule](https://code.claude.com/docs/en/permissions#permission-rule-syntax): an exact
64 /// command, a prefix such as `docker *`, or a wildcard pattern. A pattern with no wildcard
65 /// is an exact match, so `docker` matches only `docker` with no arguments.
66 ///
67 /// - **Values**: array of command patterns
68 /// - **Default**: unset, so no command is excluded
69 /// - **Scope**: any settings file, with [limits on project and local
70 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
71 ///
72 /// Docs: [`excludedCommands`](https://code.claude.com/docs/en/settings-reference#sandbox-excludedcommands).
73 #[serde(skip_serializing_if = "Option::is_none")]
74 pub excluded_commands: Option<Vec<String>>,
75 /// Let Claude retry a command outside the sandbox with the `dangerouslyDisableSandbox`
76 /// parameter after the sandbox blocks it. When it's `false`, Claude Code ignores that
77 /// parameter. While the sandbox is running, commands Claude runs are then sandboxed unless
78 /// they match an
79 /// [`excludedCommands`](https://code.claude.com/docs/en/settings-reference#sandbox-excludedcommands)
80 /// entry.
81 ///
82 /// - **Values**: Boolean
83 /// - `true`: Claude can retry a command outside the sandbox with the
84 /// `dangerouslyDisableSandbox` parameter after the sandbox blocks it
85 /// - `false`: Claude Code ignores that parameter, so while the sandbox is running,
86 /// commands Claude runs are sandboxed unless they match an `excludedCommands` entry
87 /// - **Default**: `true`
88 /// - **Scope**: any settings file, with [a limit on project and local
89 /// settings](https://code.claude.com/docs/en/sandboxing#turn-off-the-retry-with-strict-sandbox-mode).
90 ///
91 /// Docs: [`allowUnsandboxedCommands`](https://code.claude.com/docs/en/settings-reference#sandbox-allowunsandboxedcommands).
92 #[serde(skip_serializing_if = "Option::is_none")]
93 pub allow_unsandboxed_commands: Option<bool>,
94 /// Silence sandbox violation reports for paths you expect a command to probe and be
95 /// refused, such as a tool that checks `/etc/hosts` on startup, so those denials don't show
96 /// up as violations or in what Claude sees. The sandbox still blocks the access; only the
97 /// report is suppressed. Keys are substrings to match against the command, with `*`
98 /// matching every command, and values are substrings of the violation to ignore for that
99 /// command, such as a filesystem path.
100 ///
101 /// - **Values**: object mapping a command substring to an array of violation substrings,
102 /// usually paths
103 /// - **Default**: unset, so every violation is reported
104 /// - **Scope**: any settings file, with [limits on project and local
105 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
106 ///
107 /// Docs: [`ignoreViolations`](https://code.claude.com/docs/en/settings-reference#sandbox-ignoreviolations).
108 #[serde(skip_serializing_if = "Option::is_none")]
109 pub ignore_violations: Option<BTreeMap<String, Vec<String>>>,
110 /// Control which hosts, ports, and sockets sandboxed commands can reach. The sandbox routes
111 /// outbound traffic through a proxy that enforces these lists; see [Network
112 /// isolation](https://code.claude.com/docs/en/sandboxing#network-isolation) for how the
113 /// proxy decides and when it prompts.
114 ///
115 /// - **Values**: object with the sub-keys below
116 /// - **Default**: unset, so no domains are pre-allowed and your permission mode decides
117 /// [what happens to each new
118 /// host](https://code.claude.com/docs/en/sandboxing#hosts-outside-your-allowed-domains)
119 /// - **Scope**: any settings file. `strictAllowlist`, `allowManagedDomainsOnly`, and
120 /// `tlsTerminate` are read from fewer sources, as their entries say.
121 ///
122 /// Docs: [`network`](https://code.claude.com/docs/en/settings-reference#sandbox-network).
123 #[serde(skip_serializing_if = "Option::is_none")]
124 pub network: Option<SandboxNetwork>,
125 /// Control which paths sandboxed commands can read and write. By default they can write to
126 /// the working directory, the per-user temp directory, and directories you add with
127 /// `--add-dir`, `/add-dir`, or `permissions.additionalDirectories`, and can read the rest
128 /// of the filesystem, including credential files. Widen or narrow that with the four path
129 /// lists, or switch the filesystem layer off with `disabled`.
130 ///
131 /// - **Values**: object with `allowWrite`, `denyWrite`, `denyRead`, and `allowRead` arrays,
132 /// plus the `allowManagedReadPathsOnly` and `disabled` Booleans
133 /// - **Default**: unset, so the default read and write boundaries apply
134 /// - **Scope**: any settings file.
135 ///
136 /// Docs: [`filesystem`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem).
137 #[serde(skip_serializing_if = "Option::is_none")]
138 pub filesystem: Option<SandboxFilesystem>,
139 /// Declare the credential files and environment variables to [protect from sandboxed
140 /// commands](https://code.claude.com/docs/en/sandboxing#protect-credentials). Each entry
141 /// names a file `path` or a variable `name` and a `mode`: `deny` hides the credential
142 /// inside the sandbox, and `mask` shows sandboxed commands a placeholder while the [sandbox
143 /// proxy](https://code.claude.com/docs/en/sandboxing#mask-credentials) substitutes the real
144 /// value on outbound requests. Claude Code protects only the entries you list; there is no
145 /// built-in credential deny list.
146 ///
147 /// - **Values**: object with `files`, `envVars`, `allowPlaintextInject`, `awsPairs`, and
148 /// `sigv4`
149 /// - **Default**: unset, so no credentials are protected
150 /// - **Scope**: any settings file. Claude Code honors `mask` entries,
151 /// `allowPlaintextInject`, `awsPairs`, and `sigv4` only from user settings, managed
152 /// settings, and the `--settings` flag.
153 ///
154 /// Docs: [`credentials`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials).
155 #[serde(skip_serializing_if = "Option::is_none")]
156 pub credentials: Option<SandboxCredentials>,
157 /// Point the sandbox at a ripgrep binary of your own instead of the one Claude Code uses,
158 /// for example when your platform needs a differently built `rg`.
159 ///
160 /// - **Values**: object with `command`, the path to the ripgrep binary, and optional
161 /// `args`, an array of arguments to prepend
162 /// - **Default**: unset, so the sandbox uses the same ripgrep binary as Claude Code. That
163 /// is the bundled binary unless you set
164 /// [`USE_BUILTIN_RIPGREP`](https://code.claude.com/docs/en/env-vars) to `0`
165 /// - **Scope**: user or managed.
166 ///
167 /// Docs: [`ripgrep`](https://code.claude.com/docs/en/settings-reference#sandbox-ripgrep).
168 #[serde(skip_serializing_if = "Option::is_none")]
169 pub ripgrep: Option<Ripgrep>,
170 /// Let sandboxed commands on macOS reach the system TLS trust service,
171 /// `com.apple.trustd.agent`. Go-based tools such as `gh`, `gcloud`, and `terraform` need it
172 /// to verify TLS certificates when you use
173 /// [`network.httpProxyPort`](https://code.claude.com/docs/en/settings-reference#sandbox-network-httpproxyport)
174 /// with a MITM proxy and a custom CA. This reduces security by opening a potential data
175 /// exfiltration path through the trust service.
176 ///
177 /// - **Values**: Boolean
178 /// - `true`: sandboxed commands on macOS can reach `com.apple.trustd.agent`
179 /// - `false`: sandboxed commands on macOS can't reach the system TLS trust service
180 /// - **Default**: `false`
181 /// - **Scope**: any settings file, with [limits on project and local
182 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
183 ///
184 /// Docs: [`enableWeakerNetworkIsolation`](https://code.claude.com/docs/en/settings-reference#sandbox-enableweakernetworkisolation).
185 #[serde(skip_serializing_if = "Option::is_none")]
186 pub enable_weaker_network_isolation: Option<bool>,
187 /// Run the Linux sandbox inside an unprivileged Docker container, where bubblewrap can't
188 /// mount a fresh `/proc`. Instead the inner sandbox bind-mounts the container's existing
189 /// `/proc`, which exposes process information that a fresh mount would hide. This reduces
190 /// security; use it only when the outer container already provides the isolation you need.
191 ///
192 /// - **Values**: Boolean
193 /// - `true`: the inner sandbox bind-mounts the container's existing `/proc` instead of
194 /// mounting a fresh one
195 /// - `false`: the sandbox mounts a fresh `/proc`, which doesn't work in an unprivileged
196 /// Docker container
197 /// - **Default**: `false`
198 /// - **Scope**: any settings file, with [limits on project and local
199 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
200 ///
201 /// Docs: [`enableWeakerNestedSandbox`](https://code.claude.com/docs/en/settings-reference#sandbox-enableweakernestedsandbox).
202 #[serde(skip_serializing_if = "Option::is_none")]
203 pub enable_weaker_nested_sandbox: Option<bool>,
204 /// Point the sandbox at a bubblewrap binary installed outside `PATH`, such as a vendored
205 /// copy on an air-gapped host. Claude Code uses the path both for the startup dependency
206 /// check and when it wraps each sandboxed command.
207 ///
208 /// - **Values**: string, an absolute path; Claude Code drops a relative path and falls back
209 /// to `PATH` lookup
210 /// - **Default**: unset, so Claude Code finds `bwrap` on `PATH`
211 /// - **Scope**: managed. Claude Code reads it only from managed settings so that a user,
212 /// project, or local file can't point the sandbox at a different binary.
213 ///
214 /// Docs: [`bwrapPath`](https://code.claude.com/docs/en/settings-reference#sandbox-bwrappath).
215 #[serde(skip_serializing_if = "Option::is_none")]
216 pub bwrap_path: Option<String>,
217 /// Point the sandbox network proxy at a `socat` binary installed outside `PATH`.
218 ///
219 /// - **Values**: string, an absolute path; Claude Code drops a relative path and falls back
220 /// to `PATH` lookup
221 /// - **Default**: unset, so Claude Code finds `socat` on `PATH`
222 /// - **Scope**: managed.
223 ///
224 /// Docs: [`socatPath`](https://code.claude.com/docs/en/settings-reference#sandbox-socatpath).
225 #[serde(skip_serializing_if = "Option::is_none")]
226 pub socat_path: Option<String>,
227 /// Make Claude Code exit with an error at startup when `sandbox.enabled` is `true` but the
228 /// sandbox can't start because the platform doesn't support it or the dependency check
229 /// fails. Without this key, Claude Code runs commands unsandboxed. Managed deployments that
230 /// require sandboxing as a security gate can use this setting.
231 ///
232 /// - **Values**: Boolean
233 /// - `true`: Claude Code exits with an error at startup when `sandbox.enabled` is `true`
234 /// but the sandbox can't start. If the sandbox passes that check and then fails to
235 /// initialize, the session keeps running and Claude Code [refuses each sandboxed
236 /// command](https://code.claude.com/docs/en/sandboxing#commands-refused-with-sandbox-is-required)
237 /// - `false`: Claude Code runs commands unsandboxed when the sandbox can't start
238 /// - **Default**: `false`
239 /// - **Scope**: any settings file, with [limits on project and local
240 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
241 ///
242 /// Docs: [`failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable).
243 #[serde(skip_serializing_if = "Option::is_none")]
244 pub fail_if_unavailable: Option<bool>,
245 /// Limit the entire sandbox configuration to the listed platforms. On platforms not in the
246 /// list the sandbox config is inert: no sandbox, no auto-allow, no startup warning, and no
247 /// failIfUnavailable exit. When omitted, all supported platforms are included.
248 ///
249 /// - **Values**: array of strings
250 /// - **Default**: unset
251 ///
252 /// Docs: [`enabledPlatforms`](https://code.claude.com/docs/en/settings-reference#sandbox).
253 #[serde(skip_serializing_if = "Option::is_none")]
254 pub enabled_platforms: Option<Vec<Platform>>,
255 /// Let sandboxed commands on macOS send Apple Events, which `open`, `osascript`, and tools
256 /// that open URLs in a browser need; without it they fail with error `-600`. This removes
257 /// code-execution isolation: sandboxed commands can launch other applications unsandboxed
258 /// with no user prompt, and can send AppleScript commands to running applications such as
259 /// Terminal, subject to the per-app macOS automation-consent prompt (TCC).
260 ///
261 /// - **Values**: Boolean
262 /// - `true`: sandboxed commands on macOS can send Apple Events
263 /// - `false`: sandboxed commands on macOS can't send Apple Events, so `open` and
264 /// `osascript` fail with error `-600`
265 /// - **Default**: `false`
266 /// - **Scope**: user or managed.
267 ///
268 /// Docs: [`allowAppleEvents`](https://code.claude.com/docs/en/settings-reference#sandbox-allowappleevents).
269 #[serde(skip_serializing_if = "Option::is_none")]
270 pub allow_apple_events: Option<bool>,
271 /// Let sandboxed commands on Linux and WSL2 create user namespaces, which Chromium's and
272 /// Electron's own sandbox, a nested bubblewrap, and `unshare` need. If you set this key to
273 /// `true`, you turn off a security boundary: code from a sandboxed command can end up
274 /// running outside the sandbox. For rootless Podman or Buildah, use
275 /// [`excludedCommands`](https://code.claude.com/docs/en/settings-reference#sandbox-excludedcommands)
276 /// instead, because the sandbox stops them in other ways too.
277 ///
278 /// - **Values**: Boolean
279 /// - `true`: sandboxed commands can create user namespaces
280 /// - `false`: this key allows nothing extra, and the sandbox's default applies
281 /// - **Default**: `false`
282 /// - **Scope**: user or managed. A `true` counts from `~/.claude/settings.json`, JSON
283 /// passed with `--settings`, or [managed
284 /// settings](https://code.claude.com/docs/en/managed-settings).
285 ///
286 /// Docs: [`allowNestedUserNamespaces`](https://code.claude.com/docs/en/settings-reference#sandbox-allownestedusernamespaces).
287 #[serde(skip_serializing_if = "Option::is_none")]
288 pub allow_nested_user_namespaces: Option<bool>,
289 /// Keys Claude Code accepts here that this crate doesn't model (newer or
290 /// undocumented ones), kept as written so the document round-trips.
291 #[serde(flatten)]
292 pub extra: Extra,
293}
294
295/// `sandbox.network`.
296///
297/// Control which hosts, ports, and sockets sandboxed commands can reach. The sandbox routes
298/// outbound traffic through a proxy that enforces these lists; see [Network
299/// isolation](https://code.claude.com/docs/en/sandboxing#network-isolation) for how the proxy
300/// decides and when it prompts.
301///
302/// Docs: [`sandbox.network`](https://code.claude.com/docs/en/settings-reference#sandbox-network).
303#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
304#[serde(rename_all = "camelCase")]
305#[non_exhaustive]
306pub struct SandboxNetwork {
307 /// Pre-allow domains for outbound traffic from sandboxed commands, so the sandbox doesn't
308 /// prompt for them. Wildcards such as `*.example.com` match subdomains, and an optional
309 /// `:port` suffix limits an entry to one port; an entry without a port matches every port.
310 ///
311 /// - **Values**: array of strings, each a domain, wildcard pattern, or IP literal, with an
312 /// optional `:port` suffix
313 /// - **Default**: unset, so your permission mode decides [what happens to each new
314 /// host](https://code.claude.com/docs/en/sandboxing#hosts-outside-your-allowed-domains)
315 /// - **Scope**: any settings file, with [limits on project and local
316 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
317 /// Only managed settings when allowmanageddomainsonly is set.
318 ///
319 /// Docs: [`allowedDomains`](https://code.claude.com/docs/en/settings-reference#sandbox-network-alloweddomains).
320 #[serde(skip_serializing_if = "Option::is_none")]
321 pub allowed_domains: Option<Vec<String>>,
322 /// Block domains for outbound traffic from sandboxed commands, using the same wildcard,
323 /// port, and IPv6 syntax as
324 /// [`allowedDomains`](https://code.claude.com/docs/en/settings-reference#sandbox-network-alloweddomains).
325 /// A denied domain stays blocked even when an `allowedDomains` entry matches it too.
326 ///
327 /// - **Values**: array of strings, each a domain, wildcard pattern, or IP literal, with an
328 /// optional `:port` suffix
329 /// - **Default**: unset
330 /// - **Scope**: any settings file.
331 ///
332 /// Docs: [`deniedDomains`](https://code.claude.com/docs/en/settings-reference#sandbox-network-denieddomains).
333 #[serde(skip_serializing_if = "Option::is_none")]
334 pub denied_domains: Option<Vec<String>>,
335 /// Lock the network allowlist to what managed settings define. Claude Code then honors only
336 /// `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings, ignores
337 /// domains from user, project, local, and `--settings` settings, and blocks a non-allowed
338 /// domain automatically instead of prompting.
339 ///
340 /// - **Values**: Boolean
341 /// - `true`: Claude Code honors only `allowedDomains` and `WebFetch(domain:...)` allow
342 /// rules from managed settings and blocks a non-allowed domain instead of prompting
343 /// - `false`: domains from other settings files can merge into the allowlist
344 /// - **Default**: `false`
345 /// - **Scope**: managed.
346 ///
347 /// Docs: [`allowManagedDomainsOnly`](https://code.claude.com/docs/en/settings-reference#sandbox-network-allowmanageddomainsonly).
348 #[serde(skip_serializing_if = "Option::is_none")]
349 pub allow_managed_domains_only: Option<bool>,
350 /// List the Unix socket paths sandboxed commands can connect to on macOS. Claude Code
351 /// ignores this list on Linux and WSL2, where the seccomp filter can't inspect socket
352 /// paths; use
353 /// [`allowAllUnixSockets`](https://code.claude.com/docs/en/settings-reference#sandbox-network-allowallunixsockets)
354 /// there instead.
355 ///
356 /// - **Values**: array of strings, each a socket path
357 /// - **Default**: unset, so the macOS sandbox blocks every Unix socket
358 /// - **Scope**: any settings file, with [limits on project and local
359 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
360 ///
361 /// Docs: [`allowUnixSockets`](https://code.claude.com/docs/en/settings-reference#sandbox-network-allowunixsockets).
362 #[serde(skip_serializing_if = "Option::is_none")]
363 pub allow_unix_sockets: Option<Vec<String>>,
364 /// Let sandboxed commands connect to every Unix socket. On Linux and WSL2, the sandbox's
365 /// [seccomp filter](https://code.claude.com/docs/en/sandboxing#set-up-linux-and-wsl2)
366 /// blocks `socket(AF_UNIX, ...)` calls, so this is the only way to permit Unix sockets
367 /// there. When the filter is missing, which `/sandbox` reports on its Dependencies tab, the
368 /// sandbox doesn't block Unix-socket calls.
369 ///
370 /// - **Values**: Boolean
371 /// - `true`: sandboxed commands can connect to every Unix socket. On Linux and WSL2 they
372 /// can also connect to VM sockets, the `AF_VSOCK` address family
373 /// - `false`: the sandbox blocks Unix-socket connections: on macOS except the paths in
374 /// `allowUnixSockets`, and on Linux and WSL2 through the seccomp filter when it's
375 /// present
376 /// - **Default**: `false`
377 /// - **Scope**: any settings file, with [limits on project and local
378 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
379 ///
380 /// Docs: [`allowAllUnixSockets`](https://code.claude.com/docs/en/settings-reference#sandbox-network-allowallunixsockets).
381 #[serde(skip_serializing_if = "Option::is_none")]
382 pub allow_all_unix_sockets: Option<bool>,
383 /// Let sandboxed commands on macOS listen on network ports, for example to start a dev
384 /// server, and connect to any port on localhost. A command that listens on a non-loopback
385 /// address accepts connections from other machines. The key has no effect on Linux and
386 /// WSL2, where each sandboxed command has its own loopback interface.
387 ///
388 /// - **Values**: Boolean
389 /// - `true`: sandboxed commands on macOS can listen on any local address and connect to
390 /// any port on localhost
391 /// - `false`: sandboxed commands on macOS can't listen on a port or connect directly to
392 /// servers on localhost
393 /// - **Default**: `false`
394 /// - **Scope**: any settings file, with [limits on project and local
395 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
396 ///
397 /// Docs: [`allowLocalBinding`](https://code.claude.com/docs/en/settings-reference#sandbox-network-allowlocalbinding).
398 #[serde(skip_serializing_if = "Option::is_none")]
399 pub allow_local_binding: Option<bool>,
400 /// List additional XPC and Mach service names the macOS sandbox may look up. Tools that
401 /// communicate over XPC, such as the iOS Simulator or Playwright, need their services
402 /// listed here. Sandboxed commands can reach outside the sandbox to each service that you
403 /// list, and the sandbox [doesn't confine what those services do for those
404 /// commands](https://code.claude.com/docs/en/sandboxing#security-limitations).
405 ///
406 /// - **Values**: array of strings, each a service name; a single trailing `*` matches a
407 /// prefix, and `"*"` alone matches every service
408 /// - **Default**: unset
409 /// - **Scope**: any settings file, with [limits on project and local
410 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
411 ///
412 /// Docs: [`allowMachLookup`](https://code.claude.com/docs/en/settings-reference#sandbox-network-allowmachlookup).
413 #[serde(skip_serializing_if = "Option::is_none")]
414 pub allow_mach_lookup: Option<Vec<String>>,
415 /// Point the sandbox at your own HTTP proxy instead of the one Claude Code runs.
416 /// Organizations do this to inspect HTTPS traffic, apply their own filtering rules, or log
417 /// requests. Your proxy takes over filtering, and Claude Code stops applying its domain
418 /// lists and network prompts to traffic sent there.
419 ///
420 /// - **Values**: number, a local TCP port
421 /// - **Default**: unset, so Claude Code runs its own proxy
422 /// - **Scope**: any settings file, unless [other sandbox settings limit which files can set
423 /// a port](https://code.claude.com/docs/en/sandboxing#custom-proxy-configuration).
424 ///
425 /// Docs: [`httpProxyPort`](https://code.claude.com/docs/en/settings-reference#sandbox-network-httpproxyport).
426 #[serde(skip_serializing_if = "Option::is_none")]
427 pub http_proxy_port: Option<u16>,
428 /// Point the sandbox at your own SOCKS5 proxy instead of the one Claude Code runs. Your
429 /// proxy takes over filtering, and Claude Code stops applying its domain lists and network
430 /// prompts to traffic sent there. When unset, Claude Code starts its own proxy for SOCKS
431 /// traffic.
432 ///
433 /// - **Values**: number, a local TCP port
434 /// - **Default**: unset, so Claude Code runs its own proxy
435 /// - **Scope**: any settings file, unless [other sandbox settings limit which files can set
436 /// a port](https://code.claude.com/docs/en/sandboxing#custom-proxy-configuration).
437 ///
438 /// Docs: [`socksProxyPort`](https://code.claude.com/docs/en/settings-reference#sandbox-network-socksproxyport).
439 #[serde(skip_serializing_if = "Option::is_none")]
440 pub socks_proxy_port: Option<u16>,
441 /// Make the sandbox proxy terminate TLS so it can read the contents of HTTPS requests. This
442 /// is experimental, and `mask` [credential
443 /// substitution](https://code.claude.com/docs/en/sandboxing#mask-credentials) requires it.
444 /// Set `{}` to generate an ephemeral certificate authority for the session, or set
445 /// `caCertPath` and `caKeyPath` to use your own.
446 ///
447 /// - **Values**: object with optional `caCertPath` and `caKeyPath` strings, each a file
448 /// path
449 /// - **Default**: unset, so the proxy doesn't terminate or inspect TLS
450 /// - **Scope**: user or managed. A repository can't switch it on or supply a certificate
451 /// authority.
452 ///
453 /// Docs: [`tlsTerminate`](https://code.claude.com/docs/en/settings-reference#sandbox-network-tlsterminate).
454 #[serde(skip_serializing_if = "Option::is_none")]
455 pub tls_terminate: Option<TlsTerminate>,
456 /// Deny sandboxed commands access to hosts outside the allowlist instead of prompting for
457 /// approval. The allowlist is
458 /// [`allowedDomains`](https://code.claude.com/docs/en/settings-reference#sandbox-network-alloweddomains)
459 /// plus domains from `WebFetch(domain:...)` allow rules, or only the managed settings
460 /// entries when
461 /// [`allowManagedDomainsOnly`](https://code.claude.com/docs/en/settings-reference#sandbox-network-allowmanageddomainsonly)
462 /// is set. [Locks that apply without an admin-required
463 /// sandbox](https://code.claude.com/docs/en/sandboxing#locks-that-apply-without-an-admin-required-sandbox)
464 /// covers a repository's entries.
465 ///
466 /// - **Values**: Boolean
467 /// - `true`: Claude Code denies sandboxed commands access to hosts outside the allowlist
468 /// - `false`: unless another trusted settings file sets `true`, Claude Code decides a
469 /// host outside the allowlist by permission mode instead of denying it outright: in
470 /// auto mode it checks the host against the command's [per-command allowed
471 /// domains](https://code.claude.com/docs/en/sandboxing#per-command-allowed-domains-in-auto-mode),
472 /// in `dontAsk` mode it denies, in `bypassPermissions` mode and in interactive terminal
473 /// plan-mode sessions where bypass is available it allows, and otherwise it asks you
474 /// - **Default**: `false`
475 /// - **Scope**: user or managed. A repository can't turn it on or off.
476 ///
477 /// Docs: [`strictAllowlist`](https://code.claude.com/docs/en/settings-reference#sandbox-network-strictallowlist).
478 #[serde(skip_serializing_if = "Option::is_none")]
479 pub strict_allowlist: Option<bool>,
480 /// Keys Claude Code accepts here that this crate doesn't model (newer or
481 /// undocumented ones), kept as written so the document round-trips.
482 #[serde(flatten)]
483 pub extra: Extra,
484}
485
486/// `sandbox.network.tlsTerminate`; empty for a generated CA.
487///
488/// Make the sandbox proxy terminate TLS so it can read the contents of HTTPS requests. This is
489/// experimental, and `mask` [credential
490/// substitution](https://code.claude.com/docs/en/sandboxing#mask-credentials) requires it.
491///
492/// Docs: [`sandbox.network.tlsTerminate`](https://code.claude.com/docs/en/settings-reference#sandbox-network-tlsterminate).
493#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
494#[serde(rename_all = "camelCase")]
495#[non_exhaustive]
496pub struct TlsTerminate {
497 /// Path to your own certificate authority certificate.
498 ///
499 /// - **Values**: string
500 /// - **Default**: unset
501 ///
502 /// Docs: [`caCertPath`](https://code.claude.com/docs/en/settings-reference#sandbox-network-tlsterminate).
503 #[serde(skip_serializing_if = "Option::is_none")]
504 pub ca_cert_path: Option<String>,
505 /// Path to your own certificate authority private key.
506 ///
507 /// - **Values**: string
508 /// - **Default**: unset
509 ///
510 /// Docs: [`caKeyPath`](https://code.claude.com/docs/en/settings-reference#sandbox-network-tlsterminate).
511 #[serde(skip_serializing_if = "Option::is_none")]
512 pub ca_key_path: Option<String>,
513 /// Keys Claude Code accepts here that this crate doesn't model (newer or
514 /// undocumented ones), kept as written so the document round-trips.
515 #[serde(flatten)]
516 pub extra: Extra,
517}
518
519/// `sandbox.filesystem`.
520///
521/// Control which paths sandboxed commands can read and write. By default they can write to the
522/// working directory, the per-user temp directory, and directories you add with `--add-dir`,
523/// `/add-dir`, or `permissions.additionalDirectories`, and can read the rest of the filesystem,
524/// including credential files.
525///
526/// Docs: [`sandbox.filesystem`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem).
527#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
528#[serde(rename_all = "camelCase")]
529#[non_exhaustive]
530pub struct SandboxFilesystem {
531 /// Add paths where sandboxed commands can write, beyond the working directory, the per-user
532 /// temp directory, and the directories you've added with `--add-dir`, `/add-dir`, or
533 /// `permissions.additionalDirectories`. Use it when a subprocess such as `kubectl` or a
534 /// build tool needs to write outside the project.
535 ///
536 /// - **Values**: array of path strings, using the [sandbox path
537 /// prefixes](https://code.claude.com/docs/en/settings-reference#sandbox-path-prefixes)
538 /// - **Default**: unset, so sandboxed commands can write to the working directory, the
539 /// per-user temp directory, directories you've added with `--add-dir` or `/add-dir`, and
540 /// directories in
541 /// [`permissions.additionalDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-additionaldirectories)
542 /// - **Scope**: any settings file, with [limits on project and local
543 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
544 ///
545 /// Docs: [`allowWrite`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-allowwrite).
546 #[serde(skip_serializing_if = "Option::is_none")]
547 pub allow_write: Option<Vec<String>>,
548 /// Block sandboxed commands from writing to specific paths, including paths inside a
549 /// directory that is otherwise writable.
550 ///
551 /// - **Values**: array of path strings, using the [sandbox path
552 /// prefixes](https://code.claude.com/docs/en/settings-reference#sandbox-path-prefixes)
553 /// - **Default**: unset
554 /// - **Scope**: any settings file.
555 ///
556 /// Docs: [`denyWrite`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-denywrite).
557 #[serde(skip_serializing_if = "Option::is_none")]
558 pub deny_write: Option<Vec<String>>,
559 /// Block sandboxed commands from reading specific paths, such as credential files that the
560 /// default read policy would otherwise expose. To protect a credential file and keep it
561 /// usable through the sandbox proxy, see
562 /// [`sandbox.credentials`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials)
563 /// instead.
564 ///
565 /// - **Values**: array of path strings, using the [sandbox path
566 /// prefixes](https://code.claude.com/docs/en/settings-reference#sandbox-path-prefixes)
567 /// - **Default**: unset, so sandboxed commands keep the [default read
568 /// access](https://code.claude.com/docs/en/sandboxing#filesystem-isolation), which
569 /// includes credential files such as `~/.aws/credentials`
570 /// - **Scope**: any settings file.
571 ///
572 /// Docs: [`denyRead`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-denyread).
573 #[serde(skip_serializing_if = "Option::is_none")]
574 pub deny_read: Option<Vec<String>>,
575 /// Re-open reading for specific paths inside a region that
576 /// [`denyRead`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-denyread)
577 /// blocks, to build workspace-only read access. An exact or wildcard `denyRead` entry stays
578 /// blocked inside a broader `allowRead`, as the [overlap
579 /// table](https://code.claude.com/docs/en/sandboxing#configure-sandboxing) shows. When a
580 /// wildcard `denyRead` entry such as `~/**/.env` matches a directory, Claude Code blocks
581 /// reads of its contents as well.
582 ///
583 /// - **Values**: array of path strings, using the [sandbox path
584 /// prefixes](https://code.claude.com/docs/en/settings-reference#sandbox-path-prefixes)
585 /// - **Default**: unset
586 /// - **Scope**: any settings file, with [limits on project and local
587 /// settings](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox).
588 ///
589 /// Docs: [`allowRead`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-allowread).
590 #[serde(skip_serializing_if = "Option::is_none")]
591 pub allow_read: Option<Vec<String>>,
592 /// Honor only the
593 /// [`allowRead`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-allowread)
594 /// entries that come from managed settings, so developers can't re-open read access to
595 /// paths your organization blocked. Claude Code still merges `denyRead` entries from every
596 /// settings scope the session loads.
597 ///
598 /// - **Values**: Boolean
599 /// - `true`: Claude Code honors only the `allowRead` entries from managed settings
600 /// - `false`: `allowRead` entries from other settings files can merge in
601 /// - **Default**: `false`
602 /// - **Scope**: managed.
603 ///
604 /// Docs: [`allowManagedReadPathsOnly`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly).
605 #[serde(skip_serializing_if = "Option::is_none")]
606 pub allow_managed_read_paths_only: Option<bool>,
607 /// Skip filesystem isolation while keeping network isolation. Sandboxed commands get
608 /// unrestricted read and write access to the host filesystem, and their network egress
609 /// stays confined to
610 /// [`network.allowedDomains`](https://code.claude.com/docs/en/settings-reference#sandbox-network-alloweddomains).
611 /// Use it when you sandbox to control where commands connect rather than what they write.
612 ///
613 /// - **Values**: Boolean
614 /// - `true`: Claude Code skips filesystem isolation and keeps network isolation
615 /// - `false`: filesystem isolation stays on
616 /// - **Default**: `false`, so filesystem isolation stays on
617 /// - **Scope**: user or managed. When managed settings configure `sandbox.filesystem` at
618 /// all, or list a `sandbox.credentials.files` entry with `"mode": "deny"`, only managed
619 /// settings can set it.
620 ///
621 /// Docs: [`disabled`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-disabled).
622 #[serde(skip_serializing_if = "Option::is_none")]
623 pub disabled: Option<bool>,
624 /// Keys Claude Code accepts here that this crate doesn't model (newer or
625 /// undocumented ones), kept as written so the document round-trips.
626 #[serde(flatten)]
627 pub extra: Extra,
628}
629
630/// `sandbox.credentials`.
631///
632/// Declare the credential files and environment variables to [protect from sandboxed
633/// commands](https://code.claude.com/docs/en/sandboxing#protect-credentials). Each entry names
634/// a file `path` or a variable `name` and a `mode`: `deny` hides the credential inside the
635/// sandbox, and `mask` shows sandboxed commands a placeholder while the [sandbox
636/// proxy](https://code.claude.com/docs/en/sandboxing#mask-credentials) substitutes the real
637/// value on outbound requests.
638///
639/// Docs: [`sandbox.credentials`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials).
640#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
641#[serde(rename_all = "camelCase")]
642#[non_exhaustive]
643pub struct SandboxCredentials {
644 /// Protect credential files or directories from sandboxed commands. With `"mode": "deny"`,
645 /// Claude Code blocks reads of the path inside the sandbox, the same read block as
646 /// [`sandbox.filesystem.denyRead`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-denyread).
647 /// With `"mode": "mask"`, sandboxed commands on Linux and WSL2 read a sentinel copy of the
648 /// file, and the sandbox proxy substitutes the real value on outbound requests to that
649 /// entry's `injectHosts`; on macOS the file is unreadable inside the sandbox instead.
650 ///
651 /// - **Values**: array of objects, each with `path` and a `mode` of `"deny"` or `"mask"`,
652 /// plus the optional [mask fields for
653 /// files](https://code.claude.com/docs/en/settings-reference#mask-fields-for-files)
654 /// - **Default**: unset, so no credential files are protected
655 /// - **Scope**: any settings file. Claude Code drops `mask` entries from project
656 /// `.claude/settings.json` and local `.claude/settings.local.json`.
657 ///
658 /// Docs: [`files`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-files).
659 #[serde(skip_serializing_if = "Option::is_none")]
660 pub files: Option<Vec<CredentialFile>>,
661 /// Protect environment variables from sandboxed commands. With `"mode": "deny"`, Claude
662 /// Code removes the variable from the environment of sandboxed commands. With `"mode":
663 /// "mask"`, sandboxed commands see a per-session sentinel value, and the sandbox proxy
664 /// substitutes the real value on outbound requests to that entry's `injectHosts`, so tools
665 /// such as `gh` and `npm` keep authenticating without ever holding the real credential.
666 ///
667 /// - **Values**: array of objects, each with `name` and a `mode` of `"deny"` or `"mask"`,
668 /// plus the optional [mask fields for environment
669 /// variables](https://code.claude.com/docs/en/settings-reference#mask-fields-for-environment-variables)
670 /// - **Default**: unset, so no environment variables are protected
671 /// - **Scope**: any settings file. Claude Code drops `mask` entries from project
672 /// `.claude/settings.json` and local `.claude/settings.local.json`.
673 ///
674 /// Docs: [`envVars`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-envvars).
675 #[serde(skip_serializing_if = "Option::is_none")]
676 pub env_vars: Option<Vec<CredentialEnvVar>>,
677 /// Allow `mask` substitution on plain HTTP requests as well as TLS-terminated HTTPS. On
678 /// plain HTTP the upstream identity is unverified and the credential travels in cleartext,
679 /// so leave this off outside trusted test networks.
680 ///
681 /// - **Values**: Boolean
682 /// - `true`: Claude Code allows `mask` substitution on plain HTTP requests as well as
683 /// TLS-terminated HTTPS
684 /// - `false`: Claude Code allows `mask` substitution only on TLS-terminated HTTPS
685 /// - **Default**: `false`
686 /// - **Scope**: user or managed.
687 ///
688 /// Docs: [`allowPlaintextInject`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-allowplaintextinject).
689 #[serde(skip_serializing_if = "Option::is_none")]
690 pub allow_plaintext_inject: Option<bool>,
691 /// Group masked environment variables that form one AWS credential for [SigV4
692 /// re-signing](https://code.claude.com/docs/en/sandboxing#re-sign-aws-requests) when your
693 /// credential lives in variables with non-standard names. Claude Code links the
694 /// conventional `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` trio
695 /// automatically when you mask their whole values, so you need this key only for other
696 /// names. Requires Claude Code v2.1.224 or later.
697 ///
698 /// - **Values**: array of objects, each with `accessKeyIdVar`, `secretAccessKeyVar`, and
699 /// optionally `sessionTokenVar`, naming `sandbox.credentials.envVars` entries
700 /// - **Default**: unset, so only the conventional trio is paired
701 /// - **Scope**: user or managed.
702 ///
703 /// Docs: [`awsPairs`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-awspairs).
704 #[serde(skip_serializing_if = "Option::is_none")]
705 pub aws_pairs: Option<Vec<AwsPair>>,
706 /// Choose what the sandbox proxy does with AWS request forms it [can't
707 /// re-sign](https://code.claude.com/docs/en/sandboxing#re-sign-aws-requests): `streaming`
708 /// for aws-chunked streaming uploads, `presigned` for presigned URLs, and `sigv4a` for
709 /// SigV4A asymmetric signatures. This applies only to requests signed with a masked pair's
710 /// placeholder access key ID. Requires Claude Code v2.1.224 or later.
711 ///
712 /// - **Values**: object with `streaming`, `presigned`, and `sigv4a`, each one of:
713 /// - `"deny"`: the proxy fails the request
714 /// - `"passthrough"`: the proxy forwards the request signed with the masked placeholder,
715 /// so the tool receives AWS's own rejection
716 /// - **Default**: unset, so every form is `"deny"`
717 /// - **Scope**: user or managed.
718 ///
719 /// Docs: [`sigv4`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-sigv4).
720 #[serde(skip_serializing_if = "Option::is_none")]
721 pub sigv4: Option<Sigv4>,
722 /// Keys Claude Code accepts here that this crate doesn't model (newer or
723 /// undocumented ones), kept as written so the document round-trips.
724 #[serde(flatten)]
725 pub extra: Extra,
726}
727
728/// An entry of `sandbox.credentials.files`.
729///
730/// Protect credential files or directories from sandboxed commands. With `"mode": "deny"`,
731/// Claude Code blocks reads of the path inside the sandbox, the same read block as
732/// [`sandbox.filesystem.denyRead`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-denyread).
733///
734/// Docs: [`sandbox.credentials.files`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-files).
735#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
736#[serde(rename_all = "camelCase")]
737#[non_exhaustive]
738pub struct CredentialFile {
739 /// Path to the credential file to deny.
740 ///
741 /// - **Values**: string
742 /// - **Default**: unset
743 ///
744 /// Docs: [`path`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-files).
745 #[serde(skip_serializing_if = "Option::is_none")]
746 pub path: Option<String>,
747 /// Access mode; only "deny" is supported.
748 ///
749 /// - **Values**: `"deny"`
750 /// - **Default**: unset
751 ///
752 /// Docs: [`mode`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-files).
753 #[serde(skip_serializing_if = "Option::is_none")]
754 pub mode: Option<CredentialMode>,
755 /// Mask only the text captured by group 1 of each match, so the rest of the file stays
756 /// parseable. With `decode` also set, Claude Code checks each capture as a possible JWT
757 /// instead of replacing it outright. Requires v2.1.221 or later.
758 ///
759 /// - **Values**: string, a regular expression with at least one capturing group
760 /// - **Default**: unset
761 ///
762 /// Docs: [`extract`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-files).
763 #[serde(skip_serializing_if = "Option::is_none")]
764 pub extract: Option<String>,
765 /// What happens when `extract` or `decode` finds nothing to mask. `warn` leaves the file
766 /// readable as-is inside the sandbox, `deny` makes it unreadable, and `error` stops sandbox
767 /// setup until you fix the configuration. Claude Code treats `deny` as `error` when the
768 /// read block wouldn't be enforced, because you [disable filesystem
769 /// isolation](https://code.claude.com/docs/en/sandboxing#disable-filesystem-isolation) or a
770 /// [`sandbox.filesystem.allowRead`](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-allowread)
771 /// entry re-opens the path.
772 ///
773 /// - **Values**: `"warn"`, `"deny"`, or `"error"`; default `"warn"`
774 /// - **Default**: unset
775 ///
776 /// Docs: [`onExtractNoMatch`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-files).
777 #[serde(skip_serializing_if = "Option::is_none")]
778 pub on_extract_no_match: Option<ExtractNoMatch>,
779 /// Find JSON Web Tokens (JWTs) in the file, with a built-in pattern or with `extract` when
780 /// set, verify each candidate, and replace it with a structurally valid fake token, so code
781 /// inside the sandbox that decodes the token keeps working. When no candidate verifies,
782 /// `onExtractNoMatch` governs the outcome. Requires v2.1.224 or later.
783 ///
784 /// - **Values**: the string `"jwt"`
785 /// - **Default**: unset
786 ///
787 /// Docs: [`decode`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-files).
788 #[serde(skip_serializing_if = "Option::is_none")]
789 pub decode: Option<TokenDecode>,
790 /// Mask only the named top-level payload claims inside each verified JWT and rebuild the
791 /// token around the modified payload, so the other claims stay readable. When no named
792 /// claim matches, `onExtractNoMatch` governs the outcome. Requires v2.1.224 or later.
793 ///
794 /// - **Values**: array of strings, at least one claim name; requires `decode`
795 /// - **Default**: unset
796 ///
797 /// Docs: [`maskClaims`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-files).
798 #[serde(skip_serializing_if = "Option::is_none")]
799 pub mask_claims: Option<Vec<String>>,
800 /// Also replace verbatim copies of each masked value elsewhere in the file, such as a
801 /// secret pasted into a comment. Claude Code matches raw substrings, so reserve it for
802 /// long, high-entropy secrets. Consulted only when `extract` or `decode` is set.
803 ///
804 /// - **Values**: Boolean, default `false`
805 /// - **Default**: unset
806 ///
807 /// Docs: [`maskDuplicates`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-files).
808 #[serde(skip_serializing_if = "Option::is_none")]
809 pub mask_duplicates: Option<bool>,
810 /// Narrow the hosts where the sandbox proxy substitutes the real value. When unset, the
811 /// proxy substitutes it on requests to every host in `sandbox.network.allowedDomains`.
812 /// Requires v2.1.221 or later.
813 ///
814 /// - **Values**: array of strings, each a host that
815 /// [`sandbox.network.allowedDomains`](https://code.claude.com/docs/en/settings-reference#sandbox-network-alloweddomains)
816 /// also admits
817 /// - **Default**: unset
818 ///
819 /// Docs: [`injectHosts`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-files).
820 #[serde(skip_serializing_if = "Option::is_none")]
821 pub inject_hosts: Option<Vec<String>>,
822 /// Keys Claude Code accepts here that this crate doesn't model (newer or
823 /// undocumented ones), kept as written so the document round-trips.
824 #[serde(flatten)]
825 pub extra: Extra,
826}
827
828/// An entry of `sandbox.credentials.envVars`.
829///
830/// Protect environment variables from sandboxed commands. With `"mode": "deny"`, Claude Code
831/// removes the variable from the environment of sandboxed commands.
832///
833/// Docs: [`sandbox.credentials.envVars`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-envvars).
834#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
835#[serde(rename_all = "camelCase")]
836#[non_exhaustive]
837pub struct CredentialEnvVar {
838 /// Environment variable name to deny.
839 ///
840 /// - **Values**: string
841 /// - **Default**: unset
842 ///
843 /// Docs: [`name`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-envvars).
844 #[serde(skip_serializing_if = "Option::is_none")]
845 pub name: Option<String>,
846 /// Access mode; only "deny" is supported.
847 ///
848 /// - **Values**: `"deny"`
849 /// - **Default**: unset
850 ///
851 /// Docs: [`mode`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-envvars).
852 #[serde(skip_serializing_if = "Option::is_none")]
853 pub mode: Option<CredentialMode>,
854 /// Mask only the text captured by group 1 of each match, such as the password inside a
855 /// `DATABASE_URL` connection string, so the rest of the value stays parseable. Requires
856 /// v2.1.224 or later.
857 ///
858 /// - **Values**: string, a regular expression with at least one capturing group
859 /// - **Default**: unset
860 ///
861 /// Docs: [`extract`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-environment-variables).
862 #[serde(skip_serializing_if = "Option::is_none")]
863 pub extract: Option<String>,
864 /// What happens when `extract` matches nothing. `warn` passes the variable through
865 /// unmasked, `deny` unsets it inside the sandbox, and `error` stops sandbox setup until you
866 /// fix the configuration. Requires v2.1.224 or later.
867 ///
868 /// - **Values**: `"warn"`, `"deny"`, or `"error"`; default `"warn"`. On an entry with
869 /// `decode`, only `"warn"` is accepted
870 /// - **Default**: unset
871 ///
872 /// Docs: [`onExtractNoMatch`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-environment-variables).
873 #[serde(skip_serializing_if = "Option::is_none")]
874 pub on_extract_no_match: Option<ExtractNoMatch>,
875 /// Verify the whole value is a JWT and replace it with a structurally valid fake token, so
876 /// code inside the sandbox that decodes the token keeps working; the proxy substitutes the
877 /// whole real token on egress. A value that doesn't verify passes through unmasked with a
878 /// warning. Requires v2.1.224 or later.
879 ///
880 /// - **Values**: the string `"jwt"`
881 /// - **Default**: unset
882 ///
883 /// Docs: [`decode`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-environment-variables).
884 #[serde(skip_serializing_if = "Option::is_none")]
885 pub decode: Option<TokenDecode>,
886 /// Mask only the named top-level payload claims inside the decoded JWT and rebuild the
887 /// token around the modified payload, so the other claims stay readable. When no named
888 /// claim matches, the variable passes through unmasked with a warning. Requires v2.1.224 or
889 /// later.
890 ///
891 /// - **Values**: array of strings, at least one claim name; requires `decode`
892 /// - **Default**: unset
893 ///
894 /// Docs: [`maskClaims`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-environment-variables).
895 #[serde(skip_serializing_if = "Option::is_none")]
896 pub mask_claims: Option<Vec<String>>,
897 /// Narrow the hosts where the sandbox proxy substitutes the real value. When unset, the
898 /// proxy substitutes it on requests to every host in `sandbox.network.allowedDomains`.
899 /// Write an IPv6 destination as the bare compressed address, such as `"::1"`, not the
900 /// bracketed form; see [IPv6 destinations in
901 /// `injectHosts`](https://code.claude.com/docs/en/sandboxing#ipv6-destinations-in-injecthosts).
902 ///
903 /// - **Values**: array of strings, each a host that
904 /// [`sandbox.network.allowedDomains`](https://code.claude.com/docs/en/settings-reference#sandbox-network-alloweddomains)
905 /// also admits
906 /// - **Default**: unset
907 ///
908 /// Docs: [`injectHosts`](https://code.claude.com/docs/en/settings-reference#mask-fields-for-environment-variables).
909 #[serde(skip_serializing_if = "Option::is_none")]
910 pub inject_hosts: Option<Vec<String>>,
911 /// Keys Claude Code accepts here that this crate doesn't model (newer or
912 /// undocumented ones), kept as written so the document round-trips.
913 #[serde(flatten)]
914 pub extra: Extra,
915}
916
917/// An entry of `sandbox.credentials.awsPairs`.
918///
919/// Group masked environment variables that form one AWS credential for [SigV4
920/// re-signing](https://code.claude.com/docs/en/sandboxing#re-sign-aws-requests) when your
921/// credential lives in variables with non-standard names. Claude Code links the conventional
922/// `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` trio automatically
923/// when you mask their whole values, so you need this key only for other names.
924///
925/// Docs: [`sandbox.credentials.awsPairs`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-awspairs).
926#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
927#[serde(rename_all = "camelCase")]
928#[non_exhaustive]
929pub struct AwsPair {
930 /// The masked variable that holds the access key ID.
931 ///
932 /// - **Values**: string, the `name` of a `sandbox.credentials.envVars` entry (required)
933 /// - **Default**: unset
934 ///
935 /// Docs: [`accessKeyIdVar`](None).
936 #[serde(skip_serializing_if = "Option::is_none")]
937 pub access_key_id_var: Option<String>,
938 /// The masked variable that holds the secret access key.
939 ///
940 /// - **Values**: string, the `name` of a `sandbox.credentials.envVars` entry (required)
941 /// - **Default**: unset
942 ///
943 /// Docs: [`secretAccessKeyVar`](None).
944 #[serde(skip_serializing_if = "Option::is_none")]
945 pub secret_access_key_var: Option<String>,
946 /// The masked variable that holds the session token.
947 ///
948 /// - **Values**: string, the `name` of a `sandbox.credentials.envVars` entry
949 /// - **Default**: unset
950 ///
951 /// Docs: [`sessionTokenVar`](None).
952 #[serde(skip_serializing_if = "Option::is_none")]
953 pub session_token_var: Option<String>,
954 /// Keys Claude Code accepts here that this crate doesn't model (newer or
955 /// undocumented ones), kept as written so the document round-trips.
956 #[serde(flatten)]
957 pub extra: Extra,
958}
959
960/// `sandbox.credentials.sigv4`.
961///
962/// Choose what the sandbox proxy does with AWS request forms it [can't
963/// re-sign](https://code.claude.com/docs/en/sandboxing#re-sign-aws-requests): `streaming` for
964/// aws-chunked streaming uploads, `presigned` for presigned URLs, and `sigv4a` for SigV4A
965/// asymmetric signatures. This applies only to requests signed with a masked pair's placeholder
966/// access key ID. Requires Claude Code v2.1.224 or later.
967///
968/// Docs: [`sandbox.credentials.sigv4`](https://code.claude.com/docs/en/settings-reference#sandbox-credentials-sigv4).
969#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
970#[serde(rename_all = "camelCase")]
971#[non_exhaustive]
972pub struct Sigv4 {
973 /// What the proxy does with aws-chunked streaming uploads it can't re-sign.
974 ///
975 /// - **Values**: `"deny"` (fail the request) or `"passthrough"` (forward it signed with the
976 /// placeholder)
977 /// - **Default**: `"deny"`
978 ///
979 /// Docs: [`streaming`](None).
980 #[serde(skip_serializing_if = "Option::is_none")]
981 pub streaming: Option<Sigv4Action>,
982 /// What the proxy does with presigned URLs.
983 ///
984 /// - **Values**: `"deny"` or `"passthrough"`
985 /// - **Default**: `"deny"`
986 ///
987 /// Docs: [`presigned`](None).
988 #[serde(skip_serializing_if = "Option::is_none")]
989 pub presigned: Option<Sigv4Action>,
990 /// What the proxy does with SigV4A asymmetric signatures.
991 ///
992 /// - **Values**: `"deny"` or `"passthrough"`
993 /// - **Default**: `"deny"`
994 ///
995 /// Docs: [`sigv4a`](None).
996 #[serde(skip_serializing_if = "Option::is_none")]
997 pub sigv4a: Option<Sigv4Action>,
998 /// Keys Claude Code accepts here that this crate doesn't model (newer or
999 /// undocumented ones), kept as written so the document round-trips.
1000 #[serde(flatten)]
1001 pub extra: Extra,
1002}
1003
1004/// `sandbox.ripgrep`.
1005///
1006/// Point the sandbox at a ripgrep binary of your own instead of the one Claude Code uses, for
1007/// example when your platform needs a differently built `rg`.
1008///
1009/// Docs: [`sandbox.ripgrep`](https://code.claude.com/docs/en/settings-reference#sandbox-ripgrep).
1010#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
1011#[serde(rename_all = "camelCase")]
1012#[non_exhaustive]
1013pub struct Ripgrep {
1014 /// Path to the ripgrep binary to use.
1015 ///
1016 /// - **Values**: string
1017 /// - **Default**: unset
1018 ///
1019 /// Docs: [`command`](https://code.claude.com/docs/en/settings-reference#sandbox-ripgrep).
1020 #[serde(skip_serializing_if = "Option::is_none")]
1021 pub command: Option<String>,
1022 /// Additional arguments to pass to the ripgrep binary.
1023 ///
1024 /// - **Values**: array of strings
1025 /// - **Default**: unset
1026 ///
1027 /// Docs: [`args`](https://code.claude.com/docs/en/settings-reference#sandbox-ripgrep).
1028 #[serde(skip_serializing_if = "Option::is_none")]
1029 pub args: Option<Vec<String>>,
1030 /// Keys Claude Code accepts here that this crate doesn't model (newer or
1031 /// undocumented ones), kept as written so the document round-trips.
1032 #[serde(flatten)]
1033 pub extra: Extra,
1034}
1035
1036walk!(Sandbox {
1037 network: "network",
1038 filesystem: "filesystem",
1039 credentials: "credentials",
1040 ripgrep: "ripgrep",
1041});
1042walk!(SandboxNetwork {
1043 tls_terminate: "tlsTerminate"
1044});
1045walk!(TlsTerminate {});
1046walk!(SandboxFilesystem {});
1047walk!(SandboxCredentials {
1048 files: "files",
1049 env_vars: "envVars",
1050 aws_pairs: "awsPairs",
1051 sigv4: "sigv4",
1052});
1053walk!(AwsPair {});
1054walk!(Sigv4 {});
1055walk!(CredentialFile {});
1056walk!(CredentialEnvVar {});
1057walk!(Ripgrep {});