Docker Sandboxes

定时任务会在指定时间无人值守地运行智能体任务，无需让你的机器保持在线。每次运行都会 根据已保存的 kit 和配置创建一个全新的云沙箱。任务结束或存活时间（TTL）到期时，沙箱 即被删除，以先发生者为准。请指示任务在退出之前把结果保存到外部目标。

定时任务适用于依赖项审查、issue 摘要这类周期性的工作。对于由 CI 系统触发的作业， 请参阅 CI 与无头使用。对于从文件配置的交互式会话，请 参阅云端环境文件。要在 Web 界面中管理定时任务，请参阅 Docker Agentic Platform 中的定时任务。

创建定时任务 ​

定时任务需要云端访问权限、账号的定时任务权限，以及提供 sbx --cloud schedule --help 的 CLI。用 sbx login 登录，以授权无人值守的运行。 关于凭据有效期和登录要求，请参阅更新定时任务凭据。

选择某个已发布的 kit，例如 claude，或一个 oci:// 引用。不支持本地 kit 路径和 git+ 引用。该 kit 必须包含任务所需的工具，并且能够在没有交互输入的情况下接受一段 提示词或命令。

为智能体及其使用的服务配置云凭据。例如，一个 issue 摘要任务需要 一个 Anthropic API 密钥，以及一个拥有读取 issue 和发表评论权限的 GitHub 令牌：

console
$ sbx --cloud secret set anthropic
$ sbx --cloud secret set github

下面的定时任务每周把摘要发布到一个 GitHub 跟踪 issue 上，因此它的输出能在沙箱删除后 依然保留。请把仓库和 issue 占位符替换为你能控制的目标。--enabled=false 会在你 测试任务之前，让周期性运行保持暂停。

console
$ sbx --cloud schedule create claude \
    --name weekly-issue-summary \
    --cron '0 9 * * 1' \
    --timezone Etc/UTC \
    --enabled=false \
    --max-run-duration 1h \
    --workdir /home/agent \
    --env REPOSITORY=<OWNER>/<REPOSITORY> \
    --env TRACKING_ISSUE=<ISSUE_NUMBER> \
    --allow-network api.github.com:443 \
    --prompt 'Use the GitHub REST API to summarize up to ten open issues in REPOSITORY, excluding pull requests and TRACKING_ISSUE. Post their titles and links as one comment on TRACKING_ISSUE. Skip duplicate summaries. Stop on API errors. Do not modify code or other issues, or ask for input.'

请保存返回的定时任务 ID。这些命令接受的是 ID，而不是定时任务名称。请在用于智能体 任务的 --prompt 和用于 shell 命令的 --command 之间恰好选择一个。

设置执行频率 ​

--cron 接受一个带引号的五段表达式：分钟、小时、日、月和星期几。例如， '0 9 * * 1' 表示每周一 09:00 运行。请显式设置 --timezone 为某个 IANA 时区， 例如 Etc/UTC。

配置每次运行 ​

设置行为
--max-run-duration运行时长上限，至少为 1h。默认为 1h。请用它代替 --ttl。
--cpus、--memory覆盖 kit 的资源默认值。
--workdir、-w任务在沙箱中运行所在的目录。--working-dir 是它的别名。该目录必须已存在。这不会上传宿主机项目。
--env KEY=VALUE设置任务参数。不接受只写 --env KEY 的形式。请把凭据存放在密钥存储中。
--allow-network声明任务所需的目标地址。请参阅云端网络策略并测试服务访问。

每次运行都不会带上你的宿主机工作区。请让任务从外部服务获取它的输入。不要假设本地 网络策略会应用到定时沙箱上，也不要认为只配置了一条规则就能证明其已被强制执行。

测试定时任务 ​

排队一次手动运行，即使周期性运行正处于暂停状态也可以：

console
$ sbx --cloud schedule run <SCHEDULE_ID>
$ sbx --cloud schedule runs <SCHEDULE_ID>
$ sbx --cloud schedule runs inspect <SCHEDULE_ID> <RUN_ID>

使用 run 或 runs 返回的运行 ID。检查会显示状态、失败原因、可用的退出码以及耗时。 排队一次运行并不能确保成功：请等待其完成，并检查外部结果，例如跟踪 issue 上的评论。

如果另一次运行正在进行，服务会把这次额外的运行作为重叠运行取消。请等待正在进行的 运行结束后再重试。

列出和检查定时任务 ​

列出定时任务，并检查它们的频率、状态、kit 和下次运行时间：

console
$ sbx --cloud schedule ls
$ sbx --cloud schedule inspect <SCHEDULE_ID>

启用或暂停定时运行 ​

在验证过一次测试运行之后，启用定时任务：

console
$ sbx --cloud schedule update <SCHEDULE_ID> --enabled=true

用 --enabled=false 暂停周期性运行：

console
$ sbx --cloud schedule update <SCHEDULE_ID> --enabled=false

修改定时任务设置 ​

修改 --name、--description、--cron、--timezone 或 --enabled 会保留已保存的 运行配置。例如，把每周的运行时间改到 UTC 10:00：

console
$ sbx --cloud schedule update <SCHEDULE_ID> --cron '0 10 * * 1' --timezone Etc/UTC

替换任务或运行配置 ​

如果你传入 kit 参数，或者修改某项运行设置（例如提示词、时长、环境变量或工作目录）， schedule update 会替换未来运行所使用的已保存配置。它不会把这些改动与已保存的运行 设置合并。请重复写出 --prompt 或 --command，以及你想保留的每一项运行设置，即使 你只改动其中一个值。只包含 --name、--description、--cron、--timezone 或 --enabled 的更新会保留已保存的运行配置。

省略的运行设置会被重置，包括网络规则、时长、资源、平台、环境变量、工作目录和 --static-mcp 服务器选择。

例如，下面的命令会替换任务并设置两小时的时长上限。它同时会重置此前配置过的环境变量、 网络规则以及其他被省略的运行设置：

console
$ sbx --cloud schedule update <SCHEDULE_ID> claude \
    --max-run-duration 2h \
    --prompt 'Check the installed tool versions and report them. Do not ask for input.'

如果想在修改时长的同时保留 issue 摘要任务，请复制它完整的 create 命令，把 create claude 换成 update <SCHEDULE_ID> claude，并把 --max-run-duration 改为 2h。请保留提示词和其余每个运行标志。CLI 会对重置发出警告，但不会保留被省略的 设置。请在替换配置之前先暂停周期性运行，恢复之前先做测试。

定时任务会保存已解析的 kit 和所选的账号密钥名称。请通过替换运行配置来获取已发布的 kit 变更或新增的凭据。如果不传入 kit 参数，替换操作会重新解析现有的 kit 引用。只 修改定时任务设置不会刷新 kit 或密钥。

CLI 拒绝替换那些保存了多个 kit、策略 ID 或沙箱环境的运行配置，因为它的标志无法保留 这些设置。请改用定时任务 API 来更新这类配置。你仍然可以用 CLI 修改它们的名称、 描述、频率、时区和启用状态。

更新定时任务凭据 ​

当你的账号启用了定时任务功能时，交互式 sbx login 会登记一个定时任务凭据。该凭据 在 90 天后到期。请再次交互式登录来续期。使用 --password-stdin 的 PAT 登录不会 登记该凭据。

登录成功仍可能报告 schedule credential exchange failed。请处理该警告，并在依赖 定时任务之前测试一次运行。

从失败的运行中恢复 ​

检查该次运行的失败原因和退出码，并检查外部结果。如果 Docker 凭据已过期，请再次运行 sbx login。如果出现身份验证或连接失败，请检查智能体凭据和服务访问权限。如果你 添加了密钥或更改了 kit，请替换运行配置并 带上所有必需设置。恢复周期性运行之前，请重新测试。

删除定时任务 ​

console
$ sbx --cloud schedule rm <SCHEDULE_ID>

删除操作会请求确认。--force 会跳过提示。删除定时任务会阻止后续运行，但不会立即 删除正在运行中的那次运行的沙箱。该沙箱可能会保留到它的超时时间为止。