feat(docker): add sandbox docker-compose files for enhanced host isolation

Add docker-compose-sandbox.yml and docker-compose-sandbox.full.yml with security hardening: read-only filesystem, capability dropping, resource limits (2 GB RAM, 2 CPUs, 500 PIDs), and dedicated bridge network. Update documentation in all 6 languages (en, pt-br, fr, ja, vi, zh).
2026-03-18 15:09:20 -03:00 · 2026-03-18 15:09:20 -03:00 · 4259aa4f19
commit 4259aa4f19
parent e73d9d959e
8 changed files with 454 additions and 0 deletions
--- a/docker/docker-compose-sandbox.full.yml
+++ b/docker/docker-compose-sandbox.full.yml
@ -0,0 +1,76 @@
+services:
+  # ─────────────────────────────────────────────
+  # PicoClaw Agent (one-shot query) - Full MCP Support - Sandboxed
+  #   docker compose -f docker/docker-compose-sandbox.full.yml run --rm picoclaw-agent -m "Hello"
+  # ─────────────────────────────────────────────
+  picoclaw-agent:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.full
+    container_name: picoclaw-agent-full-sandbox
+    profiles:
+      - agent
+    volumes:
+      - ../config/config.json:/root/.picoclaw/config.json:ro
+      - picoclaw-workspace:/root/.picoclaw/workspace
+      - picoclaw-npm-cache:/root/.npm # npm cache for faster MCP server installs
+    entrypoint: ["picoclaw", "agent"]
+    stdin_open: true
+    tty: true
+    # ── Sandbox ──
+    read_only: true
+    tmpfs:
+      - /tmp:size=100M
+      - /run:size=10M
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    mem_limit: 2g
+    cpus: 2
+    pids_limit: 500
+    networks:
+      - picoclaw-net
+
+  # ─────────────────────────────────────────────
+  # PicoClaw Gateway (Long-running Bot) - Full MCP Support - Sandboxed
+  #   docker compose -f docker/docker-compose-sandbox.full.yml --profile gateway up
+  # ─────────────────────────────────────────────
+  picoclaw-gateway:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.full
+    container_name: picoclaw-gateway-full-sandbox
+    restart: unless-stopped
+    profiles:
+      - gateway
+    volumes:
+      # Configuration file
+      - ../config/config.json:/root/.picoclaw/config.json:ro
+      # Persistent workspace (sessions, memory, logs)
+      - picoclaw-workspace:/root/.picoclaw/workspace
+      # NPM cache for faster MCP server installs
+      - picoclaw-npm-cache:/root/.npm
+    command: ["gateway"]
+    # ── Sandbox ──
+    read_only: true
+    tmpfs:
+      - /tmp:size=100M
+      - /run:size=10M
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    mem_limit: 2g
+    cpus: 2
+    pids_limit: 500
+    networks:
+      - picoclaw-net
+
+volumes:
+  picoclaw-workspace:
+  picoclaw-npm-cache: # Cache npm packages to speed up MCP server installations
+
+networks:
+  picoclaw-net:
+    driver: bridge
--- a/docker/docker-compose-sandbox.yml
+++ b/docker/docker-compose-sandbox.yml
@ -0,0 +1,96 @@
+services:
+  # ─────────────────────────────────────────────
+  # PicoClaw Agent (one-shot query) - Sandboxed
+  #   docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent -m "Hello"
+  # ─────────────────────────────────────────────
+  picoclaw-agent:
+    image: docker.io/sipeed/picoclaw:latest
+    container_name: picoclaw-agent-sandbox
+    profiles:
+      - agent
+    #extra_hosts:
+    #  - "host.docker.internal:host-gateway"
+    volumes:
+      - ./data:/root/.picoclaw
+    entrypoint: ["picoclaw", "agent"]
+    stdin_open: true
+    tty: true
+    # ── Sandbox ──
+    read_only: true
+    tmpfs:
+      - /tmp:size=100M
+      - /run:size=10M
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    mem_limit: 2g
+    cpus: 2
+    pids_limit: 500
+    networks:
+      - picoclaw-net
+
+  # ─────────────────────────────────────────────
+  # PicoClaw Gateway (Long-running Bot) - Sandboxed
+  #   docker compose -f docker/docker-compose-sandbox.yml --profile gateway up
+  # ─────────────────────────────────────────────
+  picoclaw-gateway:
+    image: docker.io/sipeed/picoclaw:latest
+    container_name: picoclaw-gateway-sandbox
+    restart: on-failure
+    profiles:
+      - gateway
+    #extra_hosts:
+    #  - "host.docker.internal:host-gateway"
+    volumes:
+      - ./data:/root/.picoclaw
+    # ── Sandbox ──
+    read_only: true
+    tmpfs:
+      - /tmp:size=100M
+      - /run:size=10M
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    mem_limit: 2g
+    cpus: 2
+    pids_limit: 500
+    networks:
+      - picoclaw-net
+
+  # ─────────────────────────────────────────────
+  # PicoClaw Launcher (Web Console + Gateway) - Sandboxed
+  #   docker compose -f docker/docker-compose-sandbox.yml --profile launcher up
+  # ─────────────────────────────────────────────
+  picoclaw-launcher:
+    image: docker.io/sipeed/picoclaw:launcher
+    container_name: picoclaw-launcher-sandbox
+    restart: on-failure
+    profiles:
+      - launcher
+    environment:
+      - PICOCLAW_GATEWAY_HOST=0.0.0.0
+    ports:
+      - "127.0.0.1:18800:18800"
+      - "127.0.0.1:18790:18790"
+    volumes:
+      - ./data:/root/.picoclaw
+    # ── Sandbox ──
+    read_only: true
+    tmpfs:
+      - /tmp:size=100M
+      - /run:size=10M
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    mem_limit: 2g
+    cpus: 2
+    pids_limit: 500
+    networks:
+      - picoclaw-net
+
+networks:
+  picoclaw-net:
+    driver: bridge
--- a/docs/docker.md
+++ b/docs/docker.md
@ -63,6 +63,53 @@ docker compose -f docker/docker-compose.yml pull
 docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```

+## 🐳 Docker Compose - Sandbox
+
+You can run PicoClaw in a sandboxed Docker environment for enhanced host isolation. The sandbox compose files add security hardening: read-only filesystem, capability dropping, resource limits (2 GB RAM, 2 CPUs, 500 PIDs), and a dedicated network.
+
+```bash
+# 1. First run — auto-generates docker/data/config.json then exits
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up
+# The container prints "First-run setup complete." and stops.
+
+# 2. Set your API keys
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 3. Start
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
+```bash
+# 4. Check logs
+docker compose -f docker/docker-compose-sandbox.yml logs -f picoclaw-gateway
+
+# 5. Stop
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway down
+```
+
+### Launcher Mode (Web Console)
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml --profile launcher up -d
+```
+
+### Agent Mode (One-shot)
+
+```bash
+# Ask a question
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Interactive mode
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent
+```
+
+### Update
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml pull
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
 ### 🚀 Quick Start

 > [!TIP]
--- a/docs/fr/docker.md
+++ b/docs/fr/docker.md
@ -63,6 +63,53 @@ docker compose -f docker/docker-compose.yml pull
 docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```

