Skip to content

Feature: Introduce Integrated Runtime Sandboxing for Tool Execution #4320

New issue
New issue
Closed as not planned
Closed as not planned
Feature: Introduce Integrated Runtime Sandboxing for Tool Execution#4320
Labels
area:corearea:securityarea:toolsautocloseIssue will be closed automaticallyenhancementNew feature or request

Description

@coygeek
coygeek
opened on Jul 24, 2025

Title: Feature: Introduce Integrated Runtime Sandboxing for Tool Execution

Labels: enhancement, feature-request, security

Is your feature request related to a problem? Please describe.

Currently, the primary recommendation for running Claude Code in an isolated environment is using devcontainers. While this is excellent for creating consistent development environments, it is not a true runtime sandbox for tool execution.

This poses a security risk, especially when using powerful tools with side effects, such as the Bash tool. Every command executed by the agent runs with the same permissions as the user, creating a potential vector for accidental filesystem damage or the execution of malicious commands resulting from prompt injection. The burden of ensuring safety falls entirely on the user to manually vet every single operation, which is not scalable or foolproof.

Describe the solution you'd like

We propose implementing an integrated, lightweight, and configurable runtime sandboxing feature directly within the Claude Code CLI. This feature would isolate the execution environment of tools, preventing them from affecting the host system outside of a clearly defined scope.

The implementation should be inspired by the robust sandboxing model used in Google's Gemini CLI and should include:

  • Container-based Sandboxing: Support for Docker and Podman, allowing tool execution to occur inside a minimal, isolated container. The project's working directory would be mounted into the container to provide context.
  • macOS Native Sandboxing: On macOS, the CLI should leverage the built-in sandbox-exec (Seatbelt) framework to provide a low-overhead sandboxing option with configurable profiles.
  • Easy Configuration: Users and administrators should be able to enable, disable, and configure the sandbox via settings.json files and command-line flags (e.g., --sandbox).

Rationale and Value Proposition

An integrated sandbox provides a critical layer of security by default, making the tool safer for everyone.

  • Prevents Accidental Damage: Isolates file system modifications and command execution to prevent accidental deletion or modification of files outside the project workspace.
  • Contains Side Effects: Ensures that shell commands and their subprocesses are contained and cannot interfere with other parts of the user's system.
  • Mitigates Prompt Injection: Reduces the potential impact of a successful prompt injection attack by limiting the scope of what a malicious command can achieve.
  • Enterprise-Ready: A strong security posture is essential for enterprise adoption. This feature would make Claude Code a much more viable and secure tool for teams.

Prior Art & Implementation Guidance

Google's Gemini CLI provides an excellent blueprint for this feature. We should look to their implementation for inspiration:

  • Core Logic: The main sandboxing logic can be found in packages/cli/src/utils/sandbox.ts.
  • macOS Profiles: Example Seatbelt profiles are located in packages/cli/src/utils/sandbox-macos-*.sb.
  • Container Definition: The Dockerfile at the root of their repository defines the minimal container environment.

Acceptance Criteria

  • Users can enable sandboxing via a command-line flag (e.g., claude --sandbox).
  • Sandboxing can be configured as a default in ~/.claude/settings.json and .claude/settings.json.
  • On macOS, if Docker/Podman is not available, the CLI attempts to use sandbox-exec.
  • On Linux/Windows, the CLI attempts to use Docker or Podman.
  • When sandboxing is active, file system and Bash tool operations are executed within the isolated environment.
  • The current working directory is correctly mounted and accessible within the sandbox.
  • Documentation is updated to explain the new sandboxing feature, its configuration, and security benefits.

