Claude Code should run a trusted repository inside a tightly configured local sandbox, but an unfamiliar repository should not receive access to your main Mac’s SSH keys, cloud credentials, or unrestricted network. Use Claude Code Sandbox Configuration 2026 as a three-layer control: permissions, filesystem isolation, and network egress. If the repository needs dependencies, long-running agents, or broad external access, move the job to a dedicated virtual machine or independent cloud Mac.

This guide was last updated on August 15, 2026. Technical behavior was checked against Anthropic’s current security, sandbox, permissions, and Dev Container documentation, plus the Claude Code security advisory record.

This guide is for developers reviewing open-source projects or unfamiliar pull requests, team leads allowing Claude Code to run tests and MCP tools, and administrators preparing isolated Mac execution nodes for AI agents.

Key takeaway: A confirmation dialog controls approval behavior. It does not replace operating-system isolation.

Start With The Repository, Not The Agent

A common failure path looks harmless: clone an external repository, change into its directory, and start Claude Code. The danger may appear before the first obvious shell command. Repository-controlled instructions, project settings, Hooks, MCP declarations, package installation scripts, symbolic links, and text returned by external tools can all influence what the agent sees or attempts.

Anthropic’s official security guidance treats prompt injection as a risk when untrusted instructions appear in files, tool output, or external content. Its recommendations include reviewing commands, avoiding direct piping of untrusted content, verifying changes to critical files, and using virtual machines for scripts or tool calls that interact with external services. The official Claude Code security guidance should be the starting point for any team policy.

A separate example came from GhostApproval research disclosed by Wiz. The study examined cases where a user-facing approval prompt did not clearly expose the real filesystem target behind a symbolic link. The research included Claude Code, but it was a third-party disclosure, not proof that every version or every installation remains exploitable. Anthropic disputed part of the threat-model interpretation and described the scenario as involving explicit confirmation inside a directory containing a malicious symlink. The original GhostApproval research should therefore be read as a specific reported attack path, not as a claim about every release.

The practical decision is simple:

  • If the repository is trusted, the task is local, and credentials are absent, a hardened local sandbox can be reasonable.
  • If the repository source is uncertain, the project installs dependencies, or the agent needs external services, use a disposable environment.
  • If the task needs long unattended execution, treat permission prompts as insufficient and use a dedicated virtual machine or cloud Mac.

Prepare A Clean Workspace Before First Launch

Do not begin with the repository open in your everyday home directory. Create a separate workspace and inspect the content without executing project code.

A useful preparation sequence is:

  1. Clone without installing dependencies. Avoid npm install, pnpm install, pip install, bundle install, make, or project-specific bootstrap commands during the first inspection.
  2. Inspect repository-controlled configuration. Review .claude/, .mcp.json, project instruction files, CI configuration, editor settings, package manifests, lockfiles, install scripts, and Hook definitions.
  3. List symbolic links. Use a read-only command such as find . -type l -print and inspect each target before allowing file edits.
  4. Search for network and credential behavior. Look for curl, wget, package post-install scripts, shell profile changes, token names, hard-coded hostnames, reverse-shell patterns, and scripts that write outside the project.
  5. Check executable files. Review file permissions and identify scripts that would run automatically during dependency installation, tests, builds, or Git operations.
  6. Remove host credentials from the execution path. Do not mount ~/.ssh, cloud credential files, signing keys, production .env files, or broad API tokens into the workspace.
  7. Use short-lived credentials only after the repository passes review. If the task requires repository access, use a narrowly scoped token rather than a general-purpose credential.

Anthropic’s sandbox documentation includes explicit credential controls for paths such as ~/.ssh and environment variables such as GITHUB_TOKEN and NPM_TOKEN. It also warns against mounting host secrets into a Dev Container and recommends repository-scoped or short-lived tokens. See the official sandbox configuration reference before creating a team-wide configuration.

Pre-launch checklist

  • [ ] The repository is not opened from the home directory.
  • [ ] No SSH private key is available to the session.
  • [ ] Cloud credentials and production variables are absent.
  • [ ] .claude/settings.json and .claude/settings.local.json have been reviewed.
  • [ ] Hooks and MCP declarations have been inspected.
  • [ ] Symbolic links have been listed and their targets verified.
  • [ ] Dependency installation is postponed until after the read-only review.
  • [ ] The Claude Code installation is updated before security testing.

Claude Code’s official advisory record includes sandbox and path-handling issues, including a symlink-based file-write issue fixed in version 2.1.64. That advisory required untrusted content to reach the context and trigger sandboxed execution, but it still demonstrates why version review and repository inspection belong before execution. Check the Claude Code security advisories before using an older installation.

Use Read-Only Mode For The First Pass

