Triple-C (Claude-Code-Container) sandboxes Claude Code inside Docker containers so that even in its most permissive mode — `--dangerously-skip-permissions` — Claude only has access to files and projects you explicitly provide. The project consists of two components: a **Docker container image** pre-loaded with development tools, and a **cross-platform desktop application** for managing project containers, terminal sessions, and authentication.
Tauri uses a Rust backend paired with a web-based frontend rendered by the OS-native webview (WebKitGTK on Linux, WebKit on macOS, WebView2 on Windows). This gives us:
- **Small binary size** — Tauri apps ship at ~5-10 MB vs. Electron's ~150+ MB because there's no bundled Chromium. The OS webview is reused.
- **Native performance** — The backend is compiled Rust. Docker API calls, PTY streaming, and file I/O all happen in native code, not in a JavaScript runtime.
- **Cross-platform from one codebase** — Builds for Linux, macOS, and Windows from the same source. Tauri handles platform differences (file dialogs, system tray, window management).
- **Security model** — Tauri v2 uses a capabilities system where frontend code must be explicitly granted permission to access system features (filesystem, events, shell). This prevents the webview from doing anything not listed in `capabilities/default.json`.
- **Mature plugin ecosystem** — First-party plugins for OS dialog pickers (`tauri-plugin-dialog`), secure storage (`tauri-plugin-store`), and URL opening (`tauri-plugin-opener`) saved significant development time.
### React 19 + TypeScript (Frontend)
**Chosen over:** Svelte, Vue, Solid, vanilla JS
- **Ecosystem maturity** — React has the largest library ecosystem. The xterm.js terminal emulator, which is central to our app, has well-documented React integration patterns.
- **TypeScript** — Enforces type safety across the frontend, particularly important for the Tauri IPC boundary where `invoke()` calls must match Rust command signatures exactly.
- **Hooks-based architecture** — React hooks (`useTerminal`, `useProjects`, `useDocker`, `useSettings`) encapsulate all Tauri IPC calls, keeping components focused on rendering.
- **Concurrent rendering** — React 19's concurrent features prevent terminal I/O from blocking UI updates in the sidebar or settings panels.
- **Minimal boilerplate** — A single `create()` call defines the entire store. No providers, reducers, or action creators needed.
- **Direct mutation-style API** — `set({ projects })` is simpler than Redux dispatch patterns, which matters when state updates come from both user actions and async Tauri events.
- **No context provider** — Zustand stores live outside the React tree, so any component can access state without prop drilling or provider nesting. Terminal sessions, project lists, and UI state all share one store without performance penalties.
- **Small footprint** — ~1 KB gzipped. The app is already bundling xterm.js (~300 KB), so keeping other dependencies small matters.
- **Rapid iteration** — Utility classes (`flex`, `gap-4`, `rounded-lg`) allow UI adjustments without switching between files. Padding, spacing, and layout changes happen inline.
- **Dark theme via CSS variables** — The app uses CSS custom properties (`--bg-primary`, `--text-secondary`, `--accent`) defined in `index.css`. Tailwind's arbitrary value syntax (`bg-[var(--bg-primary)]`) bridges utility classes with the theme system.
- **No runtime cost** — Tailwind v4 compiles to static CSS at build time. No JavaScript style injection at runtime.
**Chosen over:** Building a custom terminal renderer, using an iframe-based terminal
- **Full VT100/xterm compatibility** — Claude Code uses ANSI escape sequences for colors, cursor movement, line clearing, and interactive prompts. xterm.js handles all of these correctly, including 256-color and truecolor support.
- **WebGL renderer** — The `@xterm/addon-webgl` addon renders the terminal using WebGL for hardware-accelerated text drawing. This is critical for smooth scrolling when Claude outputs large amounts of text.
- **Fit addon** — `@xterm/addon-fit` automatically calculates terminal dimensions (cols/rows) from the container element size. Combined with a `ResizeObserver`, the terminal re-fits when the window or panel is resized, and the backend `docker exec` session is resized to match via `resize_exec()`.
- **Web links addon** — `@xterm/addon-web-links` makes URLs in terminal output clickable. Combined with `tauri-plugin-opener`, clicked URLs open in the host browser — essential for the `claude login` OAuth flow where Claude prints an authentication URL that must be opened on the host.
- **Bidirectional data flow** — xterm.js exposes `term.onData()` for user keystrokes and `term.write()` for incoming data. This maps directly to our Tauri event-based streaming architecture.
Implementation gotchas for the terminal view and its global controls (merged in PR #7, `terminal-layout-statusbar`):
- **xterm padding lives on a wrapper, never the host.** FitAddon measures the same element that `term.open()` mounts into, so any padding on that host element makes the grid overhang and clip its rightmost column / bottom row. Padding must live on a **wrapper `div`**; the xterm host fills it with no padding of its own. Do not reintroduce padding on the host element in `TerminalView.tsx`.
- **STT mic and "Jump to Current" live in the global `StatusBar`, not per-terminal overlays.** There is a single `useSTT` instance in `App.tsx` bound to the active session. `Ctrl+Shift+M` routes through the Zustand store (`sttToggle`).
- **Recording is pinned to where it started.** The STT transcript targets `recordingSessionIdRef` (the session recording began in), **not** the live active session — switching tabs mid-recording must not misroute the transcript.
- **"Jump to Current" state is written only by the active terminal.** The active `TerminalView` surfaces `terminalAtBottom` and `scrollActiveToBottom` through the store; only the active terminal writes them, and they are cleared on its unmount.
- **Set store function values via object-merge, not the updater form** — `set({ fn: value })`, not `set(state => ...)` — when publishing action callbacks (like `scrollActiveToBottom`) into the Zustand store.
**Chosen over:** Shelling out to the `docker` CLI, dockerode (Node.js), docker-api (Python)
- **Native Rust** — bollard is a pure Rust Docker API client. It communicates directly with the Docker daemon over the Unix socket (`/var/run/docker.sock`) or Windows named pipe (`//./pipe/docker_engine`). No subprocess spawning, no CLI output parsing.
- **Async/streaming** — Container creation, image building, and exec sessions are all async. Image pulls and builds stream progress via `futures::Stream`, which we forward to the frontend as real-time status updates.
- **Type-safe** — Docker API responses are deserialized into Rust structs. Container configs, mount options, and exec parameters are all checked at compile time.
- **Exec with PTY** — bollard supports `docker exec` with `tty: true` and `attach_stdin/stdout/stderr`, giving us a full interactive pseudoterminal inside the container. This is the core mechanism that makes the terminal work.
### keyring (Secure Credential Storage)
**Chosen over:** Storing API keys in a config file, using environment variables, Tauri plugin-store
- **OS-native security** — `keyring` uses macOS Keychain, Windows Credential Manager, and Linux Secret Service (GNOME Keyring / KWallet). API keys never touch the filesystem in plaintext.
- **Simple API** — `Entry::new("triple-c", "anthropic-api-key")?.set_password(key)?` is the entire storage operation. No encryption key management needed.
- **Cross-platform** — One crate handles all three OS credential stores with feature flags (`apple-native`, `windows-native`, `linux-native`).
- **Claude Code compatibility** — Claude Code's installer (`curl -fsSL https://claude.ai/install.sh | bash`) targets glibc-based systems. Alpine's musl libc causes compatibility issues with Node.js native modules and some Claude Code dependencies.
- **Package availability** — Ubuntu 24.04 has up-to-date packages for all pre-installed tools (Python 3.12, Git 2.43, etc.) without requiring third-party repositories for most things.
- **Developer familiarity** — Claude Code will run `apt install` to add tools at runtime. Ubuntu/Debian's package manager is the most widely documented, so Claude's suggestions will work correctly.
- **LTS support** — Ubuntu 24.04 is supported until 2029, providing a stable base that won't require frequent image rebuilds.
The application uses two IPC mechanisms between the React frontend and Rust backend:
**Request/Response** (`invoke()`): Used for discrete operations — starting containers, saving settings, listing projects. The frontend calls `invoke("command_name", { args })` and awaits a typed result.
**WebSocket Streaming** (Web Terminal): Used for remote terminal access from browsers on the local network. An axum HTTP+WebSocket server runs inside the Tauri process, sharing the same `ExecSessionManager` via `Arc`-wrapped stores. The WebSocket uses a JSON protocol with base64-encoded terminal data. Each browser connection can open multiple terminal sessions; all sessions are cleaned up when the WebSocket disconnects.
**Event Streaming** (`emit()`/`listen()`): Used for continuous data — terminal I/O. When a terminal session is opened, the Rust backend spawns two tokio tasks:
1.**Output reader** — Reads from the Docker exec stdout stream and emits `terminal-output-{sessionId}` events to the frontend.
2.**Input writer** — Listens on an `mpsc::unbounded_channel` for data sent from the frontend via `invoke("terminal_input")` and writes it to the Docker exec stdin.
1.**First start**: A new container is created with bind mounts, named volumes, environment variables, and labels. The entrypoint remaps UID/GID, configures SSH and git, rebuilds the scheduler crontab, then runs `sleep infinity` to keep the container alive.
2.**Terminal open**: `docker exec` launches `claude` with a PTY in the running container, with the permission-mode flags from `PermissionMode::cli_args()` (or `bash -l` for a shell session).
4.**Restart**: `docker start` resumes the existing container — unless `container_needs_recreation()` finds a `triple-c.*` label that no longer matches the project's settings, in which case the container is committed to a snapshot image (`triple-c-snapshot-{projectId}:latest`), removed, and recreated from that snapshot. Installed tools survive; the named volumes are untouched.
5.**Reset**: `rebuild_project_container` closes live exec sessions, removes the container, removes the snapshot image, calls `remove_project_volumes` to delete **both** named volumes, then starts fresh from the clean base image.
Two named volumes exist per project and they are the only ones it owns:
| `triple-c-claude-config-{projectId}` | `/home/claude/.claude` | Claude Code config: OAuth credential, settings, skills/agents/commands, session transcripts, scheduler state. Nested inside the home volume; Docker gives the more specific mount precedence. |
`remove_project_volumes` names those two volumes explicitly (no prefix sweep) and is called from
exactly two places: `remove_project` and `rebuild_project_container`. Ordinary container removal
passes `v: false`, so stop/start and recreation never touch the volumes — **only Reset and project
removal delete them.** A Reset therefore destroys the `claude login` credential, installed skills,
session transcripts and scheduled tasks; it does not touch host bind mounts, the project record, or
host keychain secrets.
### Permission Modes
`PermissionMode` (`models/project.rs`) is a four-state enum replacing the earlier `full_permissions`
boolean. It reaches Claude Code by two different routes:
| **Anthropic** | Either the shared `CLAUDE_CODE_OAUTH_TOKEN` injected from the OS keychain, or a per-container `claude login` whose credential persists in the `.claude` config volume. The OAuth URL opens in the host browser via URL detection. | Default — personal and team use |
| **AWS Bedrock** | Per-project AWS credentials (static keys, named profile, or bearer token) injected as env vars. `~/.aws` config optionally bind-mounted read-only; SSO sessions are validated before launching Claude for profile auth. | Enterprise environments using Bedrock |
| **Ollama** | `ANTHROPIC_BASE_URL` points at an Ollama server; `ANTHROPIC_AUTH_TOKEN` is set to the placeholder `ollama`. Ollama implements `POST /v1/messages` natively. | Local models (best-effort) |
| **llama.cpp** | `ANTHROPIC_BASE_URL` points at a `llama-server` (default port 8080); `ANTHROPIC_AUTH_TOKEN` is set to the placeholder `llama.cpp`, which `llama-server` ignores unless started with `--api-key`. `llama-server` implements `POST /v1/messages` and `/v1/messages/count_tokens` natively. | Local models (best-effort) |
| **OpenAI Compatible** | `ANTHROPIC_BASE_URL` plus `ANTHROPIC_AUTH_TOKEN` point at a gateway. **Despite the name, the endpoint must implement the Anthropic Messages API** — Claude Code only ever sends `POST /v1/messages?beta=true`, never `/v1/chat/completions`. LiteLLM works; a bare OpenAI-only server does not. | Anthropic-shaped gateways (best-effort) |
#### Model aliases on custom endpoints
`Backend::uses_custom_endpoint()` (Ollama, llama.cpp, OpenAI Compatible) gates the emission of
`ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL`, computed by
`docker::container::compute_model_aliases`. All four default to the backend's resolved model id;
each backend carries an optional `haiku_model_id` override, because the Haiku alias is what Claude
Code uses for background work. Anthropic and Bedrock emit none of them and keep Claude Code's
defaults; the four names are in `MANAGED_AUTH_KEYS`, so switching away from a custom endpoint
blanks the values baked into the snapshot image. The resolved alias set is folded into each
backend's `triple-c.*-fingerprint` label, since `container_needs_recreation` is label-based and
never diffs env. `ANTHROPIC_SMALL_FAST_MODEL` is deprecated and unused.
A common Docker pain point: files created inside the container have the container user's UID (1000 by default), which may not match the host user. This causes permission errors on bind-mounted project directories.
The entrypoint solves this by:
1. Reading `HOST_UID` and `HOST_GID` environment variables (set by the Rust backend using `id -u`/`id -g`).
2. Running `usermod`/`groupmod` to change the `claude` user's UID/GID to match.
3. Relocating any existing system user/group that conflicts with the target UID/GID.
4. Fixing ownership of `/home/claude` after the change.
This runs as root in the entrypoint, then the final `exec su -s /bin/bash claude -c "exec sleep infinity"` drops to the remapped user.
### SSH Key Handling
Host SSH keys are mounted **read-only** at `/tmp/.host-ssh` (a staging directory), not directly at `/home/claude/.ssh`. The entrypoint copies them to the correct location and fixes permissions:
- Private keys: `chmod 600`
- Public keys: `chmod 644`
-`.ssh` directory: `chmod 700`
-`known_hosts` is populated with GitHub, GitLab, and Bitbucket host keys, deduplicated with `sort -u`
This avoids the common Docker problem where bind-mount permissions can't be changed (the mount reflects the host filesystem's permissions, and `chmod` on a read-only mount fails).
The projects store uses **atomic writes** (write to `.json.tmp`, then `rename()`) to prevent data corruption if the app crashes mid-write. Corrupted files are backed up to `.json.bak` before being replaced.
### URL Detection for OAuth
Claude Code's `login` command prints an OAuth URL that can exceed 200 characters. Terminal emulators hard-wrap long lines, splitting the URL across multiple lines with `\r\n` characters. The xterm.js WebLinksAddon only joins soft-wrapped lines (detected via the `isWrapped` flag on buffer lines), so the URL match is truncated.
The `TerminalView` component works around this with a **URL accumulator**:
1. All terminal output is buffered (capped at 8 KB).
2. After 150ms of silence (debounced), the buffer is stripped of ANSI escape codes and hard newlines.
3. If the reassembled text contains a URL longer than 80 characters, it's written back to the terminal as a single clickable line.
4. The WebLinksAddon detects the clean URL and `tauri-plugin-opener` opens it in the host browser when clicked.
