Merge branch 'main' into feature/restart-server-on-update

2026-04-14 17:41:32 +00:00 · 2026-04-14 17:18:33 +02:00
parent 1a0f10217d 13e97e2c71
commit 9d7d12742f
13 changed files with 578 additions and 103 deletions
--- a/README.de.md
+++ b/README.de.md
@@ -76,6 +76,8 @@ Der schnellste Einstieg – keine lokale Einrichtung erforderlich. Erhalte eine

 ### Self-Hosted (Open Source)

+#### npm
+
 CloudCLI UI sofort mit **npx** ausprobieren (erfordert **Node.js** v22+):

 ```bash
@@ -93,6 +95,15 @@ cloudcli

 Die **[Dokumentation →](https://cloudcli.ai/docs)** enthält weitere Konfigurationsoptionen, PM2, Remote-Server-Einrichtung und mehr.

+#### Docker Sandboxes (Experimentell)
+
+Agents in isolierten Sandboxes mit Hypervisor-Isolation ausführen. Standardmäßig wird Claude Code gestartet. Erfordert die [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli sandbox ~/my-project
+```
+
+Unterstützt Claude Code, Codex und Gemini CLI. Weitere Details in der [Sandbox-Dokumentation](docker/).

 ---

--- a/README.ja.md
+++ b/README.ja.md
@@ -72,6 +72,8 @@

 ### セルフホスト（オープンソース）

+#### npm
+
 **npx** で今すぐ CloudCLI UI を試せます（**Node.js** v22+ が必要）：

 ```bash
@@ -89,6 +91,15 @@ cloudcli

 より詳細な設定オプション、PM2、リモートサーバー設定などについては **[ドキュメントはこちら →](https://cloudcli.ai/docs)** を参照してください。

+#### Docker Sandboxes（実験的）
+
+ハイパーバイザーレベルの分離でエージェントをサンドボックスで実行します。デフォルトでは Claude Code が起動します。[`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/) が必要です。
+
+```
+npx @cloudcli-ai/cloudcli sandbox ~/my-project
+```
+
+Claude Code、Codex、Gemini CLI に対応。詳細は[サンドボックスのドキュメント](docker/)をご覧ください。

 ---

--- a/README.ko.md
+++ b/README.ko.md
@@ -72,6 +72,8 @@

 ### 셀프 호스트 (오픈 소스)

+#### npm
+
 **npx**로 즉시 CloudCLI UI를 실행하세요 (Node.js v22+ 필요):

 ```bash
@@ -87,7 +89,17 @@ cloudcli

 `http://localhost:3001`을 열면 기존 세션이 자동으로 발견됩니다.