+## 🐳 Docker Compose - Sandbox
+
+Vous pouvez exécuter PicoClaw dans un environnement Docker sandboxé pour une meilleure isolation de l'hôte. Les fichiers compose sandbox ajoutent des protections de sécurité : système de fichiers en lecture seule, suppression des capabilities, limites de ressources (2 Go RAM, 2 CPUs, 500 PIDs) et un réseau dédié.
+
+```bash
+# 1. Premier lancement — génère automatiquement docker/data/config.json puis s'arrête
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up
+# Le conteneur affiche "First-run setup complete." et s'arrête.
+
+# 2. Configurer vos clés API
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 3. Démarrer
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
+```bash
+# 4. Vérifier les logs
+docker compose -f docker/docker-compose-sandbox.yml logs -f picoclaw-gateway
+
+# 5. Arrêter
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway down
+```
+
+### Mode Launcher (Console Web)
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml --profile launcher up -d
+```
+
+### Mode Agent (One-shot)
+
+```bash
+# Poser une question
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Mode interactif
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent
+```
+
+### Mise à jour
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml pull
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
 ### 🚀 Démarrage Rapide

 > [!TIP]
--- a/docs/ja/docker.md
+++ b/docs/ja/docker.md
@ -63,6 +63,53 @@ docker compose -f docker/docker-compose.yml pull
 docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```

+## 🐳 Docker Compose - Sandbox
+
+ホストとの分離を強化するため、サンドボックス化された Docker 環境で PicoClaw を実行できます。サンドボックス compose ファイルは、読み取り専用ファイルシステム、capability の削除、リソース制限（2 GB RAM、2 CPU、500 PID）、専用ネットワークなどのセキュリティ強化を追加します。
+
+```bash
+# 1. 初回実行 — docker/data/config.json を自動生成して終了
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up
+# コンテナが "First-run setup complete." と表示して停止します
+
+# 2. API Key を設定
+vim docker/data/config.json   # provider API key、Bot Token などを設定
+
+# 3. 起動
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
+```bash
+# 4. ログを確認
+docker compose -f docker/docker-compose-sandbox.yml logs -f picoclaw-gateway
+
+# 5. 停止
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway down
+```
+
+### Launcher モード (Web コンソール)
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml --profile launcher up -d
+```
+
+### Agent モード (ワンショット)
+
+```bash
+# 質問する
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent -m "2+2は？"
+
+# インタラクティブモード
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent
+```
+
+### イメージの更新
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml pull
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
 ---

 ## 🚀 クイックスタート
--- a/docs/pt-br/docker.md
+++ b/docs/pt-br/docker.md
@ -63,6 +63,53 @@ docker compose -f docker/docker-compose.yml pull
 docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```

+## 🐳 Docker Compose - Sandbox
+
+Você pode executar o PicoClaw em um ambiente Docker com sandbox para maior isolamento do host. Os arquivos compose sandbox adicionam proteções de segurança: filesystem somente leitura, remoção de capabilities, limites de recursos (2 GB RAM, 2 CPUs, 500 PIDs) e uma rede dedicada.
+
+```bash
+# 1. Primeira execução — gera automaticamente docker/data/config.json e encerra
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up
+# O contêiner exibe "First-run setup complete." e para.
+
+# 2. Configure suas chaves de API
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 3. Iniciar
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
+```bash
+# 4. Verificar logs
+docker compose -f docker/docker-compose-sandbox.yml logs -f picoclaw-gateway
+
+# 5. Parar
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway down
+```
+
+### Modo Launcher (Console Web)
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml --profile launcher up -d
+```
+
+### Modo Agent (One-shot)
+
+```bash
+# Fazer uma pergunta
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Modo interativo
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent
+```
+
+### Atualização
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml pull
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
 ### 🚀 Início Rápido

 > [!TIP]
--- a/docs/vi/docker.md
+++ b/docs/vi/docker.md
@ -63,6 +63,53 @@ docker compose -f docker/docker-compose.yml pull
 docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```

+## 🐳 Docker Compose - Sandbox
+
+Bạn có thể chạy PicoClaw trong môi trường Docker sandbox để tăng cường cách ly với host. Các file compose sandbox bổ sung các biện pháp bảo mật: filesystem chỉ đọc, loại bỏ capability, giới hạn tài nguyên (2 GB RAM, 2 CPU, 500 PID) và mạng chuyên dụng.
+
+```bash
+# 1. Lần chạy đầu tiên — tự động tạo docker/data/config.json rồi thoát
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up
+# Container hiển thị "First-run setup complete." và dừng lại.
+
+# 2. Cấu hình API key của bạn
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 3. Khởi động
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
+```bash
+# 4. Kiểm tra log
+docker compose -f docker/docker-compose-sandbox.yml logs -f picoclaw-gateway
+
+# 5. Dừng
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway down
+```
+
+### Chế Độ Launcher (Web Console)
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml --profile launcher up -d
+```
+
+### Chế Độ Agent (One-shot)
+
+```bash
+# Đặt câu hỏi
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Chế độ tương tác
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent
+```
+
+### Cập Nhật
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml pull
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
 ### 🚀 Bắt Đầu Nhanh

 > [!TIP]
--- a/docs/zh/docker.md
+++ b/docs/zh/docker.md
@ -63,6 +63,53 @@ docker compose -f docker/docker-compose.yml pull
 docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```

+## 🐳 Docker Compose - Sandbox
+
+您可以在沙箱化的 Docker 环境中运行 PicoClaw，以增强与宿主机的隔离。沙箱 compose 文件增加了安全加固：只读文件系统、移除 capabilities、资源限制（2 GB 内存、2 CPU、500 PID）和专用网络。
+
+```bash
+# 1. 首次运行 — 自动生成 docker/data/config.json 后退出
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up
+# 容器打印 "First-run setup complete." 后自动停止
+
+# 2. 填写 API Key 等配置
+vim docker/data/config.json   # 设置 provider API key、Bot Token 等
+
+# 3. 正式启动
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
+```bash
+# 4. 查看日志
+docker compose -f docker/docker-compose-sandbox.yml logs -f picoclaw-gateway
+
+# 5. 停止
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway down
+```
+
+### Launcher 模式 (Web 控制台)
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml --profile launcher up -d
+```
+
+### Agent 模式 (一次性运行)
+
+```bash
+# 提问
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent -m "2+2 等于几？"
+
+# 交互模式
+docker compose -f docker/docker-compose-sandbox.yml run --rm picoclaw-agent
+```
+
+### 更新镜像
+
+```bash
+docker compose -f docker/docker-compose-sandbox.yml pull
+docker compose -f docker/docker-compose-sandbox.yml --profile gateway up -d
+```
+
 ---

 ## 🚀 快速开始