9b8562b746
Adds a webui service to docker-compose that wraps Claude Code in ttyd, serving a browser-accessible terminal on port 7681. The webui reuses Dockerfile.claude (ttyd added to apt deps) with a dedicated entrypoint script that enforces WEBUI_PASSWORD before starting. Network isolation is identical to the CLI container: claude-internal only, all egress via the proxy allowlist. claude.sh gains web and web-stop commands.
99 lines
4.2 KiB
Markdown
99 lines
4.2 KiB
Markdown
# Project Guidance
|
|
|
|
This file provides context and guidance for working with this project.
|
|
|
|
## Project Overview
|
|
|
|
**docker-claude** runs Claude Code inside a hardened Docker environment with a Squid proxy sidecar. The goal is full host encapsulation: Claude cannot access the host filesystem or network. All egress is routed through an allowlist-enforcing proxy.
|
|
|
|
## Architecture
|
|
|
|
Three containers managed by Docker Compose:
|
|
|
|
- **`claude`** — Claude Code CLI, non-root (UID 1000), isolated to an internal-only Docker network
|
|
- **`webui`** — Claude Code as a browser terminal (ttyd on port 7681), same image as `claude`, non-root (UID 1000), same network isolation, basic auth required
|
|
- **`proxy`** — Squid forward proxy, non-root (UID 13), bridges the internal network to the internet with an egress allowlist
|
|
|
|
Key Docker network property: `claude-internal` has `internal: true`, meaning Docker adds no default gateway. The `claude` and `webui` containers physically cannot reach the internet without going through the `proxy` container.
|
|
|
|
The `webui` service reuses `Dockerfile.claude`. Its entrypoint (`webui-entrypoint.sh`) starts `ttyd --credential user:pass claude` instead of `claude` directly.
|
|
|
|
## File Structure
|
|
|
|
```
|
|
docker-claude/
|
|
├── claude.sh # Control script: start/stop/run/web/web-stop/update/logs/status/shell
|
|
├── docker-compose.yml # Service definitions and network topology
|
|
├── Dockerfile.claude # Claude Code + ttyd container (node:20-slim, UID 1000)
|
|
├── Dockerfile.proxy # Squid proxy sidecar (ubuntu:22.04, UID 13)
|
|
├── webui-entrypoint.sh # Entrypoint for webui service: starts ttyd wrapping claude
|
|
├── proxy/
|
|
│ └── squid.conf # Squid ACL config — egress allowlist lives here
|
|
├── .env.example # Template for ANTHROPIC_API_KEY, WEBUI_PASSWORD, etc.
|
|
├── .gitignore # Excludes .env and logs
|
|
├── .dockerignore # Keeps .env out of build context
|
|
└── README.md # User documentation
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
```bash
|
|
chmod +x claude.sh
|
|
cp .env.example .env # set ANTHROPIC_API_KEY (and WEBUI_PASSWORD for web mode)
|
|
./claude.sh start # build + start proxy + launch Claude interactively (CLI)
|
|
./claude.sh web # build + start proxy + webui (browser terminal on :7681)
|
|
./claude.sh update # rebuild images (no cache) after upstream updates
|
|
```
|
|
|
|
## Coding Standards
|
|
|
|
- Shell scripts use `set -euo pipefail`
|
|
- Dockerfiles use `--no-install-recommends` and clean apt caches in the same layer
|
|
- No capabilities granted; `no-new-privileges` on all containers
|
|
- `.env` is never committed (enforced by `.gitignore` and `.dockerignore`)
|
|
- Commit messages follow **Angular format**: `type(scope): summary`
|
|
|
|
## Extending the Egress Allowlist
|
|
|
|
Add domains to `proxy/squid.conf` under the `allowed_sites` ACL, then rebuild:
|
|
|
|
```bash
|
|
docker compose -p claude-secure build proxy
|
|
./claude.sh stop && ./claude.sh start
|
|
```
|
|
|
|
## Environment Persistence
|
|
|
|
This sandbox has a persistent environment file at `/etc/sandbox-persistent.sh`.
|
|
|
|
This file is automatically sourced in all shell contexts:
|
|
- **Non-interactive shells**: via `BASH_ENV=/etc/sandbox-persistent.sh`
|
|
- **Login shells**: via `/etc/profile.d/sandbox-persistent.sh`
|
|
- **Interactive shells**: via `/etc/bash.bashrc` and `~/.bashrc`
|
|
|
|
## Critical: Shell Completions Must NOT Be in the Persistent Environment File
|
|
|
|
**NEVER add shell completion scripts to `/etc/sandbox-persistent.sh`.**
|
|
|
|
Shell completion scripts will completely break the bash tool when sourced via the persistent environment file.
|
|
|
|
## Network access
|
|
|
|
There is a firewall in place to restrict outbound network access. If you need http/https access to
|
|
an external service, request it by running:
|
|
|
|
```bash
|
|
sbx policy allow network [domain]
|
|
```
|
|
|
|
## Git Authentication
|
|
|
|
The sandbox proxy handles GitHub authentication automatically by injecting credentials for HTTPS Git operations.
|
|
|
|
## Additional Notes
|
|
|
|
- Always read relevant files before making changes
|
|
- Run tests after making modifications
|
|
- Follow the existing code structure and patterns
|
|
- You have sudo permissions, so you can install necessary packages
|
|
- npm, pip and uv are already available for package management
|