feat: show container progress in modal and add terminal jump-to-bottom button

Show container start/stop/rebuild progress as a modal popup instead of
inline text that was never visible. Add optimistic status updates so the
status dot turns yellow immediately. Also add a "Jump to Current" button
in the terminal when scrolled away from the bottom.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitea/workflows/backfill-releases.yml

@@ -0,0 +1,84 @@
+name: Backfill Releases to GitHub
+
+on:
+  workflow_dispatch:
+
+jobs:
+  backfill:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Backfill all Gitea releases to GitHub
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          GITEA_API: https://repo.anhonesthost.net/api/v1
+          GITEA_REPO: cybercovellc/triple-c
+          GITHUB_REPO: shadowdao/triple-c
+        run: |
+          set -e
+
+          echo "==> Fetching releases from Gitea..."
+          RELEASES=$(curl -sf \
+            -H "Authorization: token $GITEA_TOKEN" \
+            "$GITEA_API/repos/$GITEA_REPO/releases?limit=50")
+
+          echo "$RELEASES" | jq -c '.[]' | while read release; do
+            TAG=$(echo "$release" | jq -r '.tag_name')
+            NAME=$(echo "$release" | jq -r '.name')
+            BODY=$(echo "$release" | jq -r '.body')
+            IS_PRERELEASE=$(echo "$release" | jq -r '.prerelease')
+            IS_DRAFT=$(echo "$release" | jq -r '.draft')
+
+            EXISTS=$(curl -sf \
+              -H "Authorization: Bearer $GH_PAT" \
+              -H "Accept: application/vnd.github+json" \
+              "https://api.github.com/repos/$GITHUB_REPO/releases/tags/$TAG" \
+              -o /dev/null -w "%{http_code}" || true)
+
+            if [ "$EXISTS" = "200" ]; then
+              echo "==> Skipping $TAG (already exists on GitHub)"
+              continue
+            fi
+
+            echo "==> Creating release $TAG..."
+            RESPONSE=$(curl -sf -X POST \
+              -H "Authorization: Bearer $GH_PAT" \
+              -H "Accept: application/vnd.github+json" \
+              -H "Content-Type: application/json" \
+              https://api.github.com/repos/$GITHUB_REPO/releases \
+              -d "{
+                \"tag_name\": \"$TAG\",
+                \"name\": \"$NAME\",
+                \"body\": $(echo "$BODY" | jq -Rs .),
+                \"draft\": $IS_DRAFT,
+                \"prerelease\": $IS_PRERELEASE
+              }")
+
+            UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.upload_url' | sed 's/{?name,label}//')
+
+            echo "$release" | jq -c '.assets[]?' | while read asset; do
+              ASSET_NAME=$(echo "$asset" | jq -r '.name')
+              ASSET_ID=$(echo "$asset" | jq -r '.id')
+
+              echo "  ==> Downloading $ASSET_NAME..."
+              DOWNLOAD_URL=$(echo "$asset" | jq -r '.browser_download_url')
+              curl -sfL -o "/tmp/$ASSET_NAME" \
+                -H "Authorization: token $GITEA_TOKEN" \
+                "$DOWNLOAD_URL"
+
+              echo "  ==> Uploading $ASSET_NAME to GitHub..."
+              ENCODED_NAME=$(python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1]))" "$ASSET_NAME")
+              curl -sf -X POST \
+                -H "Authorization: Bearer $GH_PAT" \
+                -H "Accept: application/vnd.github+json" \
+                -H "Content-Type: application/octet-stream" \
+                --data-binary "@/tmp/$ASSET_NAME" \
+                "$UPLOAD_URL?name=$ENCODED_NAME"
+
+              echo "    Uploaded: $ASSET_NAME"
+            done
+
+            echo "==> Done: $TAG"
+          done
+
+          echo "==> Backfill complete."

.gitea/workflows/build-app.yml

@@ -20,6 +20,32 @@ jobs:
   build-linux:
     runs-on: ubuntu-latest
     steps:
+      - name: Install Node.js 22
+        run: |
+          NEED_INSTALL=false
+          if command -v node >/dev/null 2>&1; then
+            NODE_MAJOR=$(node --version | sed 's/v\([0-9]*\).*/\1/')
+            OLD_NODE_DIR=$(dirname "$(which node)")
+            echo "Found Node.js $(node --version) at $(which node) (major: ${NODE_MAJOR})"
+            if [ "$NODE_MAJOR" -lt 22 ]; then
+              echo "Node.js ${NODE_MAJOR} is too old, removing before installing 22..."
+              sudo rm -f "${OLD_NODE_DIR}/node" "${OLD_NODE_DIR}/npm" "${OLD_NODE_DIR}/npx" "${OLD_NODE_DIR}/corepack"
+              hash -r
+              NEED_INSTALL=true
+            fi
+          else
+            echo "Node.js not found, installing 22..."
+            NEED_INSTALL=true
+          fi
+          if [ "$NEED_INSTALL" = true ]; then
+            curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+            sudo apt-get install -y nodejs
+            hash -r
+          fi
+          echo "Node.js at: $(which node)"
+          node --version
+          npm --version
+
       - name: Checkout
         uses: actions/checkout@v4
         with:
@@ -61,29 +87,35 @@ jobs:
             xdg-utils
 
       - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
+        run: |
-
+          if command -v rustup >/dev/null 2>&1; then
-      - name: Rust cache
+            echo "Rust already installed: $(rustc --version)"
-        uses: swatinem/rust-cache@v2
+            rustup update stable
-        with:
+            rustup default stable
-          workspaces: "./app/src-tauri -> target"
+          else
-
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
-      - name: Install Node.js
+          fi
-        uses: actions/setup-node@v4
+          export PATH="$HOME/.cargo/bin:$PATH"
-        with:
+          rustc --version
-          node-version: "22"
+          cargo --version
 
       - name: Install frontend dependencies
         working-directory: ./app
-        run: npm ci
+        run: |
+          rm -rf node_modules package-lock.json
+          npm install
 
       - name: Install Tauri CLI
         working-directory: ./app
-        run: npx tauri --version || npm install @tauri-apps/cli
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          npx tauri --version || npm install @tauri-apps/cli
 
       - name: Build Tauri app
         working-directory: ./app
-        run: npx tauri build
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          npx tauri build
 
       - name: Collect artifacts
         run: |
@@ -119,6 +151,116 @@ jobs:
               "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets?name=${filename}"
           done
 
+  build-macos:
+    runs-on: macos-latest
+    steps:
+      - name: Install Node.js 22
+        run: |
+          NEED_INSTALL=false
+          if command -v node >/dev/null 2>&1; then
+            NODE_MAJOR=$(node --version | sed 's/v\([0-9]*\).*/\1/')
+            echo "Found Node.js $(node --version) (major: ${NODE_MAJOR})"
+            if [ "$NODE_MAJOR" -lt 22 ]; then
+              echo "Node.js ${NODE_MAJOR} is too old, upgrading to 22..."
+              NEED_INSTALL=true
+            fi
+          else
+            echo "Node.js not found, installing 22..."
+            NEED_INSTALL=true
+          fi
+          if [ "$NEED_INSTALL" = true ]; then
+            brew install node@22
+            brew link --overwrite node@22
+          fi
+          node --version
+          npm --version
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Compute version
+        id: version
+        run: |
+          COMMIT_COUNT=$(git rev-list --count HEAD)
+          VERSION="0.1.${COMMIT_COUNT}"
+          echo "VERSION=${VERSION}" >> $GITHUB_OUTPUT
+          echo "Computed version: ${VERSION}"
+
+      - name: Set app version
+        run: |
+          VERSION="${{ steps.version.outputs.VERSION }}"
+          sed -i '' "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" app/src-tauri/tauri.conf.json
+          sed -i '' "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" app/package.json
+          sed -i '' "s/^version = \".*\"/version = \"${VERSION}\"/" app/src-tauri/Cargo.toml
+          echo "Patched version to ${VERSION}"
+
+      - name: Install Rust stable
+        run: |
+          if command -v rustup >/dev/null 2>&1; then
+            echo "Rust already installed: $(rustc --version)"
+            rustup update stable
+            rustup default stable
+          else
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+          fi
+          export PATH="$HOME/.cargo/bin:$PATH"
+          rustup target add aarch64-apple-darwin x86_64-apple-darwin
+          rustc --version
+          cargo --version
+
+      - name: Install frontend dependencies
+        working-directory: ./app
+        run: |
+          rm -rf node_modules
+          npm install
+
+      - name: Install Tauri CLI
+        working-directory: ./app
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          npx tauri --version || npm install @tauri-apps/cli
+
+      - name: Build Tauri app (universal)
+        working-directory: ./app
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          npx tauri build --target universal-apple-darwin
+
+      - name: Collect artifacts
+        run: |
+          mkdir -p artifacts
+          cp app/src-tauri/target/universal-apple-darwin/release/bundle/dmg/*.dmg artifacts/ 2>/dev/null || true
+          cp app/src-tauri/target/universal-apple-darwin/release/bundle/macos/*.app.tar.gz artifacts/ 2>/dev/null || true
+          ls -la artifacts/
+
+      - name: Upload to Gitea release
+        if: gitea.event_name == 'push'
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          TAG="v${{ steps.version.outputs.VERSION }}-mac"
+          # Create release
+          curl -s -X POST \
+            -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"tag_name\": \"${TAG}\", \"name\": \"Triple-C v${{ steps.version.outputs.VERSION }} (macOS)\", \"body\": \"Automated build from commit ${{ gitea.sha }}\"}" \
+            "${GITEA_URL}/api/v1/repos/${REPO}/releases" > release.json
+          RELEASE_ID=$(cat release.json | grep -o '"id":[0-9]*' | head -1 | grep -o '[0-9]*')
+          echo "Release ID: ${RELEASE_ID}"
+          # Upload each artifact
+          for file in artifacts/*; do
+            [ -f "$file" ] || continue
+            filename=$(basename "$file")
+            echo "Uploading ${filename}..."
+            curl -s -X POST \
+              -H "Authorization: token ${TOKEN}" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary "@${file}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets?name=${filename}"
+          done
+
   build-windows:
     runs-on: windows-latest
     defaults:

.gitea/workflows/build.yml

@@ -21,6 +21,9 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
@@ -36,6 +39,7 @@ jobs:
         with:
           context: ./container
           file: ./container/Dockerfile
+          platforms: linux/amd64,linux/arm64
           push: ${{ gitea.event_name == 'push' }}
           tags: |
             ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

.gitea/workflows/sync-release.yml

@@ -0,0 +1,60 @@
+name: Sync Release to GitHub
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  sync-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Mirror release to GitHub
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+          GITHUB_REPO: shadowdao/triple-c
+          RELEASE_TAG: ${{ gitea.event.release.tag_name }}
+          RELEASE_NAME: ${{ gitea.event.release.name }}
+          RELEASE_BODY: ${{ gitea.event.release.body }}
+          IS_PRERELEASE: ${{ gitea.event.release.prerelease }}
+          IS_DRAFT: ${{ gitea.event.release.draft }}
+        run: |
+          set -e
+
+          echo "==> Creating release $RELEASE_TAG on GitHub..."
+
+          RESPONSE=$(curl -sf -X POST \
+            -H "Authorization: Bearer $GH_PAT" \
+            -H "Accept: application/vnd.github+json" \
+            -H "Content-Type: application/json" \
+            https://api.github.com/repos/$GITHUB_REPO/releases \
+            -d "{
+              \"tag_name\": \"$RELEASE_TAG\",
+              \"name\": \"$RELEASE_NAME\",
+              \"body\": $(echo "$RELEASE_BODY" | jq -Rs .),
+              \"draft\": $IS_DRAFT,
+              \"prerelease\": $IS_PRERELEASE
+            }")
+
+          UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.upload_url' | sed 's/{?name,label}//')
+          echo "Release created. Upload URL: $UPLOAD_URL"
+
+          echo '${{ toJSON(gitea.event.release.assets) }}' | jq -c '.[]' | while read asset; do
+            ASSET_NAME=$(echo "$asset" | jq -r '.name')
+            ASSET_URL=$(echo "$asset" | jq -r '.browser_download_url')
+
+            echo "==> Downloading asset: $ASSET_NAME"
+            curl -sfL -o "/tmp/$ASSET_NAME" "$ASSET_URL"
+
+            echo "==> Uploading $ASSET_NAME to GitHub..."
+            ENCODED_NAME=$(python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1]))" "$ASSET_NAME")
+            curl -sf -X POST \
+              -H "Authorization: Bearer $GH_PAT" \
+              -H "Accept: application/vnd.github+json" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary "@/tmp/$ASSET_NAME" \
+              "$UPLOAD_URL?name=$ENCODED_NAME"
+
+            echo "  Uploaded: $ASSET_NAME"
+          done
+
+          echo "==> Release sync complete."

BUILDING.md

@@ -1,6 +1,6 @@
 # Building Triple-C
 
-Triple-C is a Tauri v2 desktop application with a React/TypeScript frontend and a Rust backend. This guide covers building the app from source on Linux and Windows.
+Triple-C is a Tauri v2 desktop application with a React/TypeScript frontend and a Rust backend. This guide covers building the app from source on Linux, macOS, and Windows.
 
 ## Prerequisites (All Platforms)
 
@@ -79,6 +79,57 @@ Build artifacts are located in `app/src-tauri/target/release/bundle/`:
 | Debian pkg | `deb/*.deb`                   |
 | RPM pkg    | `rpm/*.rpm`                   |
 
+## macOS
+
+### 1. Install prerequisites
+
+- **Xcode Command Line Tools** — required for the C/C++ toolchain and system headers:
+
+```bash
+xcode-select --install
+```
+
+No additional system libraries are needed — macOS includes WebKit natively.
+
+### 2. Install Rust targets (universal binary)
+
+To build a universal binary that runs on both Apple Silicon and Intel Macs:
+
+```bash
+rustup target add aarch64-apple-darwin x86_64-apple-darwin
+```
+
+### 3. Install frontend dependencies
+
+```bash
+cd app
+npm ci
+```
+
+### 4. Build
+
+For a universal binary (recommended for distribution):
+
+```bash
+npx tauri build --target universal-apple-darwin
+```
+
+For the current architecture only (faster, for local development):
+
+```bash
+npx tauri build
+```
+
+Build artifacts are located in `app/src-tauri/target/universal-apple-darwin/release/bundle/` (or `target/release/bundle/` for single-arch builds):
+
+| Format | Path |
+|--------|------|
+| DMG | `dmg/*.dmg` |
+| macOS App | `macos/*.app` |
+| macOS App (compressed) | `macos/*.app.tar.gz` |
+
+> **Note:** The app is not signed or notarized. On first launch, macOS Gatekeeper may block it. Right-click the app and select "Open" to bypass, or remove the quarantine attribute: `xattr -cr /Applications/Triple-C.app`
+
 ## Windows
 
 ### 1. Install prerequisites

CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Triple-C (Claude-Code-Container) is a Tauri v2 desktop application that sandboxes Claude Code inside Docker containers. It has two main parts: a React/TypeScript frontend, a Rust backend, and a Docker container image definition.
+
+## Build & Development Commands
+
+All frontend/tauri commands run from the `app/` directory:
+
+```bash
+cd app
+npm ci                    # Install dependencies (required first time)
+npx tauri dev             # Launch app in dev mode with hot reload (Vite on port 1420)
+npx tauri build           # Production build (outputs to src-tauri/target/release/bundle/)
+npm run build             # Frontend-only build (tsc + vite)
+npm run test              # Run Vitest once
+npm run test:watch        # Run Vitest in watch mode
+```
+
+Rust backend is compiled automatically by `tauri dev`/`tauri build`. To check Rust independently:
+```bash
+cd app/src-tauri
+cargo check               # Type-check without full build
+cargo build               # Build Rust backend only
+```
+
+Container image:
+```bash
+docker build -t triple-c-sandbox ./container
+```
+
+### Linux Build Dependencies (Ubuntu/Debian)
+```bash
+sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libsoup-3.0-dev patchelf libssl-dev pkg-config build-essential
+```
+
+## Architecture
+
+### Two-Process Model (Tauri IPC)
+
+- **React frontend** (`app/src/`) renders UI in the OS webview
+- **Rust backend** (`app/src-tauri/src/`) handles Docker API, credential storage, and terminal I/O
+- Communication uses two patterns:
+  - `invoke()` — request/response for discrete operations (CRUD, start/stop containers)
+  - `emit()`/`listen()` — event streaming for continuous data (terminal I/O)
+
+### Terminal I/O Flow
+
+```
+User keystroke → xterm.js onData() → invoke("terminal_input") → mpsc channel → docker exec stdin
+docker exec stdout → tokio task → emit("terminal-output-{sessionId}") → listen() → xterm.js write()
+```
+
+### Frontend Structure (`app/src/`)
+
+- **`store/appState.ts`** — Single Zustand store for all app state (projects, sessions, UI)
+- **`hooks/`** — All Tauri IPC calls are encapsulated in hooks (`useTerminal`, `useProjects`, `useDocker`, `useSettings`)
+- **`lib/tauri-commands.ts`** — Typed `invoke()` wrappers; TypeScript types in `lib/types.ts` must match Rust models
+- **`components/terminal/TerminalView.tsx`** — xterm.js integration with WebGL rendering, URL detection for OAuth flow
+- **`components/layout/`** — TopBar (tabs + status), Sidebar (project list), StatusBar
+- **`components/projects/`** — ProjectCard, ProjectList, AddProjectDialog
+- **`components/settings/`** — Settings panels for API keys, Docker, AWS
+
+### Backend Structure (`app/src-tauri/src/`)
+
+- **`commands/`** — Tauri command handlers (docker, project, settings, terminal). These are the IPC entry points called by `invoke()`.
+- **`docker/`** — Docker API layer using bollard:
+  - `client.rs` — Singleton Docker connection via `OnceLock`
+  - `container.rs` — Container lifecycle (create, start, stop, remove, inspect)
+  - `exec.rs` — PTY exec sessions with bidirectional stdin/stdout streaming
+  - `image.rs` — Image build/pull with progress streaming
+- **`models/`** — Serde structs (`Project`, `AuthMode`, `BedrockConfig`, `ContainerInfo`, `AppSettings`). These define the IPC contract with the frontend.
+- **`storage/`** — Persistence: `projects_store.rs` (JSON file with atomic writes), `secure.rs` (OS keychain via `keyring` crate), `settings_store.rs`
+
+### Container (`container/`)
+
+- **`Dockerfile`** — Ubuntu 24.04 base with Claude Code, Node.js 22, Python 3.12, Rust, Docker CLI, git, gh, AWS CLI v2, ripgrep, pnpm, uv, ruff pre-installed
+- **`entrypoint.sh`** — UID/GID remapping to match host user, SSH key setup, git config, docker socket permissions, then `sleep infinity`
+- **`triple-c-scheduler`** — Bash-based scheduled task system for recurring Claude Code invocations
+
+### Container Lifecycle
+
+Containers use a **stop/start** model (not create/destroy). Installed packages persist across stops. The `.claude` config dir uses a named Docker volume (`triple-c-claude-config-{projectId}`) so OAuth tokens survive even container resets.
+
+### Authentication
+
+Per-project, independently configured:
+- **Anthropic (OAuth)** — `claude login` in terminal, token persists in config volume
+- **AWS Bedrock** — Static keys, profile, or bearer token injected as env vars
+
+## Styling
+
+- **Tailwind CSS v4** with the Vite plugin (`@tailwindcss/vite`). No separate tailwind config file.
+- All colors use CSS custom properties in `index.css` `:root` (e.g., `--bg-primary`, `--text-secondary`, `--accent`)
+- `color-scheme: dark` is set on `:root` for native dark-mode controls
+- **Do not** add a global `* { padding: 0 }` reset — Tailwind v4 uses CSS `@layer`, and unlayered CSS overrides all layered utilities
+
+## Key Conventions
+
+- Frontend types in `lib/types.ts` must stay in sync with Rust structs in `models/`
+- Tauri commands are registered in `lib.rs` via `.invoke_handler(tauri::generate_handler![...])`
+- Tauri v2 permissions are declared in `capabilities/default.json` — new IPC commands need permission grants there
+- The `projects.json` file uses atomic writes (write to `.tmp`, then `rename()`). Corrupted files are backed up to `.bak`.
+- Cross-platform paths: Docker socket is `/var/run/docker.sock` on Linux/macOS, `//./pipe/docker_engine` on Windows
+
+## Testing
+
+Frontend tests use Vitest with jsdom environment and React Testing Library. Setup file at `src/test/setup.ts`. Run a single test file:
+```bash
+cd app
+npx vitest run src/path/to/test.test.ts
+```

HOW-TO-USE.md

@@ -0,0 +1,397 @@
+# How to Use Triple-C
+
+Triple-C (Claude-Code-Container) is a desktop application that runs Claude Code inside isolated Docker containers. Each project gets its own sandboxed environment with bind-mounted directories, so Claude only has access to the files you explicitly provide.
+
+---
+
+## Prerequisites
+
+### Docker
+
+Triple-C requires a running Docker daemon. Install one of the following:
+
+| Platform | Option | Link |
+|----------|--------|------|
+| **Windows** | Docker Desktop | https://docs.docker.com/desktop/install/windows-install/ |
+| **macOS** | Docker Desktop | https://docs.docker.com/desktop/install/mac-install/ |
+| **Linux** | Docker Engine | https://docs.docker.com/engine/install/ |
+| **Linux** | Docker Desktop (alternative) | https://docs.docker.com/desktop/install/linux/ |
+
+After installation, verify Docker is running:
+
+```bash
+docker info
+```
+
+> **Windows note:** Docker Desktop must be running before launching Triple-C. The app communicates with Docker through the named pipe at `//./pipe/docker_engine`.
+
+> **Linux note:** Your user must have permission to access the Docker socket (`/var/run/docker.sock`). Either add your user to the `docker` group (`sudo usermod -aG docker $USER`, then log out and back in) or run Docker in rootless mode.
+
+### Claude Code Account
+
+You need access to Claude Code through one of:
+
+- **Anthropic account** — Sign up at https://claude.ai and use `claude login` (OAuth) inside the terminal
+- **AWS Bedrock** — An AWS account with Bedrock access and Claude models enabled
+
+---
+
+## First Launch
+
+### 1. Get the Container Image
+
+When you first open Triple-C, go to the **Settings** tab in the sidebar. Under **Docker**, you'll see:
+
+- **Docker Status** — Should show "Connected" (green). If it shows "Not Available", make sure Docker is running.
+- **Image Status** — Will show "Not Found" on first launch.
+
+Choose an **Image Source**:
+
+| Source | Description | When to Use |
+|--------|-------------|-------------|
+| **Registry** | Pulls the pre-built image from `repo.anhonesthost.net` | Fastest setup — recommended for most users |
+| **Local Build** | Builds the image locally from the embedded Dockerfile | If you can't reach the registry, or want a custom build |
+| **Custom** | Use any Docker image you specify | Advanced — bring your own sandbox image |
+
+Click **Pull Image** (for Registry/Custom) or **Build Image** (for Local Build). A progress log will stream below the button. When complete, the status changes to "Ready" (green).
+
+### 2. Create Your First Project
+
+Switch to the **Projects** tab in the sidebar and click the **+** button.
+
+1. **Project Name** — Give it a meaningful name (e.g., "my-web-app").
+2. **Folders** — Click **Browse** to select a directory on your host machine. This directory will be mounted into the container at `/workspace/<folder-name>`. You can add multiple folders with the **+** button at the bottom of the folder list.
+3. Click **Add Project**.
+
+### 3. Start the Container
+
+Select your project in the sidebar and click **Start**. The status dot changes from gray (stopped) to orange (starting) to green (running).
+
+### 4. Open a Terminal
+
+Click the **Terminal** button (highlighted in accent color) to open an interactive terminal session. A new tab appears in the top bar and an xterm.js terminal loads in the main area.
+
+Claude Code launches automatically with `--dangerously-skip-permissions` inside the sandboxed container.
+
+### 5. Authenticate
+
+**Anthropic (OAuth) — default:**
+
+1. Type `claude login` or `/login` in the terminal.
+2. Claude prints an OAuth URL. Triple-C detects long URLs and shows a clickable toast at the top of the terminal — click **Open** to open it in your browser.
+3. Complete the login in your browser. The token is saved and persists across container stops and resets.
+
+**AWS Bedrock:**
+
+1. Stop the container first (settings can only be changed while stopped).
+2. In the project card, switch the auth mode to **Bedrock**.
+3. Expand the **Config** panel and fill in your AWS credentials (see [AWS Bedrock Configuration](#aws-bedrock-configuration) below).
+4. Start the container again.
+
+---
+
+## The Interface
+
+```
+┌─────────────────────────────────────────────────────┐
+│  TopBar  [ Terminal Tabs ]           Docker ● Image ●│
+├────────────┬────────────────────────────────────────┤
+│  Sidebar   │                                        │
+│            │          Terminal View                  │
+│  Projects  │         (xterm.js)                     │
+│  Settings  │                                        │
+│            │                                        │
+├────────────┴────────────────────────────────────────┤
+│  StatusBar   X projects · X running · X terminals   │
+└─────────────────────────────────────────────────────┘
+```
+
+- **TopBar** — Terminal tabs for switching between sessions. Status dots on the right show Docker connection (green = connected) and image availability (green = ready).
+- **Sidebar** — Toggle between the **Projects** list and **Settings** panel.
+- **Terminal View** — Interactive terminal powered by xterm.js with WebGL rendering.
+- **StatusBar** — Counts of total projects, running containers, and open terminal sessions.
+
+---
+
+## Project Management
+
+### Project Status
+
+Each project shows a colored status dot:
+
+| Color | Status | Meaning |
+|-------|--------|---------|
+| Gray | Stopped | Container is not running |
+| Orange | Starting / Stopping | Container is transitioning |
+| Green | Running | Container is active, ready for terminals |
+| Red | Error | Something went wrong (check error message) |
+
+### Project Actions
+
+Select a project in the sidebar to see its action buttons:
+
+| Button | When Available | What It Does |
+|--------|---------------|--------------|
+| **Start** | Stopped | Creates (if needed) and starts the container |
+| **Stop** | Running | Stops the container but preserves its state |
+| **Terminal** | Running | Opens a new terminal session in this container |
+| **Reset** | Stopped | Destroys and recreates the container from scratch |
+| **Config** | Always | Toggles the configuration panel |
+| **Remove** | Stopped | Deletes the project and its container (with confirmation) |
+
+### Container Lifecycle
+
+Containers use a **stop/start** model. When you stop a container, everything inside it is preserved — installed packages, modified files, downloaded tools. Starting it again resumes where you left off.
+
+**Reset** removes the container and creates a fresh one. However, your Claude Code configuration (including OAuth tokens from `claude login`) is stored in a separate Docker volume and survives resets.
+
+Only **Remove** deletes everything, including the config volume and any stored credentials.
+
+---
+
+## Project Configuration
+
+Click **Config** on a selected project to expand the configuration panel. Settings can only be changed when the container is **stopped** (an orange warning box appears if the container is running).
+
+### Mounted Folders
+
+Each project mounts one or more host directories into the container. The mount appears at `/workspace/<mount-name>` inside the container.
+
+- Click **Browse** ("...") to change the host path
+- Edit the mount name to control where it appears inside `/workspace/`
+- Click **+** to add more folders, or **x** to remove one
+- Mount names must be unique and use only letters, numbers, dashes, underscores, and dots
+
+### SSH Keys
+
+Specify the path to your SSH key directory (typically `~/.ssh`). Keys are mounted read-only and copied into the container with correct permissions. This enables `git clone` via SSH inside the container.
+
+### Git Configuration
+
+- **Git Name / Email** — Sets `git config user.name` and `user.email` inside the container.
+- **Git HTTPS Token** — A personal access token (e.g., from GitHub) for HTTPS git operations. Stored securely in your OS keychain — never written to disk in plaintext.
+
+### Allow Container Spawning
+
+When enabled, the host Docker socket is mounted into the container so Claude Code can create sibling containers (e.g., for running databases, test environments). This is **off by default** for security.
+
+> Toggling this requires stopping and restarting the container to take effect.
+
+### Environment Variables
+
+Click **Edit** to open the environment variables modal. Add key-value pairs that will be injected into the container. Per-project variables override global variables with the same key.
+
+> Reserved prefixes (`ANTHROPIC_`, `AWS_`, `GIT_`, `HOST_`, `CLAUDE_`, `TRIPLE_C_`) are filtered out to prevent conflicts with internal variables.
+
+### Port Mappings
+
+Click **Edit** to map host ports to container ports. This is useful when Claude Code starts a web server or other service inside the container and you want to access it from your host browser.
+
+Each mapping specifies:
+- **Host Port** — The port on your machine (1–65535)
+- **Container Port** — The port inside the container (1–65535)
+- **Protocol** — TCP (default) or UDP
+
+### Claude Instructions
+
+Click **Edit** to write per-project instructions for Claude Code. These are written to `~/.claude/CLAUDE.md` inside the container and provide project-specific context. If you also have global instructions (in Settings), the global instructions come first, followed by the per-project instructions.
+
+---
+
+## AWS Bedrock Configuration
+
+To use Claude via AWS Bedrock instead of Anthropic's API, switch the auth mode to **Bedrock** on the project card.
+
+### Authentication Methods
+
+| Method | Fields | Use Case |
+|--------|--------|----------|
+| **Keys** | Access Key ID, Secret Access Key, Session Token (optional) | Direct credentials — simplest setup |
+| **Profile** | AWS Profile name | Uses `~/.aws/config` and `~/.aws/credentials` on the host |
+| **Token** | Bearer Token | Temporary bearer token authentication |
+
+### Additional Bedrock Settings
+
+- **AWS Region** — Required. The region where your Bedrock models are deployed (e.g., `us-east-1`).
+- **Model ID** — Optional. Override the default Claude model (e.g., `anthropic.claude-sonnet-4-20250514-v1:0`).
+
+### Global AWS Defaults
+
+In **Settings > AWS Configuration**, you can set defaults that apply to all Bedrock projects:
+
+- **AWS Config Path** — Path to your `~/.aws` directory. Click **Detect** to auto-find it.
+- **Default Profile** — Select from profiles found in your AWS config.
+- **Default Region** — Fallback region for projects that don't specify one.
+
+Per-project settings always override these global defaults.
+
+---
+
+## Settings
+
+Access global settings via the **Settings** tab in the sidebar.
+
+### Docker Settings
+
+- **Docker Status** — Connection status to the Docker daemon.
+- **Image Source** — Where to get the sandbox container image (Registry, Local Build, or Custom).
+- **Pull / Build Image** — Download or build the image. Progress streams in real time.
+- **Refresh** — Re-check Docker and image status.
+
+### Container Timezone
+
+Set the timezone for all containers (IANA format, e.g., `America/New_York`, `Europe/London`, `UTC`). Auto-detected from your host on first launch. This affects scheduled task timing inside containers.
+
+### Global Claude Instructions
+
+Instructions applied to **all** projects. Written to `~/.claude/CLAUDE.md` in every container, before any per-project instructions.
+
+### Global Environment Variables
+
+Environment variables applied to **all** project containers. Per-project variables with the same key take precedence.
+
+### Updates
+
+- **Current Version** — The installed version of Triple-C.
+- **Auto-check** — Toggle automatic update checks (every 24 hours).
+- **Check now** — Manually check for updates.
+
+When an update is available, a pulsing **Update** button appears in the top bar. Click it to see release notes and download links.
+
+---
+
+## Terminal Features
+
+### Multiple Sessions
+
+You can open multiple terminal sessions (even for the same project). Each session gets its own tab in the top bar. Click a tab to switch, or click the **x** on a tab to close it.
+
+### URL Detection
+
+When Claude Code prints a long URL (e.g., during `claude login`), Triple-C detects it and shows a toast notification at the top of the terminal with an **Open** button. Clicking it opens the URL in your default browser. The toast auto-dismisses after 30 seconds.
+
+Shorter URLs in terminal output are also clickable directly.
+
+### Image Paste
+
+You can paste images from your clipboard into the terminal (Ctrl+V / Cmd+V). The image is uploaded to the container and the file path is injected into the terminal input so Claude Code can reference it.
+
+### Terminal Rendering
+
+The terminal uses WebGL for hardware-accelerated rendering of the active tab. Inactive tabs fall back to canvas rendering to conserve GPU resources. The terminal automatically resizes when you resize the window.
+
+---
+
+## Scheduled Tasks (Inside the Container)
+
+Once inside a running container terminal, you can set up recurring or one-time tasks using `triple-c-scheduler`. Tasks run as separate Claude Code sessions.
+
+### Create a Recurring Task
+
+```bash
+triple-c-scheduler add --name "daily-review" --schedule "0 9 * * *" --prompt "Review open issues and summarize"
+```
+
+### Create a One-Time Task
+
+```bash
+triple-c-scheduler add --name "migrate-db" --at "2026-03-05 14:00" --prompt "Run database migrations"
+```
+
+One-time tasks automatically remove themselves after execution.
+
+### Manage Tasks
+
+```bash
+triple-c-scheduler list                    # List all tasks
+triple-c-scheduler enable --id abc123      # Enable a task
+triple-c-scheduler disable --id abc123     # Disable a task
+triple-c-scheduler remove --id abc123      # Delete a task
+triple-c-scheduler run --id abc123         # Trigger a task immediately
+triple-c-scheduler logs --id abc123        # View logs for a task
+triple-c-scheduler logs --tail 20          # View last 20 log entries (all tasks)
+triple-c-scheduler notifications           # View completion notifications
+triple-c-scheduler notifications --clear   # Clear notifications
+```
+
+### Cron Schedule Format
+
+Standard 5-field cron: `minute hour day-of-month month day-of-week`
+
+| Example | Meaning |
+|---------|---------|
+| `*/30 * * * *` | Every 30 minutes |
+| `0 9 * * 1-5` | 9:00 AM on weekdays |
+| `0 */2 * * *` | Every 2 hours |
+| `0 0 1 * *` | Midnight on the 1st of each month |
+
+### Working Directory
+
+By default, tasks run in `/workspace`. Use `--working-dir` to specify a different directory:
+
+```bash
+triple-c-scheduler add --name "test" --schedule "0 */6 * * *" --prompt "Run tests" --working-dir /workspace/my-project
+```
+
+---
+
+## What's Inside the Container
+
+The sandbox container (Ubuntu 24.04) comes pre-installed with:
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Claude Code | Latest | AI coding assistant (the tool being sandboxed) |
+| Node.js | 22 LTS | JavaScript/TypeScript development |
+| pnpm | Latest | Fast Node.js package manager |
+| Python | 3.12 | Python development |
+| uv | Latest | Fast Python package manager |
+| ruff | Latest | Python linter/formatter |
+| Rust | Stable | Rust development (via rustup) |
+| Docker CLI | Latest | Container management (when spawning is enabled) |
+| git | Latest | Version control |
+| GitHub CLI (gh) | Latest | GitHub integration |
+| AWS CLI | v2 | AWS services and Bedrock |
+| ripgrep | Latest | Fast code search |
+| build-essential | — | C/C++ compiler toolchain |
+| openssh-client | — | SSH for git and remote access |
+
+You can install additional tools at runtime with `sudo apt install`, `pip install`, `npm install -g`, etc. Installed packages persist across container stops (but not across resets).
+
+---
+
+## Troubleshooting
+
+### Docker is "Not Available"
+
+- **Is Docker running?** Start Docker Desktop or the Docker daemon (`sudo systemctl start docker`).
+- **Permissions?** On Linux, ensure your user is in the `docker` group or the socket is accessible.
+- **Custom socket path?** If your Docker socket is not at the default location, set it in Settings. The app expects `/var/run/docker.sock` on Linux/macOS or `//./pipe/docker_engine` on Windows.
+
+### Image is "Not Found"
+
+- Click **Pull Image** or **Build Image** in Settings > Docker.
+- If pulling fails, check your network connection and whether you can reach the registry.
+- Try switching to **Local Build** as an alternative.
+
+### Container Won't Start
+
+- Check that the Docker image is "Ready" in Settings.
+- Verify that the mounted folder paths exist on your host.
+- Look at the error message displayed in red below the project card.
+
+### OAuth Login URL Not Opening
+
+- Triple-C detects long URLs printed by `claude login` and shows a toast with an **Open** button.
+- If the toast doesn't appear, try scrolling up in the terminal — the URL may have already been printed.
+- You can also manually copy the URL from the terminal output and paste it into your browser.
+
+### File Permission Issues
+
+- Triple-C automatically remaps the container user's UID/GID to match your host user, so files created inside the container should have the correct ownership on your host.
+- If you see permission errors, try resetting the container (stop, then click **Reset**).
+
+### Settings Won't Save
+
+- Most project settings can only be changed when the container is **stopped**. Stop the container first, make your changes, then start it again.
+- Some changes (like toggling Docker access or changing mounted folders) trigger an automatic container recreation on the next start.

TODO.md

@@ -0,0 +1,60 @@
+# TODO / Future Improvements
+
+## In-App Auto-Update via `tauri-plugin-updater`
+
+**Priority:** High
+**Status:** Planned
+
+Currently the app detects available updates via the Gitea API (`check_for_updates` command) but cannot apply them. Users must manually download and install the new version. On macOS and Linux this is a poor experience compared to Windows (where NSIS handles upgrades cleanly).
+
+### Recommended approach: `tauri-plugin-updater`
+
+Full in-app auto-update: detects, downloads, verifies, and applies updates seamlessly on all platforms. The user clicks "Update" and the app restarts with the new version.
+
+### Requirements
+
+1. **Generate a Tauri update signing key pair** (this is Tauri's own Ed25519 key, not OS code signing):
+   ```bash
+   npx @tauri-apps/cli signer generate -w ~/.tauri/triple-c.key
+   ```
+   Set `TAURI_SIGNING_PRIVATE_KEY` and `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` in CI.
+
+2. **Add `tauri-plugin-updater`** to Rust and JS dependencies.
+
+3. **Create an update endpoint** that returns Tauri's expected JSON format:
+   ```json
+   {
+     "version": "v0.1.100",
+     "notes": "Changelog here",
+     "pub_date": "2026-03-01T00:00:00Z",
+     "platforms": {
+       "darwin-x86_64": { "signature": "...", "url": "https://..." },
+       "darwin-aarch64": { "signature": "...", "url": "https://..." },
+       "linux-x86_64": { "signature": "...", "url": "https://..." },
+       "windows-x86_64": { "signature": "...", "url": "https://..." }
+     }
+   }
+   ```
+   This could be a static JSON file uploaded alongside release assets, or a small API that reads from Gitea releases and reformats.
+
+4. **Configure the updater** in `tauri.conf.json`:
+   ```json
+   "plugins": {
+     "updater": {
+       "endpoints": ["https://repo.anhonesthost.net/...update-endpoint..."],
+       "pubkey": "<public key from step 1>"
+     }
+   }
+   ```
+
+5. **Add frontend UI** for the update prompt (replace or enhance the existing update check flow).
+
+6. **Update CI pipeline** to:
+   - Sign bundles with the Tauri key during build
+   - Upload `.sig` files alongside installers
+   - Generate/upload the update endpoint JSON
+
+### References
+- https://v2.tauri.app/plugin/updater/
+- Existing update check code: `app/src-tauri/src/commands/update_commands.rs`
+- Existing models: `app/src-tauri/src/models/update_info.rs`

app/src-tauri/src/commands/project_commands.rs

@@ -1,10 +1,20 @@
-use tauri::State;
+use tauri::{Emitter, State};
 
 use crate::docker;
 use crate::models::{container_config, AuthMode, Project, ProjectPath, ProjectStatus};
 use crate::storage::secure;
 use crate::AppState;
 
+fn emit_progress(app_handle: &tauri::AppHandle, project_id: &str, message: &str) {
+    let _ = app_handle.emit(
+        "container-progress",
+        serde_json::json!({
+            "project_id": project_id,
+            "message": message,
+        }),
+    );
+}
+
 /// Extract secret fields from a project and store them in the OS keychain.
 fn store_secrets_for_project(project: &Project) -> Result<(), String> {
     if let Some(ref token) = project.git_token {
@@ -81,12 +91,19 @@ pub async fn remove_project(
     state: State<'_, AppState>,
 ) -> Result<(), String> {
     // Stop and remove container if it exists
-    if let Some(project) = state.projects_store.get(&project_id) {
+    if let Some(ref project) = state.projects_store.get(&project_id) {
         if let Some(ref container_id) = project.container_id {
             state.exec_manager.close_sessions_for_container(container_id).await;
             let _ = docker::stop_container(container_id).await;
             let _ = docker::remove_container(container_id).await;
         }
+        // Clean up the snapshot image + volumes
+        if let Err(e) = docker::remove_snapshot_image(project).await {
+            log::warn!("Failed to remove snapshot image for project {}: {}", project_id, e);
+        }
+        if let Err(e) = docker::remove_project_volumes(project).await {
+            log::warn!("Failed to remove project volumes for project {}: {}", project_id, e);
+        }
     }
 
     // Clean up keychain secrets for this project
@@ -109,6 +126,7 @@ pub async fn update_project(
 #[tauri::command]
 pub async fn start_project_container(
     project_id: String,
+    app_handle: tauri::AppHandle,
     state: State<'_, AppState>,
 ) -> Result<Project, String> {
     let mut project = state
@@ -140,6 +158,7 @@ pub async fn start_project_container(
     // Wrap container operations so that any failure resets status to Stopped.
     let result: Result<String, String> = async {
         // Ensure image exists
+        emit_progress(&app_handle, &project_id, "Checking image...");
         if !docker::image_exists(&image_name).await? {
             return Err(format!("Docker image '{}' not found. Please pull or build the image first.", image_name));
         }
@@ -153,48 +172,77 @@ pub async fn start_project_container(
         // AWS config path from global settings
         let aws_config_path = settings.global_aws.aws_config_path.clone();
 
-        // Check for existing container
         let container_id = if let Some(existing_id) = docker::find_existing_container(&project).await? {
-            let needs_recreation = docker::container_needs_recreation(
+            // Check if config changed — if so, snapshot + recreate
+            let needs_recreate = docker::container_needs_recreation(
                 &existing_id,
                 &project,
                 settings.global_claude_instructions.as_deref(),
                 &settings.global_custom_env_vars,
                 settings.timezone.as_deref(),
-                )
+            ).await.unwrap_or(false);
-                .await
+
-                .unwrap_or(false);
+            if needs_recreate {
-            if needs_recreation {
+                log::info!("Container config changed for project {} — committing snapshot and recreating", project.id);
-                log::info!("Container config changed, recreating container for project {}", project.id);
+                // Snapshot the filesystem before destroying
+                emit_progress(&app_handle, &project_id, "Saving container state...");
+                if let Err(e) = docker::commit_container_snapshot(&existing_id, &project).await {
+                    log::warn!("Failed to snapshot container before recreation: {}", e);
+                }
+                emit_progress(&app_handle, &project_id, "Recreating container...");
                 let _ = docker::stop_container(&existing_id).await;
                 docker::remove_container(&existing_id).await?;
+
+                // Create from snapshot image (preserves system-level changes)
+                let snapshot_image = docker::get_snapshot_image_name(&project);
+                let create_image = if docker::image_exists(&snapshot_image).await.unwrap_or(false) {
+                    snapshot_image
+                } else {
+                    image_name.clone()
+                };
+
                 let new_id = docker::create_container(
                     &project,
                     &docker_socket,
-                    &image_name,
+                    &create_image,
                     aws_config_path.as_deref(),
                     &settings.global_aws,
                     settings.global_claude_instructions.as_deref(),
                     &settings.global_custom_env_vars,
                     settings.timezone.as_deref(),
                 ).await?;
+                emit_progress(&app_handle, &project_id, "Starting container...");
                 docker::start_container(&new_id).await?;
                 new_id
             } else {
+                emit_progress(&app_handle, &project_id, "Starting container...");
                 docker::start_container(&existing_id).await?;
                 existing_id
             }
         } else {
+            // Container doesn't exist (first start, or Docker pruned it).
+            // Check for a snapshot image first — it preserves system-level
+            // changes (apt/pip/npm installs) from the previous session.
+            let snapshot_image = docker::get_snapshot_image_name(&project);
+            let create_image = if docker::image_exists(&snapshot_image).await.unwrap_or(false) {
+                log::info!("Creating container from snapshot image for project {}", project.id);
+                snapshot_image
+            } else {
+                image_name.clone()
+            };
+
+            emit_progress(&app_handle, &project_id, "Creating container...");
             let new_id = docker::create_container(
                 &project,
                 &docker_socket,
-                &image_name,
+                &create_image,
                 aws_config_path.as_deref(),
                 &settings.global_aws,
                 settings.global_claude_instructions.as_deref(),
                 &settings.global_custom_env_vars,
                 settings.timezone.as_deref(),
             ).await?;
+            emit_progress(&app_handle, &project_id, "Starting container...");
             docker::start_container(&new_id).await?;
             new_id
         };
@@ -222,6 +270,7 @@ pub async fn start_project_container(
 #[tauri::command]
 pub async fn stop_project_container(
     project_id: String,
+    app_handle: tauri::AppHandle,
     state: State<'_, AppState>,
 ) -> Result<(), String> {
     let project = state
@@ -229,22 +278,26 @@ pub async fn stop_project_container(
         .get(&project_id)
         .ok_or_else(|| format!("Project {} not found", project_id))?;
 
-    if let Some(ref container_id) = project.container_id {
     state.projects_store.update_status(&project_id, ProjectStatus::Stopping)?;
 
+    if let Some(ref container_id) = project.container_id {
         // Close exec sessions for this project
+        emit_progress(&app_handle, &project_id, "Stopping container...");
         state.exec_manager.close_sessions_for_container(container_id).await;
 
-        docker::stop_container(container_id).await?;
+        if let Err(e) = docker::stop_container(container_id).await {
-        state.projects_store.update_status(&project_id, ProjectStatus::Stopped)?;
+            log::warn!("Docker stop failed for container {} (project {}): {} — resetting to Stopped anyway", container_id, project_id, e);
+        }
     }
 
+    state.projects_store.update_status(&project_id, ProjectStatus::Stopped)?;
     Ok(())
 }
 
 #[tauri::command]
 pub async fn rebuild_project_container(
     project_id: String,
+    app_handle: tauri::AppHandle,
     state: State<'_, AppState>,
 ) -> Result<Project, String> {
     let project = state
@@ -260,8 +313,16 @@ pub async fn rebuild_project_container(
         state.projects_store.set_container_id(&project_id, None)?;
     }
 
+    // Remove snapshot image + volumes so Reset creates from the clean base image
+    if let Err(e) = docker::remove_snapshot_image(&project).await {
+        log::warn!("Failed to remove snapshot image for project {}: {}", project_id, e);
+    }
+    if let Err(e) = docker::remove_project_volumes(&project).await {
+        log::warn!("Failed to remove project volumes for project {}: {}", project_id, e);
+    }
+
     // Start fresh
-    start_project_container(project_id, state).await
+    start_project_container(project_id, app_handle, state).await
 }
 
 fn default_docker_socket() -> String {

app/src-tauri/src/commands/terminal_commands.rs

@@ -72,3 +72,23 @@ pub async fn close_terminal_session(
     state.exec_manager.close_session(&session_id).await;
     Ok(())
 }
+
+#[tauri::command]
+pub async fn paste_image_to_terminal(
+    session_id: String,
+    image_data: Vec<u8>,
+    state: State<'_, AppState>,
+) -> Result<String, String> {
+    let container_id = state.exec_manager.get_container_id(&session_id).await?;
+
+    let timestamp = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis();
+    let file_name = format!("clipboard_{}.png", timestamp);
+
+    state
+        .exec_manager
+        .write_file_to_container(&container_id, &file_name, &image_data)
+        .await
+}

app/src-tauri/src/docker/client.rs

@@ -1,23 +1,28 @@
 use bollard::Docker;
-use std::sync::OnceLock;
+use std::sync::Mutex;
 
-static DOCKER: OnceLock<Result<Docker, String>> = OnceLock::new();
+static DOCKER: Mutex<Option<Docker>> = Mutex::new(None);
 
-pub fn get_docker() -> Result<&'static Docker, String> {
+pub fn get_docker() -> Result<Docker, String> {
-    let result = DOCKER.get_or_init(|| {
+    let mut guard = DOCKER.lock().map_err(|e| format!("Lock poisoned: {}", e))?;
-        Docker::connect_with_local_defaults()
+    if let Some(docker) = guard.as_ref() {
-            .map_err(|e| format!("Failed to connect to Docker daemon: {}", e))
+        return Ok(docker.clone());
-    });
-    match result {
-        Ok(docker) => Ok(docker),
-        Err(e) => Err(e.clone()),
     }
+    let docker = Docker::connect_with_local_defaults()
+        .map_err(|e| format!("Failed to connect to Docker daemon: {}", e))?;
+    guard.replace(docker.clone());
+    Ok(docker)
 }
 
 pub async fn check_docker_available() -> Result<bool, String> {
     let docker = get_docker()?;
     match docker.ping().await {
         Ok(_) => Ok(true),
-        Err(e) => Err(format!("Docker daemon not responding: {}", e)),
+        Err(_) => {
+            // Connection object exists but daemon not responding — clear cache
+            let mut guard = DOCKER.lock().map_err(|e| format!("Lock poisoned: {}", e))?;
+            *guard = None;
+            Ok(false)
+        }
     }
 }

app/src-tauri/src/docker/container.rs

@@ -2,6 +2,7 @@ use bollard::container::{
     Config, CreateContainerOptions, ListContainersOptions, RemoveContainerOptions,
     StartContainerOptions, StopContainerOptions,
 };
+use bollard::image::{CommitContainerOptions, RemoveImageOptions};
 use bollard::models::{ContainerSummary, HostConfig, Mount, MountTypeEnum, PortBinding};
 use std::collections::HashMap;
 use std::collections::hash_map::DefaultHasher;
@@ -40,6 +41,42 @@ After tasks run, check notifications with `triple-c-scheduler notifications` and
 ### Timezone
 Scheduled times use the container's configured timezone (check with `date`). If no timezone is configured, UTC is used."#;
 
+/// Build the full CLAUDE_INSTRUCTIONS value by merging global + project
+/// instructions, appending port mapping docs, and appending scheduler docs.
+/// Used by both create_container() and container_needs_recreation() to ensure
+/// the same value is produced in both paths.
+fn build_claude_instructions(
+    global_instructions: Option<&str>,
+    project_instructions: Option<&str>,
+    port_mappings: &[PortMapping],
+) -> Option<String> {
+    let mut combined = merge_claude_instructions(global_instructions, project_instructions);
+
+    if !port_mappings.is_empty() {
+        let mut port_lines: Vec<String> = Vec::new();
+        port_lines.push("## Available Port Mappings".to_string());
+        port_lines.push("The following ports are mapped from the host to this container. Use these container ports when starting services that need to be accessible from the host:".to_string());
+        for pm in port_mappings {
+            port_lines.push(format!(
+                "- Host port {} -> Container port {} ({})",
+                pm.host_port, pm.container_port, pm.protocol
+            ));
+        }
+        let port_info = port_lines.join("\n");
+        combined = Some(match combined {
+            Some(existing) => format!("{}\n\n{}", existing, port_info),
+            None => port_info,
+        });
+    }
+
+    combined = Some(match combined {
+        Some(existing) => format!("{}\n\n{}", existing, SCHEDULER_INSTRUCTIONS),
+        None => SCHEDULER_INSTRUCTIONS.to_string(),
+    });
+
+    combined
+}
+
 /// Compute a fingerprint string for the custom environment variables.
 /// Sorted alphabetically so order changes do not cause spurious recreation.
 fn compute_env_fingerprint(custom_env_vars: &[EnvVar]) -> String {
@@ -307,33 +344,12 @@ pub async fn create_container(
         }
     }
 
-    // Claude instructions (global + per-project, plus port mapping info)
+    // Claude instructions (global + per-project, plus port mapping info + scheduler docs)
-    let mut combined_instructions = merge_claude_instructions(
+    let combined_instructions = build_claude_instructions(
         global_claude_instructions,
         project.claude_instructions.as_deref(),
+        &project.port_mappings,
     );
-    if !project.port_mappings.is_empty() {
-        let mut port_lines: Vec<String> = Vec::new();
-        port_lines.push("## Available Port Mappings".to_string());
-        port_lines.push("The following ports are mapped from the host to this container. Use these container ports when starting services that need to be accessible from the host:".to_string());
-        for pm in &project.port_mappings {
-            port_lines.push(format!(
-                "- Host port {} -> Container port {} ({})",
-                pm.host_port, pm.container_port, pm.protocol
-            ));
-        }
-        let port_info = port_lines.join("\n");
-        combined_instructions = Some(match combined_instructions {
-            Some(existing) => format!("{}\n\n{}", existing, port_info),
-            None => port_info,
-        });
-    }
-    // Scheduler instructions (always appended so all containers get scheduling docs)
-    let scheduler_docs = SCHEDULER_INSTRUCTIONS;
-    combined_instructions = Some(match combined_instructions {
-        Some(existing) => format!("{}\n\n{}", existing, scheduler_docs),
-        None => scheduler_docs.to_string(),
-    });
 
     if let Some(ref instructions) = combined_instructions {
         env_vars.push(format!("CLAUDE_INSTRUCTIONS={}", instructions));
@@ -352,7 +368,19 @@ pub async fn create_container(
         });
     }
 
-    // Named volume for claude config persistence
+    // Named volume for the entire home directory — preserves ~/.claude.json,
+    // ~/.local (pip/npm globals), and any other user-level state across
+    // container stop/start cycles.
+    mounts.push(Mount {
+        target: Some("/home/claude".to_string()),
+        source: Some(format!("triple-c-home-{}", project.id)),
+        typ: Some(MountTypeEnum::VOLUME),
+        read_only: Some(false),
+        ..Default::default()
+    });
+
+    // Named volume for claude config persistence — mounted as a nested volume
+    // inside the home volume; Docker gives the more-specific mount precedence.
     mounts.push(Mount {
         target: Some("/home/claude/.claude".to_string()),
         source: Some(format!("triple-c-claude-config-{}", project.id)),
@@ -523,6 +551,83 @@ pub async fn remove_container(container_id: &str) -> Result<(), String> {
         .map_err(|e| format!("Failed to remove container: {}", e))
 }
 
+/// Return the snapshot image name for a project.
+pub fn get_snapshot_image_name(project: &Project) -> String {
+    format!("triple-c-snapshot-{}:latest", project.id)
+}
+
+/// Commit the container's filesystem to a snapshot image so that system-level
+/// changes (apt/pip/npm installs, ~/.claude.json, etc.) survive container
+/// removal. The Config is left empty so that secrets injected as env vars are
+/// NOT baked into the image.
+pub async fn commit_container_snapshot(container_id: &str, project: &Project) -> Result<(), String> {
+    let docker = get_docker()?;
+    let image_name = get_snapshot_image_name(project);
+
+    // Parse repo:tag
+    let (repo, tag) = match image_name.rsplit_once(':') {
+        Some((r, t)) => (r.to_string(), t.to_string()),
+        None => (image_name.clone(), "latest".to_string()),
+    };
+
+    let options = CommitContainerOptions {
+        container: container_id.to_string(),
+        repo: repo.clone(),
+        tag: tag.clone(),
+        pause: true,
+        ..Default::default()
+    };
+
+    // Empty config — no env vars / cmd baked in
+    let config = Config::<String> {
+        ..Default::default()
+    };
+
+    docker
+        .commit_container(options, config)
+        .await
+        .map_err(|e| format!("Failed to commit container snapshot: {}", e))?;
+
+    log::info!("Committed container {} as snapshot {}:{}", container_id, repo, tag);
+    Ok(())
+}
+
+/// Remove the snapshot image for a project (used on Reset / project removal).
+pub async fn remove_snapshot_image(project: &Project) -> Result<(), String> {
+    let docker = get_docker()?;
+    let image_name = get_snapshot_image_name(project);
+
+    docker
+        .remove_image(
+            &image_name,
+            Some(RemoveImageOptions {
+                force: true,
+                noprune: false,
+            }),
+            None,
+        )
+        .await
+        .map_err(|e| format!("Failed to remove snapshot image {}: {}", image_name, e))?;
+
+    log::info!("Removed snapshot image {}", image_name);
+    Ok(())
+}
+
+/// Remove both named volumes for a project (used on Reset / project removal).
+pub async fn remove_project_volumes(project: &Project) -> Result<(), String> {
+    let docker = get_docker()?;
+    for vol in [
+        format!("triple-c-home-{}", project.id),
+        format!("triple-c-claude-config-{}", project.id),
+    ] {
+        match docker.remove_volume(&vol, None).await {
+            Ok(_) => log::info!("Removed volume {}", vol),
+            Err(e) => log::warn!("Failed to remove volume {} (may not exist): {}", vol, e),
+        }
+    }
+    Ok(())
+}
+
 /// Check whether the existing container's configuration still matches the
 /// current project settings.  Returns `true` when the container must be
 /// recreated (mounts or env vars differ).
@@ -685,9 +790,10 @@ pub async fn container_needs_recreation(
     }
 
     // ── Claude instructions ───────────────────────────────────────────────
-    let expected_instructions = merge_claude_instructions(
+    let expected_instructions = build_claude_instructions(
         global_claude_instructions,
         project.claude_instructions.as_deref(),
+        &project.port_mappings,
     );
     let container_instructions = get_env("CLAUDE_INSTRUCTIONS");
     if container_instructions.as_deref() != expected_instructions.as_deref() {

app/src-tauri/src/docker/exec.rs

@@ -1,3 +1,4 @@
+use bollard::container::UploadToContainerOptions;
 use bollard::exec::{CreateExecOptions, ResizeExecOptions, StartExecResults};
 use futures_util::StreamExt;
 use std::collections::HashMap;
@@ -212,4 +213,51 @@ impl ExecSessionManager {
             session.shutdown();
         }
     }
+
+    pub async fn get_container_id(&self, session_id: &str) -> Result<String, String> {
+        let sessions = self.sessions.lock().await;
+        let session = sessions
+            .get(session_id)
+            .ok_or_else(|| format!("Session {} not found", session_id))?;
+        Ok(session.container_id.clone())
+    }
+
+    pub async fn write_file_to_container(
+        &self,
+        container_id: &str,
+        file_name: &str,
+        data: &[u8],
+    ) -> Result<String, String> {
+        let docker = get_docker()?;
+
+        // Build a tar archive in memory containing the file
+        let mut tar_buf = Vec::new();
+        {
+            let mut builder = tar::Builder::new(&mut tar_buf);
+            let mut header = tar::Header::new_gnu();
+            header.set_size(data.len() as u64);
+            header.set_mode(0o644);
+            header.set_cksum();
+            builder
+                .append_data(&mut header, file_name, data)
+                .map_err(|e| format!("Failed to create tar entry: {}", e))?;
+            builder
+                .finish()
+                .map_err(|e| format!("Failed to finalize tar: {}", e))?;
+        }
+
+        docker
+            .upload_to_container(
+                container_id,
+                Some(UploadToContainerOptions {
+                    path: "/tmp".to_string(),
+                    ..Default::default()
+                }),
+                tar_buf.into(),
+            )
+            .await
+            .map_err(|e| format!("Failed to upload file to container: {}", e))?;
+
+        Ok(format!("/tmp/{}", file_name))
+    }
 }

app/src-tauri/src/lib.rs

@@ -90,6 +90,7 @@ pub fn run() {
             commands::terminal_commands::terminal_input,
             commands::terminal_commands::terminal_resize,
             commands::terminal_commands::close_terminal_session,
+            commands::terminal_commands::paste_image_to_terminal,
             // Updates
             commands::update_commands::get_app_version,
             commands::update_commands::check_for_updates,

app/src-tauri/src/storage/projects_store.rs

@@ -70,17 +70,38 @@ impl ProjectsStore {
             (Vec::new(), false)
         };
 
+        // Reconcile stale transient statuses: on a cold app start no Docker
+        // operations can be in flight, so Starting/Stopping are always stale.
+        let mut projects = projects;
+        let mut needs_save = needs_save;
+        for p in projects.iter_mut() {
+            match p.status {
+                crate::models::ProjectStatus::Starting | crate::models::ProjectStatus::Stopping => {
+                    log::warn!(
+                        "Reconciling stale '{}' status for project '{}' ({}) → Stopped",
+                        serde_json::to_string(&p.status).unwrap_or_default().trim_matches('"'),
+                        p.name,
+                        p.id
+                    );
+                    p.status = crate::models::ProjectStatus::Stopped;
+                    p.updated_at = chrono::Utc::now().to_rfc3339();
+                    needs_save = true;
+                }
+                _ => {}
+            }
+        }
+
         let store = Self {
             projects: Mutex::new(projects),
             file_path,
         };
 
-        // Persist migrated format back to disk
+        // Persist migrated/reconciled format back to disk
         if needs_save {
-            log::info!("Migrated projects.json from single-path to multi-path format");
+            log::info!("Saving reconciled/migrated projects.json to disk");
             let projects = store.lock();
             if let Err(e) = store.save(&projects) {
-                log::error!("Failed to save migrated projects: {}", e);
+                log::error!("Failed to save projects: {}", e);
             }
         }
 

app/src/App.tsx

@@ -11,7 +11,7 @@ import { useUpdates } from "./hooks/useUpdates";
 import { useAppState } from "./store/appState";
 
 export default function App() {
-  const { checkDocker, checkImage } = useDocker();
+  const { checkDocker, checkImage, startDockerPolling } = useDocker();
   const { loadSettings } = useSettings();
   const { refresh } = useProjects();
   const { loadVersion, checkForUpdates, startPeriodicCheck } = useUpdates();
@@ -22,8 +22,13 @@ export default function App() {
   // Initialize on mount
   useEffect(() => {
     loadSettings();
+    let stopPolling: (() => void) | undefined;
     checkDocker().then((available) => {
-      if (available) checkImage();
+      if (available) {
+        checkImage();
+      } else {
+        stopPolling = startDockerPolling();
+      }
     });
     refresh();
 
@@ -34,6 +39,7 @@ export default function App() {
     return () => {
       clearTimeout(updateTimer);
       cleanup?.();
+      stopPolling?.();
     };
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 

app/src/components/projects/ContainerProgressModal.tsx

@@ -0,0 +1,109 @@
+import { useEffect, useRef, useCallback } from "react";
+
+interface Props {
+  projectName: string;
+  operation: "starting" | "stopping" | "resetting";
+  progressMsg: string | null;
+  error: string | null;
+  completed: boolean;
+  onForceStop: () => void;
+  onClose: () => void;
+}
+
+const operationLabels: Record<string, string> = {
+  starting: "Starting",
+  stopping: "Stopping",
+  resetting: "Resetting",
+};
+
+export default function ContainerProgressModal({
+  projectName,
+  operation,
+  progressMsg,
+  error,
+  completed,
+  onForceStop,
+  onClose,
+}: Props) {
+  const overlayRef = useRef<HTMLDivElement>(null);
+
+  // Auto-close on success after 800ms
+  useEffect(() => {
+    if (completed && !error) {
+      const timer = setTimeout(onClose, 800);
+      return () => clearTimeout(timer);
+    }
+  }, [completed, error, onClose]);
+
+  // Escape to close (only when completed or error)
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape" && (completed || error)) onClose();
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [completed, error, onClose]);
+
+  const handleOverlayClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (e.target === overlayRef.current && (completed || error)) onClose();
+    },
+    [completed, error, onClose],
+  );
+
+  const inProgress = !completed && !error;
+
+  return (
+    <div
+      ref={overlayRef}
+      onClick={handleOverlayClick}
+      className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
+    >
+      <div className="bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-lg p-6 w-80 shadow-xl text-center">
+        <h3 className="text-sm font-semibold mb-4">
+          {operationLabels[operation]} &ldquo;{projectName}&rdquo;
+        </h3>
+
+        {/* Spinner / checkmark / error icon */}
+        <div className="flex justify-center mb-3">
+          {error ? (
+            <span className="text-3xl text-[var(--error)]">✕</span>
+          ) : completed ? (
+            <span className="text-3xl text-[var(--success)]">✓</span>
+          ) : (
+            <div className="w-8 h-8 border-2 border-[var(--accent)] border-t-transparent rounded-full animate-spin" />
+          )}
+        </div>
+
+        {/* Progress message */}
+        <p className="text-xs text-[var(--text-secondary)] min-h-[1.25rem] mb-4">
+          {error
+            ? <span className="text-[var(--error)]">{error}</span>
+            : completed
+              ? "Done!"
+              : progressMsg ?? `${operationLabels[operation]}...`}
+        </p>
+
+        {/* Buttons */}
+        <div className="flex justify-center gap-2">
+          {inProgress && (
+            <button
+              onClick={(e) => { e.stopPropagation(); onForceStop(); }}
+              className="px-3 py-1.5 text-xs text-[var(--error)] border border-[var(--error)]/30 rounded hover:bg-[var(--error)]/10 transition-colors"
+            >
+              Force Stop
+            </button>
+          )}
+          {(completed || error) && (
+            <button
+              onClick={(e) => { e.stopPropagation(); onClose(); }}
+              className="px-3 py-1.5 text-xs text-[var(--text-secondary)] hover:text-[var(--text-primary)] border border-[var(--border-color)] rounded transition-colors"
+            >
+              Close
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

app/src/components/projects/ProjectCard.tsx

@@ -1,5 +1,6 @@
 import { useState, useEffect } from "react";
 import { open } from "@tauri-apps/plugin-dialog";
+import { listen } from "@tauri-apps/api/event";
 import type { Project, ProjectPath, AuthMode, BedrockConfig, BedrockAuthMethod } from "../../lib/types";
 import { useProjects } from "../../hooks/useProjects";
 import { useTerminal } from "../../hooks/useTerminal";
@@ -7,6 +8,7 @@ import { useAppState } from "../../store/appState";
 import EnvVarsModal from "./EnvVarsModal";
 import PortMappingsModal from "./PortMappingsModal";
 import ClaudeInstructionsModal from "./ClaudeInstructionsModal";
+import ContainerProgressModal from "./ContainerProgressModal";
 
 interface Props {
   project: Project;
@@ -23,6 +25,9 @@ export default function ProjectCard({ project }: Props) {
   const [showEnvVarsModal, setShowEnvVarsModal] = useState(false);
   const [showPortMappingsModal, setShowPortMappingsModal] = useState(false);
   const [showClaudeInstructionsModal, setShowClaudeInstructionsModal] = useState(false);
+  const [progressMsg, setProgressMsg] = useState<string | null>(null);
+  const [activeOperation, setActiveOperation] = useState<"starting" | "stopping" | "resetting" | null>(null);
+  const [operationCompleted, setOperationCompleted] = useState(false);
   const isSelected = selectedProjectId === project.id;
   const isStopped = project.status === "stopped" || project.status === "error";
 
@@ -64,9 +69,38 @@ export default function ProjectCard({ project }: Props) {
     setBedrockModelId(project.bedrock_config?.model_id ?? "");
   }, [project]);
 
+  // Listen for container progress events
+  useEffect(() => {
+    const unlisten = listen<{ project_id: string; message: string }>(
+      "container-progress",
+      (event) => {
+        if (event.payload.project_id === project.id) {
+          setProgressMsg(event.payload.message);
+        }
+      }
+    );
+    return () => { unlisten.then((f) => f()); };
+  }, [project.id]);
+
+  // Mark operation completed when status settles
+  useEffect(() => {
+    if (project.status === "running" || project.status === "stopped" || project.status === "error") {
+      if (activeOperation) {
+        setOperationCompleted(true);
+      }
+      // Clear progress if no modal is managing it
+      if (!activeOperation) {
+        setProgressMsg(null);
+      }
+    }
+  }, [project.status, activeOperation]);
+
   const handleStart = async () => {
     setLoading(true);
     setError(null);
+    setProgressMsg(null);
+    setOperationCompleted(false);
+    setActiveOperation("starting");
     try {
       await start(project.id);
     } catch (e) {
@@ -79,6 +113,9 @@ export default function ProjectCard({ project }: Props) {
   const handleStop = async () => {
     setLoading(true);
     setError(null);
+    setProgressMsg(null);
+    setOperationCompleted(false);
+    setActiveOperation("stopping");
     try {
       await stop(project.id);
     } catch (e) {
@@ -96,6 +133,21 @@ export default function ProjectCard({ project }: Props) {
     }
   };
 
+  const handleForceStop = async () => {
+    try {
+      await stop(project.id);
+    } catch (e) {
+      setError(String(e));
+    }
+  };
+
+  const closeModal = () => {
+    setActiveOperation(null);
+    setOperationCompleted(false);
+    setProgressMsg(null);
+    setError(null);
+  };
+
   const defaultBedrockConfig: BedrockConfig = {
     auth_method: "static_credentials",
     aws_region: "us-east-1",
@@ -302,6 +354,10 @@ export default function ProjectCard({ project }: Props) {
                 <ActionButton
                   onClick={async () => {
                     setLoading(true);
+                    setError(null);
+                    setProgressMsg(null);
+                    setOperationCompleted(false);
+                    setActiveOperation("resetting");
                     try { await rebuild(project.id); } catch (e) { setError(String(e)); }
                     setLoading(false);
                   }}
@@ -315,9 +371,12 @@ export default function ProjectCard({ project }: Props) {
                 <ActionButton onClick={handleOpenTerminal} disabled={loading} label="Terminal" accent />
               </>
             ) : (
+              <>
                 <span className="text-xs text-[var(--text-secondary)]">
-                {project.status}...
+                  {progressMsg ?? `${project.status}...`}
                 </span>
+                <ActionButton onClick={handleStop} disabled={loading} label="Force Stop" danger />
+              </>
             )}
             <ActionButton
               onClick={(e) => { e?.stopPropagation?.(); setShowConfig(!showConfig); }}
@@ -722,6 +781,18 @@ export default function ProjectCard({ project }: Props) {
           onClose={() => setShowClaudeInstructionsModal(false)}
         />
       )}
+
+      {activeOperation && (
+        <ContainerProgressModal
+          projectName={project.name}
+          operation={activeOperation}
+          progressMsg={progressMsg}
+          error={error}
+          completed={operationCompleted}
+          onForceStop={handleForceStop}
+          onClose={closeModal}
+        />
+      )}
     </div>
   );
 }

app/src/components/terminal/TerminalView.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { Terminal } from "@xterm/xterm";
 import { FitAddon } from "@xterm/addon-fit";
 import { WebglAddon } from "@xterm/addon-webgl";
@@ -6,6 +6,8 @@ import { WebLinksAddon } from "@xterm/addon-web-links";
 import { openUrl } from "@tauri-apps/plugin-opener";
 import "@xterm/xterm/css/xterm.css";
 import { useTerminal } from "../../hooks/useTerminal";
+import { UrlDetector } from "../../lib/urlDetector";
+import UrlToast from "./UrlToast";
 
 interface Props {
   sessionId: string;
@@ -14,10 +16,16 @@ interface Props {
 
 export default function TerminalView({ sessionId, active }: Props) {
   const containerRef = useRef<HTMLDivElement>(null);
+  const terminalContainerRef = useRef<HTMLDivElement>(null);
   const termRef = useRef<Terminal | null>(null);
   const fitRef = useRef<FitAddon | null>(null);
   const webglRef = useRef<WebglAddon | null>(null);
-  const { sendInput, resize, onOutput, onExit } = useTerminal();
+  const detectorRef = useRef<UrlDetector | null>(null);
+  const { sendInput, pasteImage, resize, onOutput, onExit } = useTerminal();
+
+  const [detectedUrl, setDetectedUrl] = useState<string | null>(null);
+  const [imagePasteMsg, setImagePasteMsg] = useState<string | null>(null);
+  const [isAtBottom, setIsAtBottom] = useState(true);
 
   useEffect(() => {
     if (!containerRef.current) return;
@@ -79,12 +87,56 @@ export default function TerminalView({ sessionId, active }: Props) {
       sendInput(sessionId, data);
     });
 
+    // Track scroll position to show "Jump to Current" button
+    const scrollDisposable = term.onScroll(() => {
+      const buf = term.buffer.active;
+      setIsAtBottom(buf.viewportY >= buf.baseY);
+    });
+
+    // Handle image paste: intercept paste events with image data,
+    // upload to the container, and inject the file path into terminal input.
+    const handlePaste = (e: ClipboardEvent) => {
+      const items = e.clipboardData?.items;
+      if (!items) return;
+
+      for (const item of Array.from(items)) {
+        if (item.type.startsWith("image/")) {
+          e.preventDefault();
+          e.stopPropagation();
+
+          const blob = item.getAsFile();
+          if (!blob) return;
+
+          blob.arrayBuffer().then(async (buf) => {
+            try {
+              setImagePasteMsg("Uploading image...");
+              const data = new Uint8Array(buf);
+              const filePath = await pasteImage(sessionId, data);
+              // Inject the file path into terminal stdin
+              sendInput(sessionId, filePath);
+              setImagePasteMsg(`Image saved to ${filePath}`);
+            } catch (err) {
+              console.error("Image paste failed:", err);
+              setImagePasteMsg("Image paste failed");
+            }
+          });
+          return; // Only handle the first image
+        }
+      }
+    };
+
+    containerRef.current.addEventListener("paste", handlePaste, { capture: true });
+
     // Handle backend output -> terminal
     let aborted = false;
 
+    const detector = new UrlDetector((url) => setDetectedUrl(url));
+    detectorRef.current = detector;
+
     const outputPromise = onOutput(sessionId, (data) => {
       if (aborted) return;
       term.write(data);
+      detector.feed(data);
     }).then((unlisten) => {
       if (aborted) unlisten();
       return unlisten;
@@ -116,7 +168,11 @@ export default function TerminalView({ sessionId, active }: Props) {
 
     return () => {
       aborted = true;
+      detector.dispose();
+      detectorRef.current = null;
       inputDisposable.dispose();
+      scrollDisposable.dispose();
+      containerRef.current?.removeEventListener("paste", handlePaste, { capture: true });
       outputPromise.then((fn) => fn?.());
       exitPromise.then((fn) => fn?.());
       if (resizeRafId !== null) cancelAnimationFrame(resizeRafId);
@@ -160,11 +216,67 @@ export default function TerminalView({ sessionId, active }: Props) {
     }
   }, [active]);
 
+  // Auto-dismiss toast after 30 seconds
+  useEffect(() => {
+    if (!detectedUrl) return;
+    const timer = setTimeout(() => setDetectedUrl(null), 30_000);
+    return () => clearTimeout(timer);
+  }, [detectedUrl]);
+
+  // Auto-dismiss image paste message after 3 seconds
+  useEffect(() => {
+    if (!imagePasteMsg) return;
+    const timer = setTimeout(() => setImagePasteMsg(null), 3_000);
+    return () => clearTimeout(timer);
+  }, [imagePasteMsg]);
+
+  const handleOpenUrl = useCallback(() => {
+    if (detectedUrl) {
+      openUrl(detectedUrl).catch((e) =>
+        console.error("Failed to open URL:", e),
+      );
+      setDetectedUrl(null);
+    }
+  }, [detectedUrl]);
+
+  const handleScrollToBottom = useCallback(() => {
+    termRef.current?.scrollToBottom();
+    setIsAtBottom(true);
+  }, []);
+
   return (
+    <div
+      ref={terminalContainerRef}
+      className={`w-full h-full relative ${active ? "" : "hidden"}`}
+    >
+      {detectedUrl && (
+        <UrlToast
+          url={detectedUrl}
+          onOpen={handleOpenUrl}
+          onDismiss={() => setDetectedUrl(null)}
+        />
+      )}
+      {imagePasteMsg && (
+        <div
+          className="absolute top-2 left-1/2 -translate-x-1/2 z-50 px-3 py-1.5 rounded-md text-xs font-medium bg-[#1f2937] text-[#e6edf3] border border-[#30363d] shadow-lg"
+          onClick={() => setImagePasteMsg(null)}
+        >
+          {imagePasteMsg}
+        </div>
+      )}
+      {!isAtBottom && (
+        <button
+          onClick={handleScrollToBottom}
+          className="absolute bottom-4 right-4 z-50 px-3 py-1.5 rounded-md text-xs font-medium bg-[#1f2937] text-[#58a6ff] border border-[#30363d] shadow-lg hover:bg-[#2d3748] transition-colors cursor-pointer"
+        >
+          Jump to Current ↓
+        </button>
+      )}
       <div
         ref={containerRef}
-      className={`w-full h-full ${active ? "" : "hidden"}`}
+        className="w-full h-full"
         style={{ padding: "8px" }}
       />
+    </div>
   );
 }

app/src/components/terminal/UrlToast.tsx

@@ -0,0 +1,101 @@
+interface Props {
+  url: string;
+  onOpen: () => void;
+  onDismiss: () => void;
+}
+
+export default function UrlToast({ url, onOpen, onDismiss }: Props) {
+  return (
+    <div
+      className="animate-slide-down"
+      style={{
+        position: "absolute",
+        top: 12,
+        left: "50%",
+        transform: "translateX(-50%)",
+        zIndex: 40,
+        display: "flex",
+        alignItems: "center",
+        gap: 10,
+        padding: "8px 12px",
+        background: "var(--bg-secondary)",
+        border: "1px solid var(--border-color)",
+        borderRadius: 8,
+        boxShadow: "0 4px 12px rgba(0,0,0,0.4)",
+        maxWidth: "min(90%, 600px)",
+      }}
+    >
+      <div style={{ flex: 1, minWidth: 0 }}>
+        <div
+          style={{
+            fontSize: 12,
+            color: "var(--text-secondary)",
+            marginBottom: 2,
+          }}
+        >
+          Long URL detected
+        </div>
+        <div
+          style={{
+            fontSize: 12,
+            fontFamily: "monospace",
+            color: "var(--text-primary)",
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap",
+          }}
+        >
+          {url}
+        </div>
+      </div>
+
+      <button
+        onClick={onOpen}
+        style={{
+          padding: "4px 12px",
+          fontSize: 12,
+          fontWeight: 600,
+          color: "#fff",
+          background: "var(--accent)",
+          border: "none",
+          borderRadius: 4,
+          cursor: "pointer",
+          whiteSpace: "nowrap",
+          flexShrink: 0,
+        }}
+        onMouseEnter={(e) =>
+          (e.currentTarget.style.background = "var(--accent-hover)")
+        }
+        onMouseLeave={(e) =>
+          (e.currentTarget.style.background = "var(--accent)")
+        }
+      >
+        Open
+      </button>
+
+      <button
+        onClick={onDismiss}
+        style={{
+          padding: "2px 6px",
+          fontSize: 14,
+          lineHeight: 1,
+          color: "var(--text-secondary)",
+          background: "transparent",
+          border: "none",
+          borderRadius: 4,
+          cursor: "pointer",
+          flexShrink: 0,
+        }}
+        onMouseEnter={(e) =>
+          (e.currentTarget.style.color = "var(--text-primary)")
+        }
+        onMouseLeave={(e) =>
+          (e.currentTarget.style.color = "var(--text-secondary)")
+        }
+        aria-label="Dismiss"
+      >
+        ✕
+      </button>
+    </div>
+  );
+}

app/src/hooks/useDocker.ts

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { useShallow } from "zustand/react/shallow";
 import { listen } from "@tauri-apps/api/event";
 import { useAppState } from "../store/appState";
@@ -59,6 +59,39 @@ export function useDocker() {
     [setImageExists],
   );
 
+  const pollingRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const startDockerPolling = useCallback(() => {
+    // Don't start if already polling
+    if (pollingRef.current) return () => {};
+
+    const interval = setInterval(async () => {
+      try {
+        const available = await commands.checkDocker();
+        if (available) {
+          clearInterval(interval);
+          pollingRef.current = null;
+          setDockerAvailable(true);
+          // Also check image once Docker is available
+          try {
+            const exists = await commands.checkImageExists();
+            setImageExists(exists);
+          } catch {
+            setImageExists(false);
+          }
+        }
+      } catch {
+        // Still not available, keep polling
+      }
+    }, 5000);
+
+    pollingRef.current = interval;
+    return () => {
+      clearInterval(interval);
+      pollingRef.current = null;
+    };
+  }, [setDockerAvailable, setImageExists]);
+
   const pullImage = useCallback(
     async (imageName: string, onProgress?: (msg: string) => void) => {
       const unlisten = onProgress
@@ -84,5 +117,6 @@ export function useDocker() {
     checkImage,
     buildImage,
     pullImage,
+    startDockerPolling,
   };
 }

app/src/hooks/useProjects.ts

@@ -50,31 +50,45 @@ export function useProjects() {
     [removeProjectFromList],
   );
 
+  const setOptimisticStatus = useCallback(
+    (id: string, status: "starting" | "stopping") => {
+      const { projects } = useAppState.getState();
+      const project = projects.find((p) => p.id === id);
+      if (project) {
+        updateProjectInList({ ...project, status });
+      }
+    },
+    [updateProjectInList],
+  );
+
   const start = useCallback(
     async (id: string) => {
+      setOptimisticStatus(id, "starting");
       const updated = await commands.startProjectContainer(id);
       updateProjectInList(updated);
       return updated;
     },
-    [updateProjectInList],
+    [updateProjectInList, setOptimisticStatus],
   );
 
   const stop = useCallback(
     async (id: string) => {
+      setOptimisticStatus(id, "stopping");
       await commands.stopProjectContainer(id);
       const list = await commands.listProjects();
       setProjects(list);
     },
-    [setProjects],
+    [setProjects, setOptimisticStatus],
   );
 
   const rebuild = useCallback(
     async (id: string) => {
+      setOptimisticStatus(id, "starting");
       const updated = await commands.rebuildProjectContainer(id);
       updateProjectInList(updated);
       return updated;
     },
-    [updateProjectInList],
+    [updateProjectInList, setOptimisticStatus],
   );
 
   const update = useCallback(

app/src/hooks/useTerminal.ts

@@ -49,6 +49,14 @@ export function useTerminal() {
     [],
   );
 
+  const pasteImage = useCallback(
+    async (sessionId: string, imageData: Uint8Array) => {
+      const bytes = Array.from(imageData);
+      return commands.pasteImageToTerminal(sessionId, bytes);
+    },
+    [],
+  );
+
   const onOutput = useCallback(
     (sessionId: string, callback: (data: Uint8Array) => void) => {
       const eventName = `terminal-output-${sessionId}`;
@@ -76,6 +84,7 @@ export function useTerminal() {
     open,
     close,
     sendInput,
+    pasteImage,
     resize,
     onOutput,
     onExit,

app/src/index.css

@@ -46,3 +46,10 @@ body {
 ::-webkit-scrollbar-thumb:hover {
   background: var(--border-color);
 }
+
+/* Toast slide-down animation */
+@keyframes slide-down {
+  from { opacity: 0; transform: translate(-50%, -8px); }
+  to   { opacity: 1; transform: translate(-50%, 0); }
+}
+.animate-slide-down { animation: slide-down 0.2s ease-out; }

app/src/lib/tauri-commands.ts

@@ -47,6 +47,8 @@ export const terminalResize = (sessionId: string, cols: number, rows: number) =>
   invoke<void>("terminal_resize", { sessionId, cols, rows });
 export const closeTerminalSession = (sessionId: string) =>
   invoke<void>("close_terminal_session", { sessionId });
+export const pasteImageToTerminal = (sessionId: string, imageData: number[]) =>
+  invoke<string>("paste_image_to_terminal", { sessionId, imageData });
 
 // Updates
 export const getAppVersion = () => invoke<string>("get_app_version");

app/src/lib/urlDetector.ts

@@ -0,0 +1,127 @@
+/**
+ * Detects long URLs that span multiple hard-wrapped lines in PTY output.
+ *
+ * The Linux PTY hard-wraps long lines with \r\n at the terminal column width,
+ * which breaks xterm.js WebLinksAddon URL detection. This class flattens
+ * the buffer (stripping PTY wraps, converting blank lines to spaces) and
+ * matches URLs with a single regex, firing a callback for ones >= 100 chars.
+ *
+ * When a URL match extends to the end of the flattened buffer, emission is
+ * deferred (more chunks may still be arriving). A confirmation timer emits
+ * the pending URL if no further data arrives within 500 ms.
+ */
+
+const ANSI_RE =
+  /\x1b(?:\[[0-9;?]*[A-Za-z]|\][^\x07\x1b]*(?:\x07|\x1b\\)?|[()#][A-Za-z0-9]|.)/g;
+
+const MAX_BUFFER = 8 * 1024; // 8 KB rolling buffer cap
+const DEBOUNCE_MS = 300;
+const CONFIRM_MS = 500; // extra wait when URL reaches end of buffer
+const MIN_URL_LENGTH = 100;
+
+export type UrlCallback = (url: string) => void;
+
+export class UrlDetector {
+  private decoder = new TextDecoder();
+  private buffer = "";
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private confirmTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastEmitted = "";
+  private pendingUrl: string | null = null;
+  private callback: UrlCallback;
+
+  constructor(callback: UrlCallback) {
+    this.callback = callback;
+  }
+
+  /** Feed raw PTY output chunks. */
+  feed(data: Uint8Array): void {
+    this.buffer += this.decoder.decode(data, { stream: true });
+
+    // Cap buffer to avoid unbounded growth
+    if (this.buffer.length > MAX_BUFFER) {
+      this.buffer = this.buffer.slice(-MAX_BUFFER);
+    }
+
+    // Cancel pending timers — new data arrived, rescan from scratch
+    if (this.timer !== null) clearTimeout(this.timer);
+    if (this.confirmTimer !== null) {
+      clearTimeout(this.confirmTimer);
+      this.confirmTimer = null;
+    }
+
+    // Debounce — scan after 300 ms of silence
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.scan();
+    }, DEBOUNCE_MS);
+  }
+
+  private scan(): void {
+    // 1. Strip ANSI escape sequences
+    const clean = this.buffer.replace(ANSI_RE, "");
+
+    // 2. Flatten the buffer:
+    //    - Blank lines (2+ consecutive line breaks) → space (real paragraph break / URL terminator)
+    //    - Remaining \r and \n → removed (PTY hard-wrap artifacts)
+    const flat = clean
+      .replace(/(\r?\n){2,}/g, " ")
+      .replace(/[\r\n]/g, "");
+
+    if (!flat) return;
+
+    // 3. Match URLs on the flattened string — spans across wrapped lines naturally
+    const urlRe = /https?:\/\/[^\s'"<>\x07]+/g;
+    let m: RegExpExecArray | null;
+
+    while ((m = urlRe.exec(flat)) !== null) {
+      const url = m[0];
+
+      // 4. Filter by length
+      if (url.length < MIN_URL_LENGTH) continue;
+
+      // 5. If the match extends to the very end of the flattened string,
+      //    more chunks may still be arriving — defer emission.
+      if (m.index + url.length >= flat.length) {
+        this.pendingUrl = url;
+        this.confirmTimer = setTimeout(() => {
+          this.confirmTimer = null;
+          this.emitPending();
+        }, CONFIRM_MS);
+        return;
+      }
+
+      // 6. URL is clearly complete (more content follows) — dedup + emit
+      this.pendingUrl = null;
+      if (url !== this.lastEmitted) {
+        this.lastEmitted = url;
+        this.callback(url);
+      }
+    }
+
+    // Scan finished without a URL at the buffer end.
+    // If we had a pending URL from a previous scan, it's now confirmed complete.
+    if (this.pendingUrl) {
+      this.emitPending();
+    }
+  }
+
+  private emitPending(): void {
+    if (this.pendingUrl && this.pendingUrl !== this.lastEmitted) {
+      this.lastEmitted = this.pendingUrl;
+      this.callback(this.pendingUrl);
+    }
+    this.pendingUrl = null;
+  }
+
+  dispose(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.confirmTimer !== null) {
+      clearTimeout(this.confirmTimer);
+      this.confirmTimer = null;
+    }
+  }
+}

container/Dockerfile

@@ -1,5 +1,6 @@
 FROM ubuntu:24.04
 
+# Multi-arch: builds for linux/amd64 and linux/arm64 (Apple Silicon)
 # Avoid interactive prompts during package install
 ENV DEBIAN_FRONTEND=noninteractive