devcontainer_base/CLAUDE.md

This directory contains the foundation Docker image for secure devcontainer environments.

Purpose

Provides a reusable base image with:

Non-root user setup (claude:local-ai-team)
Development tools (Node.js, Python/uv, Docker CLI)
Security controls and network isolation support
Claude Code defaults and linting hooks
Testing utilities for validation

Build Process

The base image is built using:

./images/build.sh devcontainer  # Builds ai-agents-sandbox/devcontainer:latest
# Or from images directory:
cd images && ./build.sh devcontainer

Directory Structure

/scripts/

Security and setup scripts installed in the image:

```
get-whitelist.sh
```
: Merges whitelist files from multiple sources
- Combines built-in defaults with project-specific domains
- Outputs merged list for tinyproxy configuration
```
non-root-post-create.sh
```
: Post-creation setup for non-root user
- Sets up Docker certificates for DinD
- Configures Claude Code settings
- Initializes development environment
- Creates logs in
```
~/scripts/logs/
```
  to avoid conflicts with
```
.claude/
```
  directory
```
setup-claude-defaults.sh
```
: Installs Claude Code configurations
- Copies agent definitions to
```
.claude/agents/
```
- Sets up linting hooks in
```
.claude/hooks/
```
- Configures default settings
- Handles ownership gracefully, excluding
```
logs/
```
  and
```
projects/
```
  directories
```
setup-p10k.sh
```
: Configures Powerlevel10k theme for zsh
- Interactive theme configuration
- Terminal appearance customization
```
test-network.sh
```
: Network isolation verification
- Tests proxy-only access enforcement
- Validates DNS blocking without proxy
- Verifies whitelist filtering
```
test-permissions.sh
```
: Security permissions validation
- Confirms non-root user enforcement
- Checks file ownership and permissions
- Validates security constraints
- Verifies
```
/home/claude/.claude/projects
```
  directory has group
```
local-ai-team
```
  for shared access
```
test-tools.sh
```
: Development tools verification
- Tests all installed tools and versions
- Validates Python, Node.js, Docker CLI
- Checks linters and formatters

/claude-defaults/

Minimal Claude Code configurations:

```
/hooks/
```
: Notification hook
- ```
notify.sh
```
  : Host notification system for alerts
```
settings.json
```
: Base Claude Code settings (telemetry disabled)
```
settings.local.json
```
: Local settings with notification hook configuration

Note: This is a minimal base image. Users can add their own agents, commands, and hooks during project initialization by choosing to copy their host Claude settings.

/conf/

User configuration files:

```
.tmux.conf
```
: Terminal multiplexer configuration
```
.zshrc
```
: Shell configuration with p10k theme

default-whitelist.txt

Built-in allowed domains for proxy filtering:

Package registries (npm, pip, etc.)
Source control (GitHub, GitLab)
Development tools and documentation

Docker Image Details

Base: Ubuntu 22.04 User: claude (UID 1001) Group: local-ai-team (GID 3000) Shell: zsh with Powerlevel10k

Installed Tools:

Node.js 20 LTS
Python with uv package manager
Docker CLI (for DinD connection)
Git and development utilities
Linters: shellcheck, hadolint, yamllint, ruff, black

Directory Structure:

```
/home/claude/scripts/
```
: Utility scripts and tools (added to PATH)
```
/home/claude/scripts/logs/
```
: Script execution logs (separate from .claude/)
```
/home/claude/claude-defaults/
```
: Source for Claude Code configurations
```
/home/claude/.claude/
```
: Runtime Claude Code configuration (populated by setup script)
```
/home/claude/.claude/projects/
```
: Mount point for host projects directory (group: local-ai-team)
```
/workspace/.notifications/
```
: Mount point for host notification system

Security Constraints

The image enforces:

NO root access: User 'claude' has no sudo
NO passwords: No authentication mechanisms
NO SSH: No remote access services
File permissions: Strict ownership model
Network isolation ready: Designed for internal networks

Container Lifecycle Scripts

entrypoint.sh

(Runtime)

When: Runs every time the container starts
Purpose: Runtime initialization and fixes
Tasks:
- Fixes
```
.codex
```
  directory ownership issues
- Ensures proper file permissions for runtime

non-root-post-create.sh

(Post-Creation)

When: Runs once after container is first created
Purpose: One-time setup and validation
Tasks:
- Orchestrates all setup scripts (P10k, Claude defaults)
- Runs comprehensive test suites
- Creates logs in
```
~/scripts/logs/
```
- Provides setup summary

Testing

After building, run validation tests:

docker run --rm ai-agents-sandbox/devcontainer:latest /usr/local/bin/test-tools.sh
docker run --rm ai-agents-sandbox/devcontainer:latest /usr/local/bin/test-permissions.sh

Network tests require proper compose setup:

# From .devcontainer/ directory with compose running
docker exec devcontainer /usr/local/bin/test-network.sh

Extending the Base Image

Projects can extend this base:

FROM ai-agents-sandbox/devcontainer:latest
# Add project-specific tools
USER claude
WORKDIR /workspace

Remember: Maintain security constraints when extending.

Notification System

The base image includes a notification hook for alerting the host:

Hook Location

/home/claude/claude-defaults/hooks/notify.sh

Usage

# From within container
/home/claude/claude-defaults/hooks/notify.sh "type" "message"

# Types: error, clarification, blocked, approval, complete, test

Integration

Writes to
```
/workspace/.notifications/
```
(mounted from host)
Host watcher script monitors for notifications
Supports urgency levels for desktop alerts

See root CLAUDE.md for complete notification system documentation.

