> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 长时间运行

默认情况下,Sandbox 的 `timeout` 最长生效 **1 小时**——传入更大的值会被截断到该上限。长时间运行(long-running)模式可以解除这一上限:启用后,创建 Sandbox 时传入的 `timeout` 可以超过 1 小时。这适用于需要远超常规会话时长保持存活的工作负载,例如常驻服务、长时间运行的 agent 任务或后台作业。

长时间运行模式通过创建 Sandbox 时的 `metadata` 字段进行配置。键为 `long_running`,值为字符串形式的 `"true"`。

<Note>
  `long_running` 与 `timeout` **配合使用**:请把 timeout 设置为你实际需要的时长——启用 `long_running` 后,它可以超过默认的 1 小时上限。未启用 `long_running` 时,`timeout` 最长生效 1 小时。**如果未设置 `timeout`,默认值为 5 分钟。**
</Note>

<Warning>
  长时间运行模式不会禁用[空闲超时](/docs/sandbox/sandbox-idle-timeout):如果你设置了空闲超时,它仍然生效,不活跃的 Sandbox 会据此被暂停或终止。
</Warning>

## 基本用法

创建 Sandbox 时,在 `metadata` 对象中传入 `long_running` 键。

<CodeGroup>
  ```python Python theme={null}
  from ppio_sandbox import PPIO

  ppio = PPIO()

  # 创建一个长时间运行的 code-interpreter Sandbox。
  # 启用 long_running 后，timeout 可以超过默认的 1 小时上限。
  sandbox = ppio.sandbox.create(
      metadata={
          'long_running': 'true',
      },
      timeout=86_400,  # 24 小时
  )
  ```

  ```typescript JavaScript & TypeScript theme={null}
  import { PPIO } from 'ppio-sandbox'

  const ppio = new PPIO()

  // 创建一个长时间运行的 code-interpreter Sandbox。
  // 启用 long_running 后，timeoutMs 可以超过默认的 1 小时上限。
  const sandbox = await ppio.sandbox.create({
    metadata: {
      long_running: 'true',
    },
    timeoutMs: 86_400_000, // 24 小时
  })
  ```

  ```bash CLI theme={null}
  # 创建一个长时间运行的 Sandbox（分离模式）。
  # --long-running 会在 metadata 中写入 long_running=true，
  # 启用后 --timeout 可以超过默认的 1 小时上限。
  ppio sandbox create base --long-running --timeout 24h -d
  ```
</CodeGroup>

## 工作原理

* 在 `create`(以及 `resume`)时,如果设置了 `long_running`,传入的 `timeout` 可以超过默认 1 小时的最长运行时间。

## 作用范围与继承

* 只有 `create` 接受 `long_running` 参数。
* `resume`(包括自动恢复):使用 `long_running` 创建的 Sandbox 从快照恢复后仍保持该行为。
* `clone` 会继承该参数;经过 `reset` 后继续运行的 Sandbox 也会保留该行为。

## 示例

创建一个最长可存活 **7 天**的长时间运行 Sandbox:

<CodeGroup>
  ```python Python theme={null}
  from ppio_sandbox import PPIO

  ppio = PPIO()

  # 7 天 = 7 * 24 * 60 * 60 秒
  sandbox = ppio.sandbox.create(
      metadata={
          'long_running': 'true',
      },
      timeout=604_800,
  )
  ```

  ```typescript JavaScript & TypeScript theme={null}
  import { PPIO } from 'ppio-sandbox'

  const ppio = new PPIO()

  // 7 天 = 7 * 24 * 60 * 60 * 1000 毫秒
  const sandbox = await ppio.sandbox.create({
    metadata: {
      long_running: 'true',
    },
    timeoutMs: 604_800_000,
  })
  ```

  ```bash CLI theme={null}
  # 7 天 = 168 小时
  ppio sandbox create base --long-running --timeout 168h -d
  ```
</CodeGroup>