# Claude Code Sandbox and devcontainers

> Claude Code: Compare Bash sandbox, sandbox runtime, devcontainers, custom containers and VMs, including credentials, networking and cache boundaries.

URL: https://docs.passion8.cc/en/docs/claude-code/sandbox-devcontainers
Language: en
Publisher: Passion8

Choose isolation before reducing prompts, automating tests or running untrusted repositories/CI. Permissions govern whether an action runs; isolation governs what it can reach afterwards.




Sandboxing does not change data already sent to models. It protects local files, networking and credentials, not training/retention policy.




## Compare isolation approaches

| Approach | Scope | Docker needed | Best fit |
| --- | --- | --- | --- |
| Bash sandbox | Shell commands and children | No | Fewer routine command prompts |
| Sandbox runtime | Entire Code process, MCP and hooks | No | Broader process isolation without Docker |
| Devcontainer | Development environment | Yes | Shared toolchain, Codespaces and IDE containers |
| Custom container | Development environment | Yes | Existing platforms, CI and remote work |
| VM | Operating system | No | Untrusted repositories and strong isolation |
| Code on the web | Hosted environment | No | Mobile delegation without local setup |

Bash sandbox does not necessarily contain built-in Read/Edit, MCP or hooks. Use runtime/container/VM isolation when needed.

## Devcontainer baseline

Minimal devcontainer.json:

```json title=".devcontainer/devcontainer.json"
{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}
```

Common additions:

```json title=".devcontainer/devcontainer.json"
{
  "mounts": [
    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
  ],
  "containerEnv": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "DISABLE_AUTOUPDATER": "1"
  }
}
```

~/.claude contains authentication, settings and history. Without persistence, rebuilds require login again. devcontainerId can separate project state.

## Container organization policy

Linux Code reads /etc/claude-code/managed-settings.json:

```dockerfile title="Dockerfile"
RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json
```

Repository Dockerfiles provide defaults but can be edited by contributors. Non-bypassable policy needs administrator/platform-controlled delivery.

## Network egress

A container firewall can restrict required domains. Reference list:

| Domain | Purpose |
| --- | --- |
| passion8.cc | Gateway and console |
| api.anthropic.com | API, preflight and managed settings |
| claude.ai | Official login/web |
| downloads.claude.ai | Binaries, plugin executables and updates |
| raw.githubusercontent.com | Release notes, marketplaces and examples |

To disable nonessential traffic:

```bash
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
```

Installation, plugins, WebFetch, Chrome bridges and Artifacts may need more domains. Separate model traffic from auxiliary client traffic.

## Protect credentials

Avoid mounting long-lived host credentials, especially:

- `~/.ssh`
- `~/.aws/credentials`
- `~/.config/gcloud`
- `.env`
- npm, GitHub and cloud-provider long-lived tokens.

Prefer:

| Need | Recommendation |
| --- | --- |
| Git | Repository-scoped deploy key or short-lived token |
| Cloud | Workload identity, Codespaces secrets or OIDC |
| Passion8 key | User secret or helper |
| Package installation | Read-only registry token and domain limits |

When using the Code sandbox, also protect common credentials:

```json title=".claude/settings.json"
{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}
```

## Combine permission modes

| Mode | Environment |
| --- | --- |
| default | Routine local development |
| plan | Review before risky changes |
| auto | Reduce prompts with sandbox/container isolation |
| bypassPermissions | Trusted repository in nonroot container, VM or strong sandbox only |

Skipping permissions removes per-action confirmation. Containers reduce host exposure but do not prevent repository changes or abuse of credentials accessible inside them.

## Caching and cost

| Scenario | Cache effect |
| --- | --- |
| Clear ~/.claude on rebuild | Changes state and can reduce cache reuse |
| Persistent volume | More stable same-project prefixes |
| Pinned client version | Stable prompts and tool behavior |
| Fresh container per CI job | Often cold prefixes with limited short-TTL reuse |
| Network/permission changes | Tool/settings/sandbox prompts can alter keys |
| Passion8 | Verify upstream TTL and usage forwarding |

## Official references

- [Development containers](https://code.claude.com/docs/en/devcontainer.md)
- [Choose a sandbox environment](https://code.claude.com/docs/en/sandbox-environments.md)
- [Configure the sandboxed Bash tool](https://code.claude.com/docs/en/sandboxing.md)
- [Security model](https://code.claude.com/docs/en/security.md)
- [Permission modes](https://code.claude.com/docs/en/permission-modes.md)

## Related pages



- [Sandboxing](https://docs.passion8.cc/en/docs/claude-code/sandboxing): Bash/runtime isolation, containers, VMs, network and credentials.
- [Permissions](https://docs.passion8.cc/en/docs/claude-code/permissions): Allow/ask/deny, auto, plan and bypass modes.
- [Enterprise deployment](https://docs.passion8.cc/en/docs/claude-code/enterprise-deployment-overview): Providers, policies, monitoring and data boundaries.
- [Headless automation](https://docs.passion8.cc/en/docs/claude-code/headless): CI, scripts, JSON, permissions, isolation and structured results.