From 1868d116af4140ef4dc7b54d64b0487f855ceb22 Mon Sep 17 00:00:00 2001 From: Jiachen Zhang Date: Thu, 16 Jul 2026 21:30:43 +0800 Subject: [PATCH 1/2] docs: document user-specified sandbox disk quota --- .../Python SDK References/python_sdk.md | 15 +++++++++++++-- .../Python SDK References/python_sdk.md | 16 ++++++++++++++-- 2 files changed, 27 insertions(+), 4 deletions(-) diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md index c1083f29b0..8450d9eef6 100644 --- a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md @@ -34,7 +34,12 @@ async def run_sandbox(): Default admin server port is 8080. """ # Create sandbox configuration - config = SandboxConfig(image="python:3.11", memory="8g", cpus=2.0) + config = SandboxConfig( + image="python:3.11", + memory="8g", + cpus=2.0, + disk="20g", + ) # Create sandbox instance sandbox = Sandbox(config) @@ -85,9 +90,15 @@ await sandbox_group.stop() ### 2.3 配置示例 +可通过 `memory`、`cpus` 和 `disk` 指定沙箱资源。`disk` 接受 `"20g"` 这样的 +容量字符串，用于限制沙箱根文件系统和日志目录的磁盘配额。 + ```python config = SandboxConfig( image="python:3.11", + memory="8g", + cpus=2.0, + disk="20g", auto_clear_seconds=60 * 20, experiment_id="test", ) @@ -262,4 +273,4 @@ if __name__ == "__main__": - [快速开始指南](../../Getting%20Started/quickstart.md) - 了解如何快速开始使用 ROCK SDK - [API 文档](../api.md) - 查看 SDK 封装的底层 API 接口 - [配置指南](../../User%20Guides/configuration.md) - 了解 SDK 相关的配置选项 -- [安装指南](../../Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置 \ No newline at end of file +- [安装指南](../../Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置 diff --git a/docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md b/docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md index 5272d7edb6..c0f252c813 100644 --- a/docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md +++ b/docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md @@ -34,7 +34,12 @@ async def run_sandbox(): Default admin server port is 8080. """ # Create sandbox configuration - config = SandboxConfig(image="python:3.11", memory="8g", cpus=2.0) + config = SandboxConfig( + image="python:3.11", + memory="8g", + cpus=2.0, + disk="20g", + ) # Create sandbox instance sandbox = Sandbox(config) @@ -85,9 +90,16 @@ await sandbox_group.stop() ### 2.3 Configuration Example +Use `memory`, `cpus`, and `disk` to request the sandbox resources. `disk` accepts a +size string such as `"20g"` and sets the quota for both the sandbox root filesystem +and its log directory. + ```python config = SandboxConfig( image="python:3.11", + memory="8g", + cpus=2.0, + disk="20g", auto_clear_seconds=60 * 20, experiment_id="test", ) @@ -262,4 +274,4 @@ if __name__ == "__main__": - [Quick Start Guide](../../Getting%20Started/quickstart.md) - Learn how to quickly get started with the ROCK SDK - [API Documentation](../api.md) - View the underlying API interfaces encapsulated by the SDK - [Configuration Guide](../../User%20Guides/configuration.md) - Learn about SDK-related configuration options -- [Installation Guide](../../Getting%20Started/installation.md) - Detailed information about ROCK installation and setup \ No newline at end of file +- [Installation Guide](../../Getting%20Started/installation.md) - Detailed information about ROCK installation and setup From adff2678689db9c73c02e27142d1ad2ca4cd5cbd Mon Sep 17 00:00:00 2001 From: Jiachen Zhang Date: Thu, 16 Jul 2026 21:32:46 +0800 Subject: [PATCH 2/2] docs: add sandbox archive usage guide --- .../Python SDK References/python_sdk.md | 64 +++++++++++++++++- .../Python SDK References/python_sdk.md | 66 ++++++++++++++++++- 2 files changed, 128 insertions(+), 2 deletions(-) diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md index 8450d9eef6..4f491ac45b 100644 --- a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md @@ -104,7 +104,69 @@ config = SandboxConfig( ) ``` -### 2.4 沙箱加速配置 +### 2.4 归档并重启沙箱 + +当 stopped 沙箱在本地容器被清理后仍需要恢复时，可以使用 `archive()`。 +ROCK 会将容器文件系统保存为归档镜像，并将沙箱日志目录上传到远端存储。 +对 archived 沙箱调用 `restart()` 时，ROCK 会恢复这些内容并启动新容器。 + +状态流转如下： + +```text +running --stop--> stopped --archive--> archiving --success--> archived + | + +--restart--> pending --alive--> running + +archiving --failure/timeout--> stopped +pending（恢复中）--failure/timeout--> archived +``` + +`archive()` 只负责发起异步归档任务。只有当 +`get_status(include_all_states=True)` 返回 `state == "archived"` 时， +才表示远端归档已完成，可用于恢复。 + +```python +import asyncio + + +async def wait_until_archived(sandbox, timeout=1800): + deadline = asyncio.get_running_loop().time() + timeout + while True: + status = await sandbox.get_status(include_all_states=True) + if status.state == "archived": + return + if status.state == "stopped": + raise RuntimeError("归档失败或超时，可以重试") + if asyncio.get_running_loop().time() >= deadline: + raise TimeoutError(f"等待归档超时，当前状态: {status.state}") + await asyncio.sleep(3) + + +# 运行此示例前，sandbox 应处于 running 状态。 +await sandbox.arun("echo 'keep me' > /tmp/archive-marker.txt") +await sandbox.stop() + +# archive() 只能对 stopped 沙箱调用。 +await sandbox.archive() +await wait_until_archived(sandbox) + +# restart() 会识别 archived 状态并自动恢复沙箱。 +await sandbox.restart() +result = await sandbox.arun("cat /tmp/archive-marker.txt") +assert "keep me" in result.output +``` + +如果要在另一个进程中恢复，请使用相同的服务地址、集群和认证信息创建 +`Sandbox`，先调用 `await sandbox.attach(sandbox_id)`，再调用 +`await sandbox.restart()`。应将 `startup_timeout` 设置得足够长，以覆盖归档恢复、 +镜像拉取和容器启动的耗时。 + +:::warning +ROCK Admin 服务必须已启用并配置归档存储。仍需要归档时请勿调用 `delete()`： +归档存储已配置时，删除 archived 沙箱也会删除对应的归档内容。 +::: + +### 2.5 沙箱加速配置 ROCK 提供沙箱网络加速功能，支持配置 APT、PIP 和 GitHub 镜像源，提升受限网络环境下的包下载速度。 diff --git a/docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md b/docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md index c0f252c813..38a80f1931 100644 --- a/docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md +++ b/docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md @@ -105,7 +105,71 @@ config = SandboxConfig( ) ``` -### 2.4 Sandbox Speedup Configuration +### 2.4 Archive and Restart a Sandbox + +Use `archive()` when a stopped sandbox must remain recoverable after its local +container is removed. ROCK saves the container filesystem as an archive image and +uploads the sandbox log directory to remote storage. Calling `restart()` on the +archived sandbox restores that content and starts a new container. + +The lifecycle is: + +```text +running --stop--> stopped --archive--> archiving --success--> archived + | + +--restart--> pending --alive--> running + +archiving --failure/timeout--> stopped +pending (during restore) --failure/timeout--> archived +``` + +`archive()` only starts the asynchronous archive task. The archive is ready for +remote recovery only after `get_status(include_all_states=True)` returns +`state == "archived"`. + +```python +import asyncio + + +async def wait_until_archived(sandbox, timeout=1800): + deadline = asyncio.get_running_loop().time() + timeout + while True: + status = await sandbox.get_status(include_all_states=True) + if status.state == "archived": + return + if status.state == "stopped": + raise RuntimeError("Archive failed or timed out; it can be retried") + if asyncio.get_running_loop().time() >= deadline: + raise TimeoutError(f"Timed out waiting for archive; current state: {status.state}") + await asyncio.sleep(3) + + +# The sandbox must be running before this example starts. +await sandbox.arun("echo 'keep me' > /tmp/archive-marker.txt") +await sandbox.stop() + +# archive() is only valid for a stopped sandbox. +await sandbox.archive() +await wait_until_archived(sandbox) + +# restart() detects the archived state and restores the sandbox automatically. +await sandbox.restart() +result = await sandbox.arun("cat /tmp/archive-marker.txt") +assert "keep me" in result.output +``` + +To restore in another process, create a `Sandbox` with the same endpoint, cluster, +and credentials, call `await sandbox.attach(sandbox_id)`, and then call +`await sandbox.restart()`. Set `startup_timeout` high enough to cover image restore, +pull, and startup time. + +:::warning +The ROCK Admin service must enable and configure archive storage. Do not call +`delete()` while the archive is still needed: deleting an archived sandbox also +removes its archive artifacts when archive storage is configured. +::: + +### 2.5 Sandbox Speedup Configuration ROCK provides sandbox network acceleration capabilities, supporting configuration of APT, PIP, and GitHub mirror sources to improve package download speeds in restricted network environments.