Activity

  1. github-actions
    added
    enhancementNew feature or request
    area:tools
    area:core
    area:security
    on Jul 27, 2025

  2. dimsky commented on Aug 11, 2025

    @dimsky
    dimsky
    on Aug 11, 2025

    +1

  3. aspiers commented on Aug 18, 2025

    @aspiers
    aspiers
    on Aug 18, 2025

    It would be helpful to explain the key differences between this proposal and what is already offered by https://docs.anthropic.com/en/docs/claude-code/devcontainer

  4. coygeek commented on Aug 18, 2025

    @coygeek
    coygeek
    on Aug 18, 2025
    Author

    Thanks @aspiers

    That's a great question. You're right to point out that there's an existing security feature, and it's helpful to clarify the distinction. The two features aim to solve different problems and can even be used together.

    Here are the key differences between the proposed Integrated Runtime Sandbox and the existing Devcontainer:

    1. Scope of Isolation

    • Devcontainer: Isolates the entire development environment. When you "Reopen in Container," your terminal, files, and all processes live inside a single, persistent Docker container. It's a macro-level isolation for your whole workspace.
    • Proposed Sandbox: Isolates individual tool executions at runtime. Your main claude session runs on your native OS (or inside the devcontainer), but when Claude needs to run a potentially dangerous command (e.g., Bash), that specific command is executed inside a temporary, minimal sandbox (like a new, short-lived container or a macOS sandbox-exec process).

    2. Activation and Persistence

    • Devcontainer: Is a static, session-long environment. You decide to use it at the beginning of your session and you stay inside it.
    • Proposed Sandbox: Is a dynamic, per-command protection. It activates automatically and transparently in the background only when a tool is used, and it's torn down immediately after the command finishes.

    3. Primary Security Goal

    • Devcontainer: The main security feature highlighted in the docs is a firewall with network restrictions. It's designed to make unattended operation (using --dangerously-skip-permissions) safer by preventing the project from accessing unexpected network resources. It provides environmental consistency for teams.
    • Proposed Sandbox: The primary goal is to prevent accidental or malicious filesystem damage from tool execution. It contains the side effects of commands, ensuring an rm command, for example, can't delete files outside of the project directory.

    4. Implementation and Overhead

    • Devcontainer: Relies on the standard VS Code Dev Containers extension and a user-provided Docker setup. It's a well-established but "heavier" solution.
    • Proposed Sandbox: Would be a lightweight feature integrated directly into the Claude Code CLI. It proposes multiple backends, including Docker/Podman but also a very low-overhead native macOS option (sandbox-exec), making it more accessible and faster for per-command execution.

    Analogy

    Think of it this way:

    • The Devcontainer is like a secure, isolated workshop. You go inside to do all your work, and the workshop has rules about what signals can go in or out (network firewall).
    • The proposed Runtime Sandbox is like an automatic safety guard on a power tool. You can use the tool anywhere (on your native OS or inside the workshop), but the moment you press the trigger, the guard engages to prevent you from cutting anything you're not supposed to.

    In short, the devcontainer provides a "secure room" to work in, while the proposed sandbox provides a "safety harness" for the specific actions Claude takes within that room (or on your native system).

    Hope this helps clarify the distinction and the value this proposal aims to add

  5. aspiers commented on Aug 18, 2025

    @aspiers
    aspiers
    on Aug 18, 2025

    Got it, thanks!

  6. mafshin commented on Aug 20, 2025

    @mafshin
    mafshin
    on Aug 20, 2025

    Codex already uses Seatbelt:

    user
are you running directly in my mac or in a container

thinking
Clarifying running environment

I need to answer the user's question about whether I'm running directly on their Mac or in a container. Based on the context, I'm in a Codex CLI harness, which operates within a restricted sandbox
environment rather than directly on the host. I'll explain that while it's still MacOS, I'm running in a sandbox that limits network access and file writes. So, I can clarify that I'm not a Docker
container, just a sandboxed process with limited permissions.

Explaining the environment

