From 4382d4c1990bc8a8984def638a9937f4480a4ff7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=AB=98=E7=84=B6?= <pangjiping.pjp@alibaba-inc.com>
Date: Wed, 4 Feb 2026 18:31:00 +0800
Subject: [PATCH] chore(README): install server by PyPI package

---
 README.md                           | 23 ++++++++++++++++-------
 docs/README_zh.md                   | 23 ++++++++++++++++-------
 examples/agent-sandbox/README.md    |  9 ++++-----
 examples/aio-sandbox/README.md      | 10 ++++------
 examples/chrome/README.md           |  7 +++----
 examples/claude-code/README.md      |  8 +++-----
 examples/code-interpreter/README.md | 18 +++++++-----------
 examples/codex-cli/README.md        |  8 +++-----
 examples/desktop/README.md          |  8 +++-----
 examples/gemini-cli/README.md       |  8 +++-----
 examples/google-adk/README.md       |  8 +++-----
 examples/iflow-cli/README.md        |  8 +++-----
 examples/langgraph/README.md        |  8 +++-----
 examples/playwright/README.md       |  8 +++-----
 examples/rl-training/README.md      |  8 +++-----
 examples/vscode/README.md           |  8 +++-----
 server/README.md                    | 22 +++++++++-------------
 server/README_zh.md                 | 25 ++++++++++---------------
 18 files changed, 99 insertions(+), 118 deletions(-)

diff --git a/README.md b/README.md
index 8d09a118..e118cee9 100644
--- a/README.md
+++ b/README.md
@@ -33,20 +33,29 @@ Requirements:
 - Docker (required for local execution)
 - Python 3.10+ (recommended for examples and local runtime)
 
-#### 1. Clone the Repository
+#### 1. Install and Configure the Sandbox Server
 
 ```bash
-git clone https://github.com/alibaba/OpenSandbox.git
-cd OpenSandbox
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+```
+
+> If you prefer working from source, you can still clone the repo for development, but server startup no longer requires it.
+>
+> ```bash
+> git clone https://github.com/alibaba/OpenSandbox.git
+> cd OpenSandbox/server
+> uv sync
+> cp example.config.toml ~/.sandbox.toml # Copy configuration file
+> uv run python -m src.main # Start the service
 ```
 
 #### 2. Start the Sandbox Server
 
 ```bash
-cd server
-uv sync
-cp example.config.toml ~/.sandbox.toml # Copy configuration file
-uv run python -m src.main # Start the service
+opensandbox-server
+
+# opensandbox-server -h # Show help
 ```
 
 #### 3. Create a Code Interpreter and Execute Commands
diff --git a/docs/README_zh.md b/docs/README_zh.md
index 9e6bfc42..196651f7 100644
--- a/docs/README_zh.md
+++ b/docs/README_zh.md
@@ -31,20 +31,29 @@ OpenSandbox 是一个面向 AI 应用场景设计的「通用沙箱平台」，
 - Docker（本地运行必需）
 - Python 3.10+（本地 runtime 和快速开始）
 
-#### 1. 克隆仓库
+#### 1. 安装并配置 Server
 
 ```bash
-git clone https://github.com/alibaba/OpenSandbox.git
-cd OpenSandbox
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.zh.toml
+```
+
+> 如果需要开发或使用源码编译，可通过clone仓库进行开发。
+> 
+> ```bash
+> git clone https://github.com/alibaba/OpenSandbox.git
+> cd OpenSandbox/server
+> uv sync
+> cp example.config.toml ~/.sandbox.toml # Copy configuration file
+> uv run python -m src.main # Start the service
 ```
 
 #### 2. 启动沙箱 Server
 
 ```bash
-cd server
-uv sync
-cp example.config.zh.toml ~/.sandbox.toml # 复制配置文件
-uv run python -m src.main # 启动服务
+opensandbox-server
+
+# opensandbox-server -h # Show help
 ```
 
 #### 3. 创建代码解释器，并在沙箱中执行命令
diff --git a/examples/agent-sandbox/README.md b/examples/agent-sandbox/README.md
index 8dc89002..e2f07eb1 100644
--- a/examples/agent-sandbox/README.md
+++ b/examples/agent-sandbox/README.md
@@ -11,11 +11,11 @@ executes `echo hello world` via the OpenSandbox Python SDK.
 
 ## Start OpenSandbox server
 
-1. Copy the example config and edit it for agent-sandbox:
+1. Install the server package and fetch the example config for agent-sandbox:
 
 ```shell
-cd server
-cp example.config.toml ~/.sandbox.toml
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
 ```
 
 2. Update `~/.sandbox.toml` with the following sections:
@@ -37,8 +37,7 @@ shutdown_policy = "Delete"
 3. Start the server:
 
 ```shell
-cd server
-uv sync && uv run python -m src.main
+opensandbox-server
 ```
 
 ## Run the example
