沙箱（sandbox）= 一个隔离的执行环境（通常是 Docker 容器），里面跑着 agent-server，AI 在其中敲命令、改文件。它和你的宿主机隔离——AI 在里面折腾坏了，删容器重建即可。

SandboxService（sandbox_service.py:30）抽象了沙箱的全部操作：search / get / start / resume / pause / delete。基类还实现两个通用能力：

# sandbox_service.py
async def wait_for_sandbox_running(self, ...):   # :93 轮询直到 RUNNING，可选校验 /alive
    # 避免"容器起了但 agent-server 没就绪"的竞态
async def pause_old_sandboxes(self, ...):          # :223 超上限时按创建时间暂停最老的
    # 资源回收

沙箱有两个模型，区别很重要（sandbox_models.py）：

• SandboxRecord（:33）：只有 id + owner 的持久化身份。轻量，存库。
• SandboxInfo（:48）：完整实时信息——status、session_api_key、exposed_urls（含 AGENT_SERVER/VSCODE 等命名 URL）。需要查 Docker 才能拼出。

SandboxSpecInfo（sandbox_spec_models.py:8）是"创建沙箱的模板"——类比 Docker Image 之于 Container：

class SandboxSpecInfo:
    id: str            # 镜像名
    command: str       # 启动命令
    initial_env: dict  # 初始环境变量
    working_dir: str

# 如果让你自己写（朴素版）：
def start_sandbox_naive(spec):
    c = docker.run(spec.image)      # 起个容器
    return c                        # 完事
# 问题：① 没限配额，容器越起越多把机器占满
#      ② docker.run 一返回就用，但里面 agent-server 还没就绪 → 报错
#      ③ 没身份/回调 → 沙箱产生的事件寄不回来（Day08）
#      ④ 容器里 1 号进程不回收僵尸子进程 → 进程泄漏

真实版 docker_sandbox_service.py:385 的 start_sandbox 把上面这些坑逐一补上：

# start_sandbox 概念流程
# 1. pause_old_sandboxes 先腾配额
# 2. resolve_sandbox_spec 定镜像
# 3. 生成随机 sandbox_id 和 session_api_key = base62(os.urandom(32))
# 4. 组装环境变量，注入两个关键值（见 L06）
# 5. 端口映射、CORS、volumes、KVM device
# 6. docker_client.containers.run(..., detach=True, init=True)   # init=True 用 tini 收僵尸进程
# 7. _container_to_sandbox_info 把容器映射成 SandboxInfo

第 4 步注入的"两个关键值"（docker_sandbox_service.py:418）是双进程架构的命门：

env_vars[SESSION_API_KEY_VARIABLE] = session_api_key   # 'OH_SESSION_API_KEYS_0'
env_vars[WEBHOOK_CALLBACK_VARIABLE] = (                # 'OH_WEBHOOKS_0_BASE_URL'
    f'http://host.docker.internal:{self.host_port}/api/v1/webhooks')

Agent 干活常需要密钥（比如访问私有仓库的 token、调某 API 的 key）。这些敏感密钥绝不打进镜像、也不在启动时全塞进容器，而是用时才实时下发（sandbox_router.py:157）：

# 容器内需要某密钥时，用 session key 回调 app_server 拿：
GET /sandboxes/{id}/settings/secrets/{name}
# app_server 校验 session_key 与该 sandbox 匹配（_valid_sandbox_from_session_key），才返回密钥值

✋ 动手

grep -n 'wait_for_sandbox_running\|pause_old_sandboxes' openhands/app_server/sandbox/sandbox_service.py
grep -n 'class SandboxRecord\|class SandboxInfo\|SandboxStatus' openhands/app_server/sandbox/sandbox_models.py
grep -n 'def start_sandbox\|SESSION_API_KEY_VARIABLE\|WEBHOOK_CALLBACK\|os.urandom' openhands/app_server/sandbox/docker_sandbox_service.py