I need to clarify that I’m running on the user's Mac, but I'm in a sandboxed runner called Seatbelt. My filesystem access is limited to workspace-write only within the specified directory. Also,
my network access is restricted; any requests require approval and are blocked by the harness configuration. This limitation explains why some commands, like the NuGet restore, fail. I'll keep this
concise to ensure clarity for the user.


codex
I’m running on your Mac inside a sandboxed runner (not a full host shell or Docker). Specifically:

- Filesystem: workspace-write only (this repo folder).
- Network: restricted by the harness; restores need explicit allowance and may still be blocked.
- Security: macOS Seatbelt–style sandboxing, so some commands time out or fail silently.

  7. coygeek commented on Aug 20, 2025

    @coygeek
    coygeek
    on Aug 20, 2025
    Author

    Excellent point, @mafshin! Thank you for sharing that transcript. This is fantastic information and actually reinforces why this feature is so critical for Claude Code.

    You're absolutely right that Codex has implemented a form of runtime sandboxing using macOS Seatbelt. My feature request is fundamentally about bringing that same level of security and a similar, proven model to Claude Code.

    Here’s how my proposal is different and why it's still a necessary addition for the Claude Code ecosystem:

    1. The Core Issue: This is a Feature Request for Claude Code, Not Codex

    The most crucial distinction is that my request is for Anthropic's Claude Code. The transcript you shared is from OpenAI's Codex, which is a separate, competing product.

    The fact that a major competitor has already identified this as a necessary security feature and implemented it only strengthens the case for Claude Code to adopt a similar mechanism to stay competitive and secure. My proposal is about achieving parity with industry best practices.

    2. Cross-Platform Consistency

    The Codex transcript specifically mentions "macOS Seatbelt–style sandboxing." My proposal goes a step further by outlining a cross-platform strategy:

    • macOS: Use the native, low-overhead sandbox-exec (Seatbelt), just like Codex does.
    • Linux & Windows (WSL): Use containerization (Docker/Podman) to provide an equivalent level of isolation.

    This ensures that all Claude Code users, regardless of their OS, benefit from the same high level of runtime security. A Linux user shouldn't have a less secure experience than a macOS user.

    3. Configurability and User Control

    My proposal explicitly calls for making sandboxing a first-class, configurable feature. The user or an administrator should be able to:

    • Enable or disable it with a flag (claude --sandbox).
    • Set a default policy in settings.json.
    • Understand exactly what security guarantees are in place.

    While Codex appears to have sandboxing enabled by default (which is great!), it's not clear from the transcript how configurable it is. My proposal emphasizes making this a transparent and controllable feature for developers and enterprise admins.

    Summary: It's an Argument For the Feature, Not Against It

    In short, your example is the perfect "prior art." It proves:

    1. The Need is Real: Other major players in the AI coding assistant space recognize runtime sandboxing as a critical security requirement.
    2. The Technology is Viable: The use of Seatbelt by Codex demonstrates that this is a practical and effective approach on macOS.

    My request is to take that proven concept, expand it for cross-platform support, and integrate it into Claude Code as a transparent, configurable, and essential security feature. We want to make Claude Code as safe—or safer—than its competitors.

    Thanks again for bringing this up; it's a perfect example to point to for the development team

  8. github-actions commented on Dec 5, 2025

    @github-actions
    github-actionsBot
    on Dec 5, 2025 – with GitHub Actions

    This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

  9. github-actions
    added
    autocloseIssue will be closed automatically
    on Dec 5, 2025

  10. github-actions commented on Jan 8, 2026

    @github-actions
    github-actionsBot
    on Jan 8, 2026 – with GitHub Actions

    This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

  11. github-actions
    closed this as not plannedon Jan 8, 2026

  12. github-actions commented on Jan 15, 2026

    @github-actions
    github-actionsBot
    on Jan 15, 2026 – with GitHub Actions

    This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

  13. github-actions
    locked as resolved and limited conversation to collaborators on Jan 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:corearea:securityarea:toolsautocloseIssue will be closed automaticallyenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions