Claude Chromium

One Compose project with three containers:

• claude-chromium: your existing Chromium desktop, Claude CLI, automation tools and persistent user state. It now also runs tmux sessions.
• claude-docker: your existing Docker-in-Docker daemon.
• claude-cloud: browser terminal UI, Python session manager, WeTTY and Nginx. Every terminal executes inside claude-chromium as its configured user.

For the terminal replacement and rebuild instructions, see WETTY-MIGRATION.md. For the subsequent layout and navigation fixes, see WETTY-FIXES.md. For the latest startup size handshake, see WETTY-STARTUP.md.

The build sources are separated into build/chromium, build/docker and build/terminal. DinD still uses its upstream image; its startup script lives in build/docker.

Read only the files needed for your task: MIGRATION.md for applying this merge, ENV.md for settings, and WORKSPACE_SESSIONS.md for URLs.

Setup

For an existing installation, follow MIGRATION.md first. Keep your private files and actual paths. This is source to build on your own Docker host, not a prebuilt image.

For new configuration:

cp .env.example .env
vi .env
stat -c '%g' /var/run/docker.sock

Set HOST_DOCKER_GID to that socket's numeric group. If using a different daemon, configure HOST_DOCKER_SOCKET and inspect that socket instead. All three containers must run on the same daemon. The bridge deliberately does not use Chromium's DinD endpoint.

Keep your existing .secrets/key.txt, private CAs, personal .vimrc, profile, Claude state and desktop mounts. The archive includes a minimal .vimrc for new setup; retain your current version. Default named volumes are external and must already exist. Choose CC_VOLUMES_EXTERNAL=false only for a fresh installation with deliberately new volume names.

docker compose config --quiet
docker compose build --pull
docker compose up -d
bash scripts/verify-live.sh

The web terminal is available at http://127.0.0.1:7681 by default. HOST_BIND_IP and HOST_PORT control that listener.

Terminal URLs

See NATIVE-SCROLLING.md for the pinned xterm beta, native tmux wheel behavior, Vim mouse setting, safe gateway-only rebuild and validation notes.

With default WORKSPACE_ROOT=/opt/claude, / opens /opt/claude inside Chromium. /docker opens /opt/claude/docker. /claude?task=2 opens another task in /opt/claude/claude. /claude?task=Research opens or creates a named task there. Names are unique within each project, and the same name can exist in other projects.

The Open project... search shows one row per running project when empty; when typing, matching running tasks appear as project: Task name. Unopened workspace folders appear below alphabetically as 📁 name. Click an inactive folder to start its first task, or use ↗ to open it in a new tab. Once any task is running in a project, its folder is hidden to avoid duplicate results; closing its last task makes the folder visible again. Each running project has ↗ and 🗑 actions; 🗑 warns with a list of open tasks and, if confirmed, ends all that project's tmux sessions (not the workspace files). Task search shows ✎, ↗ and 🗑 for individual tasks. The backend reads immediate directory names within Chromium through its existing Docker connection, so no additional workspace bind mount is needed in claude-cloud. Creating an entirely new project is labeled Create new project. Both searches keep same-tab and new-tab creation actions at the bottom, even before typing. Project creation prompts for the required name when search is empty (cancel safely does nothing), while task creation opens the next numbered task in the current project without requiring an alias. Once a name is typed, the existing name-specific creation actions are shown. The Open project task... search still lists only tasks from the current project, never filesystem folders.

Search results have horizontal separators between running projects, inactive workspace folders and creation actions, and between existing tasks and task creation actions. If an entered project name already exists, its creation prompt closes the search dropdown, displays a browser alert and preserves the duplicate-project warning in the toolbar.

Shells use Chromium's HOME, Claude login/state, PATH, desktop environment and Docker configuration. Opening a terminal does not automatically launch Claude; run claude when desired. Session files use the existing workspace mount.

Restarting claude-cloud disconnects browser clients but preserves Chromium tmux sessions. Reopen the same URL to reattach. Recreating/stopping claude-chromium ends its processes, including tmux; workspace files remain persistent.

Access boundary

The gateway mounts the containing daemon's Unix socket to run remote exec commands. That socket grants Docker administration privileges despite a read-only mount. Keep this unauthenticated terminal on loopback or behind your private VPN/authenticated access layer. No public daemon port is added. Existing privileged DinD and Chromium sandbox exceptions are retained and documented in the review.

Source checks and packaging

python3 -m unittest discover -s tests -v
node tests/test_toolbar.js
node tests/test_delete_fallback.js
node tests/test_project_delete.js
node tests/test_search.js
node tests/test_navigation_history.js
bash scripts/package.sh /tmp/claude-chromium-merged.zip

Python checks require aiohttp. Live verification requires a running Docker stack. The archive intentionally excludes runtime credentials, profiles, logs and private certificates; it includes all build sources and the merged environment template.