The first Claude Code session should answer questions, not modify files or install tools. Start in the repository directory and use plan mode or regular permission mode.

A safe first pass should ask Claude Code to:

  • summarize the repository structure;
  • identify scripts that execute during installation, testing, or building;
  • list all declared MCP servers;
  • explain every Hook and its trigger;
  • identify network destinations;
  • locate references to SSH, cloud tokens, signing keys, environment files, and shell startup files;
  • report symbolic links and targets;
  • produce a proposed test plan without running it.

Plan mode is useful because it allows exploration while restricting source edits. Regular permission mode is better when every shell operation should remain visible. Avoid automatic approval until the repository has passed the first review.

The permission system distinguishes deny, ask, and allow rules. Claude Code evaluates them in that order. A matching deny rule blocks an action even when a narrower allow rule also matches. A matching ask rule still prompts even when an allow rule exists. This behavior is documented in the official permissions reference.

A conservative project configuration can begin like this:

{
  "permissions": {
    "deny": [
      "Bash(git push *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.ssh/**)",
      "Read(**/credentials*)",
      "mcp__*"
    ],
    "ask": [
      "Bash(npm install *)",
      "Bash(pnpm install *)",
      "Bash(pip install *)",
      "Bash(git commit *)",
      "Bash(git checkout *)",
      "Bash(run_background:true)",
      "WebFetch"
    ],
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ]
  }
}

The exact rule set must match the repository. A blanket deny for every MCP server may block legitimate inspection tools, while a broad allow rule can create an unnecessary execution path. The point is to begin narrow and add one capability at a time.

Configure macOS Seatbelt For Bash And Child Processes

On macOS, Claude Code’s built-in sandbox uses the operating system’s Seatbelt framework. It constrains Bash commands and their child processes at the filesystem and network layers. It does not turn every Claude Code tool into a fully isolated process.

This distinction matters. The sandbox protects shell commands such as package managers, test runners, compilers, and scripts. Built-in file tools such as Read, Edit, and Write remain governed by Claude Code’s permission system. Therefore, a safe configuration combines OS-level sandboxing with explicit tool permissions rather than treating either layer as complete.

Run /sandbox inside the session and verify four points:

  1. Sandbox is enabled.
  2. Filesystem writes are limited to the working directory and a controlled temporary directory.
  3. Only required network domains are allowed.
  4. Unsandboxed fallback is disabled for unfamiliar repositories.

A representative settings block is:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "allowWrite": [
        "./build",
        "./tmp"
      ],
      "denyRead": [
        "~/.ssh",
        "~/.aws",
        "~/.config",
        "~/.docker"
      ]
    },
    "network": {
      "allowedDomains": [
        "api.anthropic.com"
      ]
    }
  }
}

The domain list should include only endpoints required by the task. For example, a dependency build may require a package registry, while a source audit may require no outbound repository access at all. Authentication, package downloads, telemetry, error reporting, and source control access should be considered separate network requirements rather than merged into one broad allowlist.

The most important setting is failIfUnavailable. Claude Code documentation explains that a configuration can warn when sandboxing is unavailable and then run commands without sandboxing. A managed or high-risk environment should fail closed instead. The same documentation describes allowUnsandboxedCommands: false as a strict mode that prevents the dangerouslyDisableSandbox escape hatch from retrying outside the sandbox.

Operational warning: A sandbox that silently falls back to unsandboxed execution is not an acceptable boundary for an unfamiliar repository.

Restrict Credentials Before Allowing Network Access

The question “Can Claude Code’s sandbox protect SSH keys?” has a conditional answer. It can deny access to configured credential paths for sandboxed Bash processes, but a host credential that remains mounted, exported, or reachable through another tool should not be considered protected by the sandbox alone.

Use credential rules where supported:

{
  "sandbox": {
    "credentials": {
      "files": [
        {
          "path": "~/.ssh",
          "mode": "deny"
        },
        {
          "path": "~/.aws/credentials",
          "mode": "deny"
        }
      ],
      "envVars": [
        {
          "name": "SSH_AUTH_SOCK",
          "mode": "deny"
        },
        {
          "name": "GITHUB_TOKEN",
          "mode": "deny"
        },
        {
          "name": "NPM_TOKEN",
          "mode": "deny"
        }
      ]
    }
  }
}

This reduces exposure for sandboxed Bash, but it does not justify running a malicious project on a host that already contains production access. The safer sequence is still to remove long-lived credentials from the environment, then add a narrowly scoped token only when the repository needs it.

Do not use --dangerously-skip-permissions on a local host with valuable credentials. Anthropic’s Dev Container guidance permits unattended operation only in the context of container isolation, while also warning that accessible credentials inside the container can still be exfiltrated. A container does not prevent a malicious project from reading anything available inside that container.