devcontainer_base/CLAUDE.md

This directory contains the foundation Docker image for secure devcontainer environments.

Purpose

Provides a reusable base image with:

Non-root user setup (claude:local-ai-team)
Development tools (Node.js, Python/uv, Docker CLI)
Security controls and network isolation support
Claude Code defaults and linting hooks
Testing utilities for validation

Build Process

The base image is built using:

./images/build.sh devcontainer  # Builds ai-agents-sandbox/devcontainer:latest
# Or from images directory:
cd images && ./build.sh devcontainer

Directory Structure

/scripts/

Security and setup scripts installed in the image:

```
get-whitelist.sh
```
: Merges whitelist files from multiple sources
- Combines built-in defaults with project-specific domains
- Outputs merged list for tinyproxy configuration
```
non-root-post-create.sh
```
: Post-creation setup for non-root user
- Sets up Docker certificates for DinD
- Configures Claude Code settings
- Initializes development environment
- Creates logs in
```
~/scripts/logs/
```
  to avoid conflicts with
```
.claude/
```
  directory
```
setup-claude-defaults.sh
```
: Installs Claude Code configurations
- Copies agent definitions to
```
.claude/agents/
```
- Sets up linting hooks in
```
.claude/hooks/
```
- Configures default settings
- Handles ownership gracefully, excluding
```
logs/
```
  and
```
projects/
```
  directories
```
setup-p10k.sh
```
: Configures Powerlevel10k theme for zsh
- Interactive theme configuration
- Terminal appearance customization
```
test-network.sh
```
: Network isolation verification
- Tests proxy-only access enforcement
- Validates DNS blocking without proxy
- Verifies whitelist filtering
```
test-permissions.sh
```
: Security permissions validation
- Confirms non-root user enforcement
- Checks file ownership and permissions
- Validates security constraints
- Verifies
```
/home/claude/.claude/projects
```
  directory has group
```
local-ai-team
```
  for shared access
```
test-tools.sh
```
: Development tools verification
- Tests all installed tools and versions
- Validates Python, Node.js, Docker CLI
- Checks linters and formatters

/claude-defaults/

Minimal Claude Code configurations:

```
/hooks/
```
: Notification hook
- ```
notify.sh
```
  : Host notification system for alerts
```
settings.json
```
: Base Claude Code settings (telemetry disabled)
```
settings.local.json
```
: Local settings with notification hook configuration

Note: This is a minimal base image. Users can add their own agents, commands, and hooks during project initialization by choosing to copy their host Claude settings.

/conf/

User configuration files:

```
.tmux.conf
```
: Terminal multiplexer configuration
```
.zshrc
```
: Shell configuration with p10k theme

default-whitelist.txt

Built-in allowed domains for proxy filtering:

Package registries (npm, pip, etc.)
Source control (GitHub, GitLab)
Development tools and documentation

Docker Image Details

Base: Ubuntu 22.04 User: claude (UID 1001) Group: local-ai-team (GID 3000) Shell: zsh with Powerlevel10k

Installed Tools:

Node.js 20 LTS
Python with uv package manager
Docker CLI (for DinD connection)
Git and development utilities
Linters: shellcheck, hadolint, yamllint, ruff, black

Directory Structure:

```
/home/claude/scripts/
```
: Utility scripts and tools (added to PATH)
```
/home/claude/scripts/logs/
```
: Script execution logs (separate from .claude/)
```
/home/claude/claude-defaults/
```
: Source for Claude Code configurations
```
/home/claude/.claude/
```
: Runtime Claude Code configuration (populated by setup script)
```
/home/claude/.claude/projects/
```
: Mount point for host projects directory (group: local-ai-team)
```
/workspace/.notifications/
```
: Mount point for host notification system

Security Constraints

The image enforces:

NO root access: User 'claude' has no sudo
NO passwords: No authentication mechanisms
NO SSH: No remote access services
File permissions: Strict ownership model
Network isolation ready: Designed for internal networks

Container Lifecycle Scripts

entrypoint.sh

(Runtime)

When: Runs every time the container starts
Purpose: Runtime initialization and fixes
Tasks:
- Fixes
```
.codex
```
  directory ownership issues
- Ensures proper file permissions for runtime

non-root-post-create.sh

(Post-Creation)

When: Runs once after container is first created
Purpose: One-time setup and validation
Tasks:
- Orchestrates all setup scripts (P10k, Claude defaults)
- Runs comprehensive test suites
- Creates logs in
```
~/scripts/logs/
```
- Provides setup summary

Testing

After building, run validation tests:

docker run --rm ai-agents-sandbox/devcontainer:latest /usr/local/bin/test-tools.sh
docker run --rm ai-agents-sandbox/devcontainer:latest /usr/local/bin/test-permissions.sh

Network tests require proper compose setup:

# From .devcontainer/ directory with compose running
docker exec devcontainer /usr/local/bin/test-network.sh

Extending the Base Image

Projects can extend this base:

FROM ai-agents-sandbox/devcontainer:latest
# Add project-specific tools
USER claude
WORKDIR /workspace

Remember: Maintain security constraints when extending.

Notification System

The base image includes a notification hook for alerting the host:

Hook Location

/home/claude/claude-defaults/hooks/notify.sh

Usage

# From within container
/home/claude/claude-defaults/hooks/notify.sh "type" "message"

# Types: error, clarification, blocked, approval, complete, test

Integration

Writes to
```
/workspace/.notifications/
```
(mounted from host)
Host watcher script monitors for notifications
Supports urgency levels for desktop alerts

See root CLAUDE.md for complete notification system documentation.

devcontainer_base/CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password