[DOCS] Security-critical `enableWeakerNestedSandbox` option lacks documentation of specific protections lost

Documentation Type

Missing documentation (feature not documented)

Documentation Location

Primary: https://code.claude.com/en/sandboxing (Security Limitations section) Also affected: - https://code.claude.com/en/settings#sandbox-settings - https://docs.anthropic.com/en/docs/agent-sdk/typescript (SandboxSettings section) - https://docs.anthropic.com/en/docs/agent-sdk/python (SandboxSettings section)

Section/Topic

1. Sandboxing page - "Security Limitations" section, Linux Sandbox Strength bullet 2. Settings page - Sandbox settings table, enableWeakerNestedSandbox row 3. Agent SDK (TypeScript) - SandboxSettings interface documentation 4. Agent SDK (Python) - SandboxSettings class documentation

Current Documentation

In sandboxing.md (line 181):

* Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used in cases where additional isolation is otherwise enforced.

In settings.md (line 282):

| `enableWeakerNestedSandbox` | Enable weaker sandbox for unprivileged Docker environments (Linux and WSL2 only). **Reduces security.** Default: false | `true` |

In agent-sdk/typescript.md (line 2051):

| `enableWeakerNestedSandbox` | `boolean` | `false` | Enable a weaker nested sandbox for compatibility |

In agent-sdk/python.md (line 2263):

| `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility |

What's Wrong or Missing?

A security-critical setting is documented with vague warnings that don't explain the actual security impact:

1. No specifics on what's weakened: "Considerably weakens security" and "Reduces security" are meaningless without explaining WHICH protections are lost. Users cannot make informed decisions.

1. SDK documentation has no warning at all: The TypeScript and Python SDK docs say only "weaker nested sandbox for compatibility" with zero mention of security implications. Developers integrating the Agent SDK may enable this without any awareness of the risk.

1. Unclear guidance: "Should only be used in cases where additional isolation is otherwise enforced" doesn't explain what "additional isolation" means or how to implement it.

1. Risk to users:

• Developers may enable this for Docker convenience without understanding the tradeoff
• SDK users building agent applications have no warning whatsoever
• Security auditors cannot assess the risk without source code analysis

Suggested Improvement

Document the specific protections lost

Add a dedicated subsection explaining what changes when enableWeakerNestedSandbox is enabled:

### Weaker nested sandbox mode

When `enableWeakerNestedSandbox` is enabled for Docker compatibility:

**Protections retained:**
- [List filesystem restrictions that still apply]
- [List network restrictions that still apply]

**Protections weakened or disabled:**
- [List specific protections that are reduced]
- [Explain what attack vectors this enables]

**When to use:**
- Running inside a Docker container without `--privileged` flag
- When the Docker container itself provides equivalent isolation
- [Other legitimate use cases]

**When NOT to use:**
- On bare metal Linux systems
- When the Docker container has host-mounted volumes
- [Other contraindicated scenarios]

Add Warning boxes to SDK documentation

In agent-sdk/typescript.md and agent-sdk/python.md:

| `enableWeakerNestedSandbox` | `boolean` | `false` | Enable a weaker nested sandbox for unprivileged Docker environments. **Warning: Reduces security.** See [sandboxing limitations](https://code.claude.com/en/sandboxing#security-limitations) |

Consider runtime feedback

While outside documentation scope, consider logging a warning when this mode is active so users are reminded of the weakened security posture.

Impact

High - Prevents users from using a feature

Additional Context

Affected files in documentation mirror

| File | Line | Issue |
|------|------|-------|
| code-claude/docs/en/sandboxing.md | 181 | "Considerably weakens security" - no specifics |
| code-claude/docs/en/settings.md | 282 | "Reduces security." - no specifics |
| platform-claude/docs/en/agent-sdk/typescript.md | 2051 | "Weaker...for compatibility" - no security warning |
| platform-claude/docs/en/agent-sdk/python.md | 2263 | "Weaker...for compatibility" - no security warning |

Security considerations

1. Informed consent: Users enabling security-reducing features deserve to know exactly what they're trading away
2. SDK exposure: Agent SDK developers building applications on top of Claude Code may unknowingly ship weakened security to their users
3. Audit compliance: Security teams cannot properly assess configurations when documentation is vague

Comparison to similar patterns

The dangerouslyDisableSandbox parameter follows a good pattern:

• Name clearly signals danger
• Documentation explains what it does
• Requires explicit permission flow

The enableWeakerNestedSandbox should follow the same transparency standard.

Cross-references

• Sandboxing documentation: https://code.claude.com/en/sandboxing
• Settings reference: https://code.claude.com/en/settings
• Agent SDK (TypeScript): https://docs.anthropic.com/en/docs/agent-sdk/typescript
• Agent SDK (Python): https://docs.anthropic.com/en/docs/agent-sdk/python

---

Issue validated against documentation mirror on 2026-01-22