diff --git a/examples/aio-sandbox/README.md b/examples/aio-sandbox/README.md
index 73d205d6..2ad54b20 100644
--- a/examples/aio-sandbox/README.md
+++ b/examples/aio-sandbox/README.md
@@ -28,13 +28,11 @@ docker pull ghcr.io/agent-infra/sandbox:latest
 Then, start the OpenSandbox server, you can obtain stdout log from terminal.
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync && uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
-> Note: `uv run python -m src.main` runs the server in the foreground and will keep the current terminal session busy.
-> Open a new terminal window/tab, `cd` into the project root (`OpenSandbox/`), then run the AIO sandbox creation steps below.
+> Note: `opensandbox-server` runs in the foreground and will keep the current terminal session busy. The example code lives in this repository—clone it and, in a new terminal window/tab, `cd` into the project root before running the AIO sandbox creation steps below.
 If you see errors like `FileNotFoundError: [Errno 2] No such file or directory` from `docker/transport/unixconn.py`, it usually means the Docker unix socket is missing / Docker daemon is not running.
 
 ## Create and Access the AIO Sandbox Instance
diff --git a/examples/chrome/README.md b/examples/chrome/README.md
index 635e8cb5..d099fa65 100644
--- a/examples/chrome/README.md
+++ b/examples/chrome/README.md
@@ -28,10 +28,9 @@ docker pull opensandbox/chrome:latest
 Start the OpenSandbox server and tail stdout from the terminal:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync && uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and access a Chrome sandbox
diff --git a/examples/claude-code/README.md b/examples/claude-code/README.md
index ac5a9797..2efb72ee 100644
--- a/examples/claude-code/README.md
+++ b/examples/claude-code/README.md
@@ -16,11 +16,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-int
 Then start the local OpenSandbox server, stdout logs will be visible in the terminal:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and Access the Claude Sandbox
diff --git a/examples/code-interpreter/README.md b/examples/code-interpreter/README.md
index 2cf77d65..e0efd638 100644
--- a/examples/code-interpreter/README.md
+++ b/examples/code-interpreter/README.md
@@ -18,11 +18,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-int
 Start the local OpenSandbox server:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and access the Code Interpreter Sandbox
@@ -149,15 +147,13 @@ spec:
 Start the k8s OpenSandbox server:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
+uv pip install opensandbox-server
 
 # replace with your k8s cluster config, kubeconfig etc.
-cp example.config.k8s.toml ~/.sandbox.toml
-cp example.batchsandbox-template.yaml ~/batchsandbox-template.yaml
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.k8s.toml
+curl -o ~/batchsandbox-template.yaml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.batchsandbox-template.yaml
 
-uv sync
-uv run python -m src.main
+opensandbox-server
 ```
 
 ## Create and access the Code Interpreter Sandbox
diff --git a/examples/codex-cli/README.md b/examples/codex-cli/README.md
index a420d7fc..58e5c753 100644
--- a/examples/codex-cli/README.md
+++ b/examples/codex-cli/README.md
@@ -16,11 +16,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-int
 Start the local OpenSandbox server, logs will be visible in the terminal:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and Access the Codex Sandbox
diff --git a/examples/desktop/README.md b/examples/desktop/README.md
index d33b1116..8cab165e 100644
--- a/examples/desktop/README.md
+++ b/examples/desktop/README.md
@@ -28,11 +28,9 @@ docker pull opensandbox/desktop:latest
 Start the local OpenSandbox server:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and Access the Desktop Sandbox
diff --git a/examples/gemini-cli/README.md b/examples/gemini-cli/README.md
index dbd7ebd4..b5819cba 100644
--- a/examples/gemini-cli/README.md
+++ b/examples/gemini-cli/README.md
@@ -16,11 +16,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-int
 Start the local OpenSandbox server, logs will be visible in the terminal:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and Access the Gemini Sandbox
diff --git a/examples/google-adk/README.md b/examples/google-adk/README.md
index 051a5ca6..7786bc60 100644
--- a/examples/google-adk/README.md
+++ b/examples/google-adk/README.md
@@ -17,11 +17,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-int
 Start the local OpenSandbox server, logs will be visible in the terminal:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Run the example
diff --git a/examples/iflow-cli/README.md b/examples/iflow-cli/README.md
index 3b1d2637..8168cf6d 100644
--- a/examples/iflow-cli/README.md
+++ b/examples/iflow-cli/README.md
@@ -16,11 +16,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-int
 Start the local OpenSandbox server, logs will be visible in the terminal:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and Access the iFlow Sandbox
diff --git a/examples/langgraph/README.md b/examples/langgraph/README.md
index ebcc7f1d..341bf400 100644
--- a/examples/langgraph/README.md
+++ b/examples/langgraph/README.md
@@ -18,11 +18,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-int
 Start the local OpenSandbox server, logs will be visible in the terminal:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Run the example
diff --git a/examples/playwright/README.md b/examples/playwright/README.md
index b28d1f91..887ba21e 100644
--- a/examples/playwright/README.md
+++ b/examples/playwright/README.md
@@ -28,11 +28,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/playwrig
 Start the local OpenSandbox server:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and Access the Playwright Sandbox
diff --git a/examples/rl-training/README.md b/examples/rl-training/README.md
index 4be05f08..1bd427b4 100644
--- a/examples/rl-training/README.md
+++ b/examples/rl-training/README.md
@@ -7,11 +7,9 @@ Demonstrates running a basic RL training loop (CartPole + DQN) inside an isolate
 Start the local OpenSandbox server:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Run the Example
diff --git a/examples/vscode/README.md b/examples/vscode/README.md
index f854377c..c7bf3742 100644
--- a/examples/vscode/README.md
+++ b/examples/vscode/README.md
@@ -27,11 +27,9 @@ docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/vscode:l
 Start the local OpenSandbox server:
 
 ```shell