-자세한 구성 옵션, PM2, 원격 서버 설정 등은 **[문서 →](https://cloudcli.ai/docs)**를 참고하세요
+자세한 구성 옵션, PM2, 원격 서버 설정 등은 **[문서 →](https://cloudcli.ai/docs)**를 참고하세요.
+
+#### Docker Sandboxes (실험적)
+
+하이퍼바이저 수준 격리로 에이전트를 샌드박스에서 실행합니다. 기본 에이전트는 Claude Code입니다. [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/)가 필요합니다.
+
+```
+npx @cloudcli-ai/cloudcli sandbox ~/my-project
+```
+
+Claude Code, Codex, Gemini CLI를 지원합니다. 자세한 내용은 [샌드박스 문서](docker/)를 참고하세요.

 ---

--- a/README.md
+++ b/README.md
@@ -76,6 +76,8 @@ The fastest way to get started — no local setup required. Get a fully managed,

 ### Self-Hosted (Open source)

+#### npm
+
 Try CloudCLI UI instantly with **npx** (requires **Node.js** v22+):

 ```
@@ -91,33 +93,41 @@ cloudcli

 Open `http://localhost:3001` — all your existing sessions are discovered automatically.

-Visit the **[documentation →](https://cloudcli.ai/docs)** for more full configuration options, PM2, remote server setup and more
+Visit the **[documentation →](https://cloudcli.ai/docs)** for full configuration options, PM2, remote server setup and more.
+
+#### Docker Sandboxes (Experimental)
+
+Run agents in isolated sandboxes with hypervisor-level isolation. Starts Claude Code by default. Requires the [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli sandbox ~/my-project
+```
+
+Supports Claude Code, Codex, and Gemini CLI. See the [sandbox docs](docker/) for setup and advanced options.


 ---

 ## Which option is right for you?

-CloudCLI UI is the open source UI layer that powers CloudCLI Cloud. You can self-host it on your own machine, or use CloudCLI Cloud which builds on top of it with a full managed cloud environment, team features, and deeper integrations.
+CloudCLI UI is the open source UI layer that powers CloudCLI Cloud. You can self-host it on your own machine, run it in a Docker sandbox for isolation, or use CloudCLI Cloud for a fully managed environment.

-| | CloudCLI UI (Self-hosted) | CloudCLI Cloud |
-|---|---|---|
-| **Best for** | Developers who want a full UI for local agent sessions on their own machine | Teams and developers who want agents running in the cloud, accessible from anywhere |
-| **How you access it** | Browser via `[yourip]:port` | Browser, any IDE, REST API, n8n |
-| **Setup** | `npx @cloudcli-ai/cloudcli` | No setup required |
-| **Machine needs to stay on** | Yes | No |
-| **Mobile access** | Any browser on your network | Any device, native app coming |
-| **Sessions available** | All sessions auto-discovered from `~/.claude` | All sessions within your cloud environment |
-| **Agents supported** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
-| **File explorer and Git** | Yes, built into the UI | Yes, built into the UI |
-| **MCP configuration** | Managed via UI, synced with your local `~/.claude` config | Managed via UI |
-| **IDE access** | Your local IDE | Any IDE connected to your cloud environment |
-| **REST API** | Yes | Yes |
-| **n8n node** | No | Yes |
-| **Team sharing** | No | Yes |
-| **Platform cost** | Free, open source | Starts at $7/month |
+| | Self-Hosted (npm) | Self-Hosted (Docker Sandbox) *(Experimental)* | CloudCLI Cloud |
+|---|---|---|---|
+| **Best for** | Local agent sessions on your own machine | Isolated agents with web/mobile IDE | Teams who want agents in the cloud |
+| **How you access it** | Browser via `[yourip]:port` | Browser via `localhost:port` | Browser, any IDE, REST API, n8n |
+| **Setup** | `npx @cloudcli-ai/cloudcli` | `npx @cloudcli-ai/cloudcli sandbox ~/project` | No setup required |
+| **Isolation** | Runs on your host | Hypervisor-level sandbox (microVM) | Full cloud isolation |
+| **Machine needs to stay on** | Yes | Yes | No |
+| **Mobile access** | Any browser on your network | Any browser on your network | Any device, native app coming |
+| **Agents supported** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
+| **File explorer and Git** | Yes | Yes | Yes |
+| **MCP configuration** | Synced with `~/.claude` | Managed via UI | Managed via UI |
+| **REST API** | Yes | Yes | Yes |
+| **Team sharing** | No | No | Yes |
+| **Platform cost** | Free, open source | Free, open source | Starts at $7/month |

-> Both options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.
+> All options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.

 ---

--- a/README.ru.md
+++ b/README.ru.md
@@ -76,6 +76,8 @@

 ### Self-Hosted (Open source)

+#### npm
+
 Попробовать CloudCLI UI можно сразу через **npx** (требуется **Node.js** v22+):

 ```bash
@@ -91,8 +93,17 @@ cloudcli

 Откройте `http://localhost:3001` — все ваши существующие сессии будут обнаружены автоматически.

-Посетите **[документацию →](https://cloudcli.ai/docs)**, чтобы узнать про дополнительные варианты конфигурации, PM2, настройку удалённого сервера и многое другое
+Посетите **[документацию →](https://cloudcli.ai/docs)**, чтобы узнать про дополнительные варианты конфигурации, PM2, настройку удалённого сервера и многое другое.

+#### Docker Sandboxes (Экспериментально)
+
+Запускайте агентов в изолированных песочницах с гипервизорной изоляцией. По умолчанию запускается Claude Code. Требуется [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli sandbox ~/my-project
+```
+
+Поддерживаются Claude Code, Codex и Gemini CLI. Подробнее в [документации sandbox](docker/).

 ---

--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -72,6 +72,8 @@

 ### 自托管（开源）

+#### npm
+
 启动 CloudCLI UI，只需一行 `npx`（需要 Node.js v22+）：

 ```bash
@@ -87,7 +89,17 @@ cloudcli

 打开 `http://localhost:3001`，系统会自动发现所有现有会话。

-更多配置选项、PM2、远程服务器设置等，请参阅 **[文档 →](https://cloudcli.ai/docs)**
+更多配置选项、PM2、远程服务器设置等，请参阅 **[文档 →](https://cloudcli.ai/docs)**。
+
+#### Docker Sandboxes（实验性）
+
+在隔离的沙箱中运行代理，具有虚拟机管理程序级别的隔离。默认启动 Claude Code。需要 [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/)。
+
+```
+npx @cloudcli-ai/cloudcli sandbox ~/my-project
+```
+
+支持 Claude Code、Codex 和 Gemini CLI。详情请参阅 [沙箱文档](docker/)。

 ---

--- a/docker/README.md
+++ b/docker/README.md
@@ -1,89 +1,146 @@
-# CloudCLI — Docker Sandbox Templates
+<!-- Docker Hub short description (100 chars max): -->
+<!-- Sandbox templates for running AI coding agents with a web & mobile IDE (Claude Code, Codex, Gemini) -->

-Run AI coding agents with a full web IDE inside [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/).
+# Sandboxed coding agents with a web & mobile IDE (CloudCLI)

-Instead of a terminal-only experience, get a browser-based interface with chat, file explorer, git panel, shell, and MCP configuration — all running safely inside an isolated sandbox.
+[Docker Sandbox](https://docs.docker.com/ai/sandboxes/) templates that add [CloudCLI](https://cloudcli.ai) on top of Claude Code, Codex, and Gemini CLI. You get a full web and mobile IDE accessible from any browser on any device.

-## Available Templates
+## Get started

-| Template | Base Image | Agent |
-|----------|-----------|-------|
-| `cloudcli-ai/sandbox:claude-code` | `docker/sandbox-templates:claude-code` | Claude Code |
-| `cloudcli-ai/sandbox:codex` | `docker/sandbox-templates:codex` | OpenAI Codex |
-| `cloudcli-ai/sandbox:gemini` | `docker/sandbox-templates:gemini` | Gemini CLI |
+### 1. Install the sbx CLI

-## Quick Start
+Docker Sandboxes run agents in isolated microVMs. Install the `sbx` CLI:

-### 1. Start a sandbox with the template
+- **macOS**: `brew install docker/tap/sbx`
+- **Windows**: `winget install -h Docker.sbx`
+- **Linux**: `sudo apt-get install docker-sbx`
+
+Full instructions: [docs.docker.com/ai/sandboxes/get-started](https://docs.docker.com/ai/sandboxes/get-started/)
+
+### 2. Store your API key
+
+`sbx` manages credentials securely — your API key never enters the sandbox. Store it once:

 ```bash
-sbx run --template docker.io/cloudcli-ai/sandbox:claude-code claude ~/my-project
+sbx login
+sbx secret set -g anthropic
 ```

-### 2. Forward the UI port
+### 3. Launch Claude Code

 ```bash
-sbx ports <sandbox-name> --publish 3001:3001
+npx @cloudcli-ai/cloudcli sandbox ~/my-project
 ```

-### 3. Open the browser
+Open **http://localhost:3001**. Set a password on first visit. Start building.

-```
-http://localhost:3001
+### Using a different agent
+
+Store the matching API key and pass `--agent`:
+
+```bash
+# OpenAI Codex
+sbx secret set -g openai
+npx @cloudcli-ai/cloudcli sandbox ~/my-project --agent codex
+
+# Gemini CLI
+sbx secret set -g google
+npx @cloudcli-ai/cloudcli sandbox ~/my-project --agent gemini
 ```

-On first visit you'll set a password — this protects the UI if the port is ever exposed beyond localhost.
+### Available templates

-## What You Get
+| Agent | Template |
+|-------|----------|
+| **Claude Code** (default) | `docker.io/cloudcliai/sandbox:claude-code` |
+| OpenAI Codex | `docker.io/cloudcliai/sandbox:codex` |
+| Gemini CLI | `docker.io/cloudcliai/sandbox:gemini` |

- **Chat** — Rich conversation UI with markdown rendering, code blocks, and message history
- **Files** — Visual file tree with syntax-highlighted editor
- **Git** — Diff viewer, staging, branch switching, and commit — all visual
+These are used with `--template` when running `sbx` directly (see [Advanced usage](#advanced-usage)).
+
+## Managing sandboxes
+
+```bash
+cloudcli sandbox ls                  # List all sandboxes
+cloudcli sandbox stop my-project     # Stop (preserves state)
+cloudcli sandbox start my-project    # Restart and re-launch web UI
+cloudcli sandbox logs my-project     # View server logs
+cloudcli sandbox rm my-project       # Remove everything
+```
+
+## What you get
+
+- **Chat** — Markdown rendering, code blocks, message history
+- **Files** — File tree with syntax-highlighted editor
+- **Git** — Diff viewer, staging, branch switching, commits
 - **Shell** — Built-in terminal emulator
- **MCP** — Configure Model Context Protocol servers through the UI
+- **MCP** — Configure Model Context Protocol servers visually
 - **Mobile** — Works on tablet and phone browsers

-## Building Locally
-
-All Dockerfiles share scripts from `shared/`. Build with the `docker/` directory as context:
-
-```bash
-# Claude Code variant
-docker build -f docker/claude-code/Dockerfile -t cloudcli-sandbox:claude-code docker/
-
-# Codex variant
-docker build -f docker/codex/Dockerfile -t cloudcli-sandbox:codex docker/
-
-# Gemini variant
-docker build -f docker/gemini/Dockerfile -t cloudcli-sandbox:gemini docker/
-```
-
-## How It Works
-
-Each template extends Docker's official sandbox base image and adds:
-
-1. **Node.js 22** — Runtime for CloudCLI
-2. **CloudCLI** — Installed globally via `npm install -g @cloudcli-ai/cloudcli`
-3. **Auto-start** — The UI server starts in the background when the sandbox shell opens (port 3001)
-
-The agent (Claude Code, Codex, or Gemini) comes from the base image. CloudCLI connects to it and provides the web interface on top.
+Your project directory is mounted bidirectionally — edits propagate in real time, both ways.

 ## Configuration

-| Environment Variable | Default | Description |
-|---------------------|---------|-------------|
-| `SERVER_PORT` | `3001` | Port for the web UI |
-| `HOST` | `0.0.0.0` | Bind address |
-| `DATABASE_PATH` | `~/.cloudcli/auth.db` | SQLite database location |
-
-## Network Policies
-
-If your sandbox uses restricted network policies, allow the UI port:
+Set variables at creation time with `--env`:

 ```bash
-sbx policy allow network "localhost:3001"
+npx @cloudcli-ai/cloudcli sandbox ~/my-project --env SERVER_PORT=8080
 ```

+Or inside a running sandbox:
+
+```bash
+sbx exec my-project bash -c 'echo "export SERVER_PORT=8080" >> /etc/sandbox-persistent.sh'
+sbx exec my-project bash -c 'pkill -f "server/index.js"; . ~/.cloudcli-start.sh'
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SERVER_PORT` | `3001` | Web UI port |
+| `HOST` | `0.0.0.0` | Bind address (must be `0.0.0.0` for `sbx ports`) |
+| `DATABASE_PATH` | `~/.cloudcli/auth.db` | SQLite database location |
+
+## Advanced usage
+
+For branch mode, multiple workspaces, memory limits, or the terminal agent experience, use `sbx` with the template:
+
+```bash
+# Terminal agent + web UI
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --name my-project
+sbx ports my-project --publish 3001:3001
+
+# Branch mode (Git worktree isolation)
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --branch my-feature
+
+# Multiple workspaces
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/project ~/shared-libs:ro
+
+# Pass a prompt directly
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project -- "Fix the auth bug"
+```
+
+CloudCLI auto-starts via `.bashrc` when using `sbx run`.
+
+Full options in the [Docker Sandboxes usage guide](https://docs.docker.com/ai/sandboxes/usage/).
+
+## Network policies
+
+Sandboxes restrict outbound access by default. To reach host services from inside the sandbox:
+
+```bash
+sbx policy allow network localhost:11434
+# Inside the sandbox: curl http://host.docker.internal:11434
+```
+
+The web UI itself doesn't need a policy — access it via `sbx ports`.
+
+## Links
+
+- [CloudCLI Cloud](https://cloudcli.ai) — fully managed, no setup required
+- [Documentation](https://cloudcli.ai/docs) — full configuration guide
+- [Discord](https://discord.gg/buxwujPNRE) — community support
+- [GitHub](https://github.com/siteboon/claudecodeui) — source code and issues
+
 ## License

-These templates are free and open-source under the same license as CloudCLI (AGPL-3.0-or-later).
+AGPL-3.0-or-later
--- a/docker/claude-code/Dockerfile
+++ b/docker/claude-code/Dockerfile
@@ -5,7 +5,7 @@ COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
 RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh

 USER agent
-RUN npm install -g @cloudcli-ai/cloudcli
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version

-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
 RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc
--- a/docker/codex/Dockerfile
+++ b/docker/codex/Dockerfile
@@ -5,7 +5,7 @@ COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
 RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh

 USER agent
-RUN npm install -g @cloudcli-ai/cloudcli
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version

-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
 RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc
--- a/docker/gemini/Dockerfile
+++ b/docker/gemini/Dockerfile
@@ -5,7 +5,7 @@ COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
 RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh

 USER agent
-RUN npm install -g @cloudcli-ai/cloudcli
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version

-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
 RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc
--- a/docker/shared/install-cloudcli.sh
+++ b/docker/shared/install-cloudcli.sh
@@ -1,13 +1,10 @@
 #!/bin/bash
 set -e

-# Install Node.js 22 LTS
-curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
-
-# Install Node.js + build tools needed for native modules (node-pty, better-sqlite3, bcrypt)
-# Node.js + build tools for native modules + common dev tools
-apt-get install -y --no-install-recommends \
-  nodejs build-essential python3 python3-setuptools \
+# Install build tools needed for native modules (node-pty, better-sqlite3, bcrypt)
+# Node.js is already provided by the sandbox base image
+apt-get update && apt-get install -y --no-install-recommends \
+  build-essential python3 python3-setuptools \
  jq ripgrep sqlite3 zip unzip tree vim-tiny

 # Clean up apt cache to reduce image size
--- a/docker/shared/start-cloudcli.sh
+++ b/docker/shared/start-cloudcli.sh
@@ -4,19 +4,14 @@
 # This script is sourced from ~/.bashrc on sandbox shell open.

 if ! pgrep -f "server/index.js" > /dev/null 2>&1; then
-  # Start the pre-installed version immediately
  nohup cloudcli start --port 3001 > /tmp/cloudcli-ui.log 2>&1 &
  disown

-  # Check for updates in the background (non-blocking)
-  nohup npm update -g @cloudcli-ai/cloudcli > /tmp/cloudcli-update.log 2>&1 &
-  disown
-
  echo ""
  echo "  CloudCLI is starting on port 3001..."
  echo ""
-  echo "  To access the web UI, forward the port:"
-  echo "    sbx ports \$(hostname) --publish 3001:3001"
+  echo "  Forward the port from another terminal:"
+  echo "    sbx ports <sandbox-name> --publish 3001:3001"
  echo ""
  echo "  Then open: http://localhost:3001"
  echo ""
--- a/server/cli.js
+++ b/server/cli.js
@@ -7,6 +7,7 @@
 * Commands:
 *   (no args)     - Start the server (default)
 *   start         - Start the server
+ *   sandbox       - Manage Docker sandbox environments
 *   status        - Show configuration and data locations
 *   help          - Show help information
 *   version       - Show version information
@@ -150,6 +151,7 @@ Usage:

 Commands:
  start          Start the CloudCLI server (default)
+  sandbox        Manage Docker sandbox environments
  status         Show configuration and data locations
  update         Update to the latest version
  help           Show this help information
@@ -164,8 +166,7 @@ Options:
 Examples:
  $ cloudcli                        # Start with defaults
  $ cloudcli --port 8080            # Start on port 8080
-  $ cloudcli -p 3000                # Short form for port
-  $ cloudcli start --port 4000      # Explicit start command
+  $ cloudcli sandbox ~/my-project   # Run in a Docker sandbox
  $ cloudcli status                 # Show configuration

 Environment Variables:
@@ -244,6 +245,357 @@ async function updatePackage() {
    }
 }

+// ── Sandbox command ─────────────────────────────────────────
+
+const SANDBOX_TEMPLATES = {
+    claude: 'docker.io/cloudcliai/sandbox:claude-code',
+    codex: 'docker.io/cloudcliai/sandbox:codex',
+    gemini: 'docker.io/cloudcliai/sandbox:gemini',
+};
+
+const SANDBOX_SECRETS = {
+    claude: 'anthropic',
+    codex: 'openai',
+    gemini: 'google',
+};
+
+function parseSandboxArgs(args) {
+    const result = {
+        subcommand: null,
+        workspace: null,
+        agent: 'claude',
+        name: null,
+        port: 3001,
+        template: null,
+        env: [],
+    };
+
+    const subcommands = ['ls', 'stop', 'start', 'rm', 'logs', 'help'];
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+
+        if (i === 0 && subcommands.includes(arg)) {
+            result.subcommand = arg;
+        } else if (arg === '--agent' || arg === '-a') {
+            result.agent = args[++i];
+        } else if (arg === '--name' || arg === '-n') {
+            result.name = args[++i];
+        } else if (arg === '--port') {
+            result.port = parseInt(args[++i], 10);
+        } else if (arg === '--template' || arg === '-t') {
+            result.template = args[++i];
+        } else if (arg === '--env' || arg === '-e') {
+            result.env.push(args[++i]);
+        } else if (!arg.startsWith('-')) {
+            if (!result.subcommand) {
+                result.workspace = arg;
+            } else {
+                result.name = arg; // for stop/start/rm/logs <name>
+            }
+        }
+    }
+
+    // Default subcommand based on what we got
+    if (!result.subcommand) {
+        result.subcommand = 'create';
+    }
+
+    // Derive name from workspace path if not set
+    if (!result.name && result.workspace) {
+        result.name = path.basename(path.resolve(result.workspace.replace(/^~/, os.homedir())));
+    }
+
+    // Default template from agent
+    if (!result.template) {
+        result.template = SANDBOX_TEMPLATES[result.agent] || SANDBOX_TEMPLATES.claude;
+    }
+
+    return result;
+}
+
+function showSandboxHelp() {
+    console.log(`
+${c.bright('CloudCLI Sandbox')} — Run CloudCLI inside Docker Sandboxes
+
+Usage:
+  cloudcli sandbox <workspace>            Create and start a sandbox
+  cloudcli sandbox <subcommand> [name]    Manage sandboxes
+
+Subcommands:
+  ${c.bright('(default)')}    Create a sandbox and start the web UI
+  ${c.bright('ls')}           List all sandboxes
+  ${c.bright('start')}        Restart a stopped sandbox and re-launch the web UI
+  ${c.bright('stop')}         Stop a sandbox (preserves state)
+  ${c.bright('rm')}           Remove a sandbox
+  ${c.bright('logs')}         Show CloudCLI server logs
+  ${c.bright('help')}         Show this help
+
+Options:
+  -a, --agent <agent>       Agent to use: claude, codex, gemini (default: claude)
+  -n, --name <name>         Sandbox name (default: derived from workspace folder)
+  -t, --template <image>    Custom template image
+  -e, --env <KEY=VALUE>     Set environment variable (repeatable)
+      --port <port>         Host port for the web UI (default: 3001)
+
+Examples:
+  $ cloudcli sandbox ~/my-project
+  $ cloudcli sandbox ~/my-project --agent codex --port 8080
+  $ cloudcli sandbox ~/my-project --env SERVER_PORT=8080 --env HOST=0.0.0.0
+  $ cloudcli sandbox ls
+  $ cloudcli sandbox stop my-project
+  $ cloudcli sandbox start my-project
+  $ cloudcli sandbox rm my-project
+
+Prerequisites:
+  1. Install sbx CLI: https://docs.docker.com/ai/sandboxes/get-started/
+  2. Authenticate and store your API key:
+       sbx login
+       sbx secret set -g anthropic   # for Claude
+       sbx secret set -g openai      # for Codex
+       sbx secret set -g google      # for Gemini
+
+Advanced usage:
+  For branch mode, multiple workspaces, memory limits, network policies,
+  or passing prompts to the agent, use sbx directly with the template:
+
+    sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --branch my-feature
+    sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/project ~/libs:ro --memory 8g
+
+  Full Docker Sandboxes docs: https://docs.docker.com/ai/sandboxes/usage/
+`);
+}
+
+async function sandboxCommand(args) {
+    const { execFileSync } = await import('child_process');
+
+    // Safe execution — uses execFileSync (no shell) to prevent injection
+    const sbx = (subcmd, opts = {}) => {
+        const result = execFileSync('sbx', subcmd, {
+            encoding: 'utf8',
+            stdio: opts.inherit ? 'inherit' : 'pipe',
+        });
+        return result || '';
+    };
+
+    const opts = parseSandboxArgs(args);
+
+    if (opts.subcommand === 'help') {
+        showSandboxHelp();
+        return;
+    }
+
+    // Validate name (alphanumeric, hyphens, underscores only)
+    if (opts.name && !/^[\w-]+$/.test(opts.name)) {
+        console.error(`\n${c.error('❌')} Invalid sandbox name: ${opts.name}`);
+        console.log(`   Names may only contain letters, numbers, hyphens, and underscores.\n`);
+        process.exit(1);
+    }
+
+    // Check sbx is installed
+    try {
+        sbx(['version']);
+    } catch {
+        console.error(`\n${c.error('❌')} ${c.bright('sbx')} CLI not found.\n`);
+        console.log(`   Install it from: ${c.info('https://docs.docker.com/ai/sandboxes/get-started/')}`);
+        console.log(`   Then run: ${c.bright('sbx login')}`);
+        console.log(`   And store your API key: ${c.bright('sbx secret set -g anthropic')}\n`);
+        process.exit(1);
+    }
+
+    switch (opts.subcommand) {
+
+        case 'ls':
+            sbx(['ls'], { inherit: true });
+            break;
+
+        case 'stop':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox stop <name>\n`);
+                process.exit(1);
+            }
+            sbx(['stop', opts.name], { inherit: true });
+            break;
+
+        case 'rm':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox rm <name>\n`);
+                process.exit(1);
+            }
+            sbx(['rm', opts.name], { inherit: true });
+            break;
+
+        case 'logs':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox logs <name>\n`);
+                process.exit(1);
+            }
+            try {
+                sbx(['exec', opts.name, 'bash', '-c', 'cat /tmp/cloudcli-ui.log'], { inherit: true });
+            } catch (e) {
+                console.error(`\n${c.error('❌')} Could not read logs: ${e.message || 'Is the sandbox running?'}\n`);
+            }
+            break;
+
+        case 'start': {
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox start <name>\n`);
+                process.exit(1);
+            }
+            console.log(`\n${c.info('▶')} Starting sandbox ${c.bright(opts.name)}...`);
+            try {
+                sbx(['start', opts.name], { inherit: true });
+            } catch { /* might already be running */ }
+
+            console.log(`${c.info('▶')} Launching CloudCLI web server...`);
+            sbx(['exec', '-d', opts.name, 'bash', '-c', '. ~/.cloudcli-start.sh']);
+
+            console.log(`${c.info('▶')} Forwarding port ${opts.port} → 3001...`);
+            try {
+                sbx(['ports', opts.name, '--publish', `${opts.port}:3001`]);
+            } catch (e) {
+                const msg = e.stdout || e.stderr || e.message || '';
+                if (msg.includes('address already in use')) {
+                    const altPort = opts.port + 1;
+                    console.log(`${c.warn('⚠')}  Port ${opts.port} in use, trying ${altPort}...`);
+                    try {
+                        sbx(['ports', opts.name, '--publish', `${altPort}:3001`]);
+                        opts.port = altPort;
+                    } catch {
+                        console.error(`${c.error('❌')} Ports ${opts.port} and ${altPort} both in use. Use --port to specify a free port.`);
+                        process.exit(1);
+                    }
+                } else {
+                    throw e;
+                }
+            }
+
+            console.log(`\n${c.ok('✔')} ${c.bright('CloudCLI is ready!')}`);
+            console.log(`  ${c.info('→')} ${c.bright(`http://localhost:${opts.port}`)}\n`);
+            break;
+        }
+
+        case 'create': {
+            if (!opts.workspace) {
+                console.error(`\n${c.error('❌')} Workspace path required: cloudcli sandbox <path>\n`);
+                console.log(`   Example: ${c.bright('cloudcli sandbox ~/my-project')}\n`);
+                process.exit(1);
+            }
+
+            const workspace = opts.workspace.startsWith('~')
+                ? opts.workspace.replace(/^~/, os.homedir())
+                : path.resolve(opts.workspace);
+
+            if (!fs.existsSync(workspace)) {
+                console.error(`\n${c.error('❌')} Workspace path not found: ${c.dim(workspace)}\n`);
+                process.exit(1);
+            }
+
+            const secret = SANDBOX_SECRETS[opts.agent] || 'anthropic';
+
+            // Check if the required secret is stored
+            try {
+                const secretList = sbx(['secret', 'ls']);
+                if (!secretList.includes(secret)) {
+                    console.error(`\n${c.error('❌')} No ${c.bright(secret)} API key found.\n`);
+                    console.log(`   Run: ${c.bright(`sbx secret set -g ${secret}`)}\n`);
+                    process.exit(1);
+                }
+            } catch { /* sbx secret ls not available, skip check */ }
+
+            console.log(`\n${c.bright('CloudCLI Sandbox')}`);
+            console.log(c.dim('─'.repeat(50)));
+            console.log(`  Agent:     ${c.info(opts.agent)} ${c.dim(`(${secret} credentials)`)}`);
+            console.log(`  Workspace: ${c.dim(workspace)}`);
+            console.log(`  Name:      ${c.dim(opts.name)}`);
+            console.log(`  Template:  ${c.dim(opts.template)}`);
+            console.log(`  Port:      ${c.dim(String(opts.port))}`);
+            if (opts.env.length > 0) {
+                console.log(`  Env:       ${c.dim(opts.env.join(', '))}`);
+            }
+            console.log(c.dim('─'.repeat(50)));
+
+            // Step 1: Create sandbox
+            console.log(`\n${c.info('▶')} Creating sandbox ${c.bright(opts.name)}...`);
+            try {
+                sbx(
+                    ['create', '--template', opts.template, '--name', opts.name, opts.agent, workspace],
+                    { inherit: true }
+                );
+            } catch (e) {
+                const msg = e.stdout || e.stderr || e.message || '';
+                if (msg.includes('already exists')) {
+                    console.log(`${c.warn('⚠')}  Sandbox ${c.bright(opts.name)} already exists. Starting it instead...\n`);
+                    try { sbx(['start', opts.name]); } catch { /* may already be running */ }
+                } else {
+                    throw e;
+                }
+            }
+
+            // Step 2: Inject environment variables
+            if (opts.env.length > 0) {
+                console.log(`${c.info('▶')} Setting environment variables...`);
+                const exports = opts.env
+                    .filter(e => /^\w+=.+$/.test(e))
+                    .map(e => `export ${e}`)
+                    .join('\n');
+                if (exports) {
+                    sbx(['exec', opts.name, 'bash', '-c', `echo '${exports}' >> /etc/sandbox-persistent.sh`]);
+                }
+                const invalid = opts.env.filter(e => !/^\w+=.+$/.test(e));
+                if (invalid.length > 0) {
+                    console.log(`${c.warn('⚠')}  Skipped invalid env vars: ${invalid.join(', ')} (expected KEY=VALUE)`);
+                }
+            }
+
+            // Step 3: Start CloudCLI
+            console.log(`${c.info('▶')} Launching CloudCLI web server...`);
+            try {
+                sbx(['exec', '-d', opts.name, 'bash', '-c', '. ~/.cloudcli-start.sh']);
+            } catch (e) {
+                console.error(`${c.error('❌')} Failed to start CloudCLI: ${e.message}`);
+                process.exit(1);
+            }
+
+            // Step 4: Forward port
+            console.log(`${c.info('▶')} Forwarding port ${opts.port} → 3001...`);
+            try {
+                sbx(['ports', opts.name, '--publish', `${opts.port}:3001`]);
+            } catch (e) {
+                const msg = e.stdout || e.stderr || e.message || '';
+                if (msg.includes('address already in use')) {
+                    const altPort = opts.port + 1;
+                    console.log(`${c.warn('⚠')}  Port ${opts.port} in use, trying ${altPort}...`);
+                    try {
+                        sbx(['ports', opts.name, '--publish', `${altPort}:3001`]);
+                        opts.port = altPort;
+                    } catch {
+                        console.error(`${c.error('❌')} Ports ${opts.port} and ${altPort} both in use. Use --port to specify a free port.`);
+                        process.exit(1);
+                    }
+                } else {
+                    throw e;
+                }
+            }
+
+            // Done
+            console.log(`\n${c.ok('✔')} ${c.bright('CloudCLI is ready!')}`);
+            console.log(`  ${c.info('→')} Open ${c.bright(`http://localhost:${opts.port}`)}`);
+            console.log(`\n${c.dim('  Manage with:')}`);
+            console.log(`  ${c.dim('$')} cloudcli sandbox ls`);
+            console.log(`  ${c.dim('$')} cloudcli sandbox stop ${opts.name}`);
+            console.log(`  ${c.dim('$')} cloudcli sandbox start ${opts.name}`);
+            console.log(`  ${c.dim('$')} cloudcli sandbox rm ${opts.name}\n`);
+            break;
+        }
+
+        default:
+            showSandboxHelp();
+    }
+}
+
+// ── Server ──────────────────────────────────────────────────
+
 // Start the server
 async function startServer() {
    // Check for updates silently on startup
@@ -274,6 +626,10 @@ function parseArgs(args) {
            parsed.command = 'version';
        } else if (!arg.startsWith('-')) {
            parsed.command = arg;
+            if (arg === 'sandbox') {
+                parsed.remainingArgs = args.slice(i + 1);
+                break;
+            }
        }
    }

@@ -283,7 +639,7 @@ function parseArgs(args) {
 // Main CLI handler
 async function main() {
    const args = process.argv.slice(2);
-    const { command, options } = parseArgs(args);
+    const { command, options, remainingArgs } = parseArgs(args);

    // Apply CLI options to environment variables
    if (options.serverPort) {
@@ -299,6 +655,9 @@ async function main() {
        case 'start':
            await startServer();
            break;
+        case 'sandbox':
+            await sandboxCommand(remainingArgs || []);
+            break;
        case 'status':
        case 'info':
            showStatus();