Decide Between Local Sandbox, Dev Container, And Dedicated Mac

A Dev Container can isolate command execution from the host, but it does not completely isolate the project from every mounted resource. If the repository directory is bind-mounted, Claude Code can modify that workspace. If authentication state or host secrets are mounted, those become part of the container’s attack surface.

Use this decision branch:

  • If the repository is trusted, no dependency installation is needed, and no sensitive credentials are present: choose local Claude Code with Seatbelt, strict filesystem rules, limited network domains, and manual approval.
  • If the repository is moderately trusted, dependencies are required, and the work can stay inside a reproducible Linux toolchain: choose a Dev Container with a non-root user, restricted egress, no host secret mounts, and per-project authentication.
  • If the repository is unknown, requires external services, uses macOS-only tooling, or must run unattended for a long task: choose a disposable virtual machine or independent cloud Mac.
  • If the task touches signing material, production systems, customer data, or unrestricted cloud access: do not use the main Mac. Create an isolated execution node or reject the task until the access boundary is redesigned.

The answer to “Can Dev Container completely isolate Claude Code?” is no. It creates a stronger boundary than a normal host shell, but the repository can still affect bind-mounted files, allowed network destinations, mounted volumes, and credentials exposed inside the container. The official Dev Container guidance recommends avoiding host secrets, limiting network egress, and recognizing that unattended operation removes the chance to review each tool call.

For macOS-specific builds, signing, Xcode workflows, or long-running AI Agent jobs, an independent cloud Mac can be easier to reset than a primary workstation. RUVCLOUD’s remote Mac ordering options can be evaluated after the repository has been classified. The correct decision is not “remote is automatically safe”; it is whether the proposed node has the required filesystem, network, credential, reset, and access controls.

Verify The First Execution In Small Increments

After static review and sandbox configuration, do not immediately start a full build. Use a staged execution process:

  1. Run harmless inspection commands. Confirm the current directory, Git status, tool versions, and visible files.
  2. Test filesystem boundaries. Ask the agent to write only inside the approved temporary directory, then verify that writes outside it fail.
  3. Test network boundaries. Attempt a request to an approved domain and a deliberately unapproved domain.
  4. Install one dependency group at a time. Review the package manager output and lifecycle scripts before continuing.
  5. Run a narrow test target. Avoid full repository automation until the dependency graph and scripts are understood.
  6. Review Git changes immediately. Inspect modified files, generated artifacts, permission files, shell configuration, and new executables.
  7. Approve exceptions individually. If a command needs to leave the sandbox, record the reason and decide whether the task belongs on a disposable node instead.

Claude Code’s sandbox supports explicit filesystem write paths and network domain lists. Its documentation also explains that sandboxed commands can fall back to an unsandboxed retry unless that escape hatch is disabled. Treat every fallback request as a boundary failure, not as a routine compatibility prompt.

Finish With Cleanup And Environment Destruction

A successful test does not prove that the environment is clean. A script may have created persistence, altered shell startup files, added an SSH key, changed Git configuration, installed a background process, or contacted an external endpoint without changing tracked files.

Use this end-of-task checklist:

  • [ ] Review git diff and all untracked files.
  • [ ] Inspect .claude/ settings and permission changes.
  • [ ] Check shell startup files and local executable paths.
  • [ ] Review ~/.ssh/authorized_keys if the environment had SSH access.
  • [ ] Inspect token usage and authentication logs.
  • [ ] Review network access records where available.
  • [ ] Remove temporary credentials and revoke tokens.
  • [ ] Compare the environment against its initial snapshot.
  • [ ] Destroy and recreate the instance if the repository executed unknown scripts.
  • [ ] Do not confuse code rollback with reversal of external side effects.

For a one-time audit, destruction is usually safer than continued trust. A clean rebuild removes hidden files, altered packages, modified startup configuration, and untracked persistence that a Git reset cannot address.

RUVCLOUD’s pricing and rental options are most relevant when a temporary Apple environment is cheaper and safer than exposing a primary Mac to repeated untrusted execution. The decision should be based on task duration, reset frequency, macOS tooling, network requirements, and credential sensitivity rather than on convenience alone.

A main Mac remains useful for trusted repositories and short interactive reviews. A Dev Container is appropriate when the toolchain is reproducible and the mounted surface is controlled. A dedicated virtual machine or cloud Mac is the better long-term pattern when the repository is unknown, the agent must run unattended, or the job needs macOS tooling with a clear destroy-and-rebuild cycle.

Before creating a temporary node, confirm four boundaries: what files the agent can read, where it can write, which domains it can contact, and which credentials it can use. If any answer is still “the whole host,” the environment is not ready for Claude Code.