# 沙箱生命周期
<subtitle>管理沙箱从创建到关闭的全过程，包括运行上限、超时设置、暂停恢复与手动销毁。</subtitle>

沙箱会按照您设置的超时时间保持运行。超时到期后，沙箱会由系统处理；如果启用了自动暂停，沙箱可以进入暂停状态以释放计算资源，同时保留完整运行状态，之后可以恢复继续使用。您也可以显式设置超时时间，或在任务完成后手动销毁沙箱。

> UCloud Sandbox 对所有用户的单次连续运行上限都是 **24 小时**。对于超过 24 小时的工作负载，请使用 [暂停与恢复](/docs/agent-sandbox/sdk/sandbox/04-persistence.md)：暂停会重置连续运行窗口，并完整保留沙箱状态。

## 创建沙箱并设置超时

启动沙箱时，默认存活时间（timeout）为 5 分钟（300 秒）。您可以根据需求自定义此参数。

> 注意：未启用自动暂停时，超时的沙箱会由系统自动回收并清理。需要保留运行状态时，请参考 [沙箱持久化](/docs/agent-sandbox/sdk/sandbox/04-persistence.md)。

```python
from ucloud_sandbox import Sandbox

# 创建沙箱并设置存活时间为 60 秒
# 参数单位为秒
sandbox = Sandbox.create(
    timeout=60,
)
```

## 动态调整存活时间

您可以在沙箱运行时调用 `set_timeout` 方法实时更新存活时间。

每次调用该方法时，沙箱超时时间都会重置为您指定的新值，并从当前时间点开始重新计算。这对于需要根据用户交互动态延长会话的场景非常有用。例如，您可以先用 1 分钟超时创建沙箱，再在用户每次交互时续期。

```python
from ucloud_sandbox import Sandbox

# 创建沙箱，初始 60 秒
sandbox = Sandbox.create(timeout=60)

# 在后续业务逻辑中重新调整为 30 秒
# 沙箱将从此刻起再运行 30 秒
sandbox.set_timeout(30)
```

## 获取运行详情

通过 `get_info` 方法，您可以检索沙箱信息，包括沙箱 ID、所用模板、元数据以及精确的开始与结束时间。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(timeout=60)

# 获取沙箱详细信息
info = sandbox.get_info()

print(info)

# 输出示例：
# SandboxInfo(
#   sandbox_id='ig6f1yt6idvxkxl562scj-419ff533',
#   template_id='u7nqkmpn3jjf1tvftlsu',
#   name='base',
#   metadata={},
#   started_at=datetime.datetime(2025, 3, 24, 15, 42, 59, 255612),
#   end_at=datetime.datetime(2025, 3, 24, 15, 47, 59, 255612)
# )
```

## 手动销毁沙箱

您可以在超时到期前随时调用 `kill` 方法销毁沙箱。业务流程结束后，建议主动销毁不再使用的沙箱，以释放资源。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(timeout=60)

# 立即销毁并回收沙箱
sandbox.kill()
```