From 6cfce64f996fe9ef474d4667fb1f787a3d45a59f Mon Sep 17 00:00:00 2001
From: HuaQiu6659 <huaqiu6659@example.com>
Date: Tue, 7 Apr 2026 03:32:28 +0000
Subject: [PATCH] feat: add docker deployment support

---
 .dockerignore      | 18 ++++++++++++
 DOCKER.md          | 73 ++++++++++++++++++++++++++++++++++++++++++++++
 Dockerfile         | 38 ++++++++++++++++++++++++
 README.md          | 22 ++++++++++++++
 README_CN.md       | 22 ++++++++++++++
 docker-compose.yml | 22 ++++++++++++++
 6 files changed, 195 insertions(+)
 create mode 100644 .dockerignore
 create mode 100644 DOCKER.md
 create mode 100644 Dockerfile
 create mode 100644 docker-compose.yml

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..cb76a9c
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,18 @@
+.git
+.github
+node_modules/
+frontend/node_modules/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+.env
+.openspace/
+frontend/dist/
+showcase/
+gdpval_bench/
+assets/
diff --git a/DOCKER.md b/DOCKER.md
new file mode 100644
index 0000000..5711398
--- /dev/null
+++ b/DOCKER.md
@@ -0,0 +1,73 @@
+# Docker Deployment for OpenSpace
+
+This guide provides instructions on how to run OpenSpace in a Docker container. Containerization ensures a consistent environment, making it easy to run the dashboard and backend API without dealing with local Python and Node.js dependencies.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/)
+- [Docker Compose](https://docs.docker.com/compose/install/)
+
+## Quick Start (Docker Compose)
+
+The easiest way to get OpenSpace running is using `docker-compose`.
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/HKUDS/OpenSpace.git
+   cd OpenSpace
+   ```
+
+2. **Configure Environment Variables:**
+
+   Create a `.env` file in the root directory and add your API keys:
+
+   ```bash
+   cp .env.example .env
+   # Edit .env with your favorite editor and set your API keys:
+   # OPENSPACE_API_KEY=your_key
+   # OPENAI_API_KEY=your_key
+   # ANTHROPIC_API_KEY=your_key
+   ```
+
+3. **Build and Run:**
+
+   ```bash
+   docker-compose up -d --build
+   ```
+
+4. **Access the Dashboard:**
+
+   Open your browser and navigate to [http://localhost:7788](http://localhost:7788). The frontend and backend are both served seamlessly from the same container.
+
+## Interacting with the CLI
+
+You can use the container to execute OpenSpace CLI commands.
+
+**To run a single task using the CLI inside the running container:**
+
+```bash
+docker exec -it openspace openspace --model "anthropic/claude-sonnet-4-5" --query "Analyze the local skills"
+```
+
+**To download/upload skills:**
+
+```bash
+docker exec -it openspace openspace-download-skill <skill_id>
+docker exec -it openspace openspace-upload-skill /app/skills/my-skill
+```
+
+## Volumes
+
+The `docker-compose.yml` is configured with two persistent volumes:
+
+- `openspace-data`: Mounted to `/app/.openspace`, storing the SQLite database (`openspace.db`) containing the skill evolution history and metadata.
+- `openspace-skills`: Mounted to `/app/skills`, allowing you to persist downloaded and custom skills across container restarts.
+
+If you prefer to mount a local directory for your skills so you can edit them directly from your host machine, you can update the `docker-compose.yml` file:
+
+```yaml
+    volumes:
+      - openspace-data:/app/.openspace
+      - ./my-local-skills:/app/skills
+```
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..efc952d
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,38 @@
+# Stage 1: Build the frontend
+FROM node:20-slim AS frontend-builder
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm install
+COPY frontend/ ./
+RUN npm run build
+
+# Stage 2: Build the backend and serve
+FROM python:3.12-slim
+WORKDIR /app
+
+# Install system dependencies required for python packages and GUI features
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    python3-dev \
+    libx11-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy backend source
+COPY . /app/
+
+# Install the Python package with linux optional dependencies
+RUN pip install --no-cache-dir -e .[linux]
+
+# Copy built frontend from Stage 1
+COPY --from=frontend-builder /app/frontend/dist /app/frontend/dist
+
+# Expose the dashboard port
+EXPOSE 7788
+
+# Set environment variables
+ENV HOST=0.0.0.0
+ENV PORT=7788
+ENV OPENSPACE_WORKSPACE=/app
+
+# Run the dashboard server by default
+CMD ["openspace-dashboard", "--host", "0.0.0.0", "--port", "7788"]
diff --git a/README.md b/README.md
index 871298d..f27bbf2 100644
--- a/README.md
+++ b/README.md
@@ -135,6 +135,7 @@ On 50 professional tasks (**📈 [GDPVal Economic Benchmark](#-benchmark-gdpval)
   - [🤖 Path A: For Your Agent](#-path-a-for-your-agent)
   - [👤 Path B: As Your Co-Worker](#-path-b-as-your-co-worker)
   - [📊 Local Dashboard](#-local-dashboard)
+- [🐳 Docker Deployment](#-docker-deployment)
 - [📈 Benchmark: GDPVal](#-benchmark-gdpval)
 - [📊 Showcase: My Daily Monitor](#-showcase-my-daily-monitor)
 - [🏗️ Framework](#️-framework)
@@ -294,6 +295,27 @@ npm run dev
 
 ---
 
+### 🐳 Docker Deployment
+
+To deploy OpenSpace without worrying about local Python and Node.js dependencies, you can use the official Docker image. We provide a `docker-compose.yml` for an easy, single-command setup.
+
+```bash
+# Clone the repository
+git clone https://github.com/HKUDS/OpenSpace.git
+cd OpenSpace
+
+# Setup your API keys
+cp .env.example .env
+# Edit .env with your LLM API keys
+
+# Start the container
+docker-compose up -d --build
+```
+
+The OpenSpace Dashboard is now available at [http://localhost:7788](http://localhost:7788).
+
+For detailed CLI and volume configurations, check out the [Docker Deployment Guide (DOCKER.md)](./DOCKER.md).
+
 ## 📈 Benchmark: GDPVal
 
 We evaluate OpenSpace on [GDPVal](https://huggingface.co/datasets/openai/gdpval) — 220 real-world professional tasks spanning 44 occupations — using the [ClawWork](https://github.com/HKUDS/ClawWork) evaluation protocol with identical productivity tools and LLM-based scoring. Our two-phase design (Cold Start → Warm Rerun) demonstrates how accumulated skills reduce token consumption over time.
diff --git a/README_CN.md b/README_CN.md
index 09aee71..9a08945 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -135,6 +135,7 @@ Skill 能够自动学习并持续提升
   - [🤖 路径 A：为你的 Agent 接入](#-路径-a为你的-agent-接入)
   - [👤 路径 B：作为你的 AI 协作者](#-路径-b作为你的-ai-协作者)
   - [📊 本地仪表盘](#-本地仪表盘)
+- [🐳 Docker 容器化部署](#-docker-部署)
 - [📈 基准测试：GDPVal](#-基准测试gdpval)
 - [📊 案例展示：My Daily Monitor](#-案例展示my-daily-monitor)
 - [🏗️ 框架](#️-框架)
@@ -294,6 +295,27 @@ npm run dev
 
 ---
 
+### 🐳 Docker 容器化部署
+
+为了避免配置本地 Python 和 Node.js 环境，你可以使用 Docker 容器化运行 OpenSpace。我们提供了一个 `docker-compose.yml` 用于一键部署。
+
+```bash
+# 克隆仓库
+git clone https://github.com/HKUDS/OpenSpace.git
+cd OpenSpace
+
+# 配置环境变量
+cp .env.example .env
+# 编辑 .env 文件，填入你的 API 密钥
+
+# 启动容器
+docker-compose up -d --build
+```
+
+启动完成后，你可以通过浏览器访问 [http://localhost:7788](http://localhost:7788) 打开 OpenSpace Dashboard。
+
+如果需要执行命令行操作或者配置数据卷持久化，请参阅详细的 [Docker 部署指南 (DOCKER.md)](./DOCKER.md)。
+
 ## 📈 基准测试：GDPVal
 
 我们在 [GDPVal](https://huggingface.co/datasets/openai/gdpval) 上评估 OpenSpace——该数据集包含 220 项真实世界的专业任务，涵盖 44 个职业——采用 [ClawWork](https://github.com/HKUDS/ClawWork) 评测协议，使用相同的生产力工具和基于 LLM 的评分方式。我们的两阶段设计（Cold Start → Warm Rerun）展示了积累的 Skill 如何随时间降低 Token 消耗。
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..899919a
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,22 @@
+version: '3.8'
+
+services:
+  openspace:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: openspace
+    ports:
+      - "7788:7788"
+    volumes:
+      - openspace-data:/app/.openspace
+      - openspace-skills:/app/skills
+    environment:
+      - OPENSPACE_API_KEY=${OPENSPACE_API_KEY:-}
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+    restart: unless-stopped
+
+volumes:
+  openspace-data:
+  openspace-skills: