home / skills / trevors / dot-claude / claude-code-web-docker

claude-code-web-docker skill

needs review

This skill helps you set up and run Docker in Claude Code for Web environments, tackling bridge, iptables, and SSL proxy challenges.

npx playbooks add skill trevors/dot-claude --skill claude-code-web-docker

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.8 KB

---
name: claude-code-web-docker
description: Set up and use Docker in Claude Code for Web environments. Use when Docker builds fail with bridge/iptables errors, SSL certificate errors through proxy, or when working in containerized web environments.
---

# Docker in Claude Code for Web

Claude Code for Web runs in a restricted container environment that requires special configuration for Docker.

## Detection

You're in Claude Code for Web if:

```bash
# Proxy environment is set
echo $http_proxy  # Shows a proxy URL

# Running inside a container
test -f /.dockerenv && echo "In container"

# iptables is restricted
iptables -L 2>&1 | grep -q "Permission denied"
```

## Quick Setup

```bash
# Install Docker
sudo apt-get update && sudo apt-get install -y docker.io

# Start daemon with restrictions (background)
sudo dockerd --iptables=false --bridge=none &

# Wait for daemon to be ready
sleep 3

# Verify
docker info
```

## Building csb Images

Standard builds fail because Docker tries to create bridge networks. Use these flags:

```bash
# Build with host networking and insecure SSL (for intercepting proxy)
csb build --host-network --insecure
```

What these flags do:

- `--host-network`: Uses host networking instead of bridge (which requires iptables)
- `--insecure`: Adds `-k` to curl commands and disables npm strict-ssl (for SSL-intercepting proxies)

## Creating Sandboxes

Sandbox creation also needs host networking:

```bash
# When creating sandboxes, they'll run in the Docker network
# The proxy container won't work (needs iptables), so use --egress=all
csb create my-sandbox --egress=all
```

## Common Errors and Fixes

### "iptables: Permission denied"

The daemon is trying to manage iptables rules. Restart with:

```bash
sudo pkill dockerd
sudo dockerd --iptables=false --bridge=none &
```

### "network bridge not found"

Same issue - daemon needs `--bridge=none` flag.

### "SSL certificate problem"

The proxy intercepts HTTPS. Use `--insecure` flag with csb build, or for manual curl:

```bash
curl -k https://example.com
```

### "npm ERR! unable to verify certificate"

```bash
npm config set strict-ssl false
npm install
npm config set strict-ssl true  # Reset after
```

## Full Workflow Example

```bash
# 1. Install and start Docker
sudo apt-get update && sudo apt-get install -y docker.io
sudo dockerd --iptables=false --bridge=none &
sleep 3

# 2. Build csb images
csb build --host-network --insecure

# 3. Create a sandbox
csb create dev --egress=all

# 4. Connect
csb ssh dev
```

## Limitations

In Claude Code for Web:

- No bridge networking - containers share host network
- No egress proxy container (requires iptables)
- SSL verification must be disabled for builds
- GPU passthrough not available

## Cleanup

```bash
# Stop all containers
docker stop $(docker ps -q) 2>/dev/null

# Stop daemon
sudo pkill dockerd
```

Overview

This skill explains how to configure and run Docker inside Claude Code for Web's restricted container environment. It covers detection, daemon startup options that avoid iptables and bridge networking, build flags for SSL-intercepting proxies, sandbox creation, common errors and cleanup commands. Use it to get reliable Docker builds and sandboxes when running inside the web-hosted Claude Code environment.

How this skill works

It inspects the environment for proxy variables, the presence of /.dockerenv, and iptables permission errors to confirm the restricted runtime. The skill shows how to start dockerd with --iptables=false and --bridge=none so Docker does not attempt privileged network manipulations. It also provides build and sandbox command flags (--host-network, --insecure, --egress=all) to work around bridge networking and SSL interception by proxies.

When to use it

You are running inside Claude Code for Web or another restricted container and need Docker to run reliably.
Docker builds fail with iptables, bridge network, or network bridge not found errors.
HTTPS requests fail due to an intercepting proxy causing SSL certificate errors during image builds.
Creating sandboxes fails because the proxy egress container requires iptables or bridge networking.
You need a quick, reproducible workflow to build and run csb images and sandboxes in the web environment.

Best practices

Start dockerd with --iptables=false and --bridge=none to avoid permission issues and bridge creation.
Use csb build --host-network --insecure when building behind an SSL-intercepting proxy.
Create sandboxes with --egress=all because the proxy egress container cannot run without iptables.
Temporarily disable strict SSL only for builds (e.g., npm config set strict-ssl false) and re-enable after.
Stop dockerd and containers during cleanup to avoid leftover processes in the shared runtime.

Example use cases

Install docker.io in Claude Code for Web, start the daemon with restricted flags, then run csb build --host-network --insecure.
Recover from iptables permission denied by killing dockerd and restarting it with --iptables=false --bridge=none.
Work around npm SSL verification failures by disabling strict-ssl for the install steps in the build.
Create a development sandbox with csb create dev --egress=all so networking works without the proxy container.
Clean up the environment before finishing a session: stop containers and pkill dockerd.

FAQ

How do I detect I'm in Claude Code for Web?

Check for proxy env variables (http_proxy), the /.dockerenv file, and iptables errors like 'Permission denied'.

Why use --host-network and --insecure?

--host-network avoids bridge creation that needs iptables; --insecure bypasses SSL verification for builds behind intercepting proxies.