-git clone git@github.com:alibaba/OpenSandbox.git
-cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync
-uv run python -m src.main
+uv pip install opensandbox-server
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
+opensandbox-server
 ```
 
 ## Create and Access the VS Code Sandbox
diff --git a/server/README.md b/server/README.md
index a37aab09..b3767202 100644
--- a/server/README.md
+++ b/server/README.md
@@ -40,15 +40,11 @@ A production-grade, FastAPI-based service for managing the lifecycle of containe
 
 ### Installation
 
-1. **Clone the repository** and navigate to the server directory:
+1. **Install from PyPI** (no repository clone required):
    ```bash
-   cd server
-   ```
-
-2. **Install dependencies** using `uv`:
-   ```bash
-   uv sync
+   uv pip install opensandbox-server
    ```
+   > For source development or contributions, you can still clone the repo and run `uv sync` inside `server/`.
 
 ### Configuration
 
@@ -56,13 +52,13 @@ The server uses a TOML configuration file to select and configure the underlying
 
 **Create configuration file**:
 ```bash
-cp example.config.toml ~/.sandbox.toml
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.toml
 ```
-**[optional] Create K8S configuration file：
+**[optional] Create K8S configuration file：**
 The K8S version of the Sandbox Operator needs to be deployed in the cluster, refer to the Kubernetes directory.
 ```bash
-cp example.config.k8s.toml ~/.sandbox.toml
-cp example.batchsandbox-template.yaml ~/batchsandbox-template.yaml
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.k8s.toml
+curl -o ~/batchsandbox-template.yaml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.batchsandbox-template.yaml
 ```
 
 **[optional] Edit `~/.sandbox.toml`** for your environment:
@@ -145,10 +141,10 @@ cp example.batchsandbox-template.yaml ~/batchsandbox-template.yaml
 
 ### Run the server
 
-Start the server using `uv`:
+Start the server using the installed CLI (reads `~/.sandbox.toml` by default):
 
 ```bash
-uv run python -m src.main
+opensandbox-server
 ```
 
 The server will start at `http://0.0.0.0:8080` (or your configured host/port).
diff --git a/server/README_zh.md b/server/README_zh.md
index 80d425b1..4ae2dbd0 100644
--- a/server/README_zh.md
+++ b/server/README_zh.md
@@ -40,17 +40,12 @@
 
 ### 安装步骤
 
-1. **克隆仓库**并进入 server 目录：
+1. **通过 PyPI 安装**（无需克隆仓库）：
 
 ```bash
-cd server
-```
-
-2. **安装依赖**（使用 `uv`）：
-
-```bash
-uv sync
+uv pip install opensandbox-server
 ```
+> 如需源码开发或贡献，可仍然克隆仓库并在 `server/` 下执行 `uv sync`。
 
 ### 配置指南
 
@@ -59,13 +54,13 @@ uv sync
 **复制配置文件**：
 
 ```bash
-cp example.config.zh.toml ~/.sandbox.toml
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.zh.toml
 ```
-**[可选] 复制K8S版本配置文件：
-需要在集群中部署 K8S版本的Sandbox Operator，参考Kubernetes目录。
+**[可选] 复制 K8S 版本配置文件：**
+需要在集群中部署 K8S 版本的 Sandbox Operator，参考 Kubernetes 目录。
 ```bash
-cp example.config.k8s.zh.toml ~/.sandbox.toml
-cp example.batchsandbox-template.yaml ~/batchsandbox-template.yaml
+curl -o ~/.sandbox.toml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.config.k8s.zh.toml
+curl -o ~/batchsandbox-template.yaml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.batchsandbox-template.yaml
 ```
 
 **[可选] 编辑 `~/.sandbox.toml`** 适配您的环境：
@@ -151,10 +146,10 @@ egress_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egre
 
 ### 启动服务
 
-使用 `uv` 启动服务：
+使用安装后的 CLI 启动（默认读取 `~/.sandbox.toml`）：
 
 ```bash
-uv run python -m src.main
+opensandbox-server
 ```
 
 服务将在 `http://0.0.0.0:8080`（或您配置的主机/端口）启动。