# Sandbox Lifecycle
<subtitle>Manage the entire process of sandbox from creation to shutdown, including timeout settings and runtime monitoring.</subtitle>

>
> **Prerequisites**: Please complete [API Key Configuration](/docs/agent-sandbox/product/01-prerequisites) first

## Creation and Timeout Settings

When starting a sandbox, the default lifetime (timeout) is 5 minutes (300 seconds). You can customize this parameter according to your needs.

>
> Note: Timed-out sandboxes will be automatically reclaimed and cleaned up by the system.

```python
from ucloud_sandbox import Sandbox

# Create sandbox and set lifetime to 60 seconds
# 🚨 Parameter unit is seconds
sandbox = Sandbox.create(timeout=60)
```

## Dynamic Timeout Adjustment

You can update the lifetime in real-time by calling the `set_timeout` method while the sandbox is running.

Each time you call this method, the remaining lifetime will be **recalculated from the current time point**. This is very useful for scenarios that need to dynamically extend sessions based on user interaction.

```python
from ucloud_sandbox import Sandbox

# Create sandbox with initial 60 seconds
sandbox = Sandbox.create(timeout=60)

# Adjust to 30 seconds in subsequent business logic
# Sandbox will automatically close 30 seconds from now
sandbox.set_timeout(30)
```

## Get Runtime Details

Through the `get_info` method, you can retrieve the real-time status of the sandbox, including ID, template used, metadata, and precise start and end times.

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(timeout=60)

# Get sandbox detailed information
info = sandbox.get_info()

print(info)

# Output example:
# 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)
# )
```

## Completely Close Sandbox

When the business process ends, it is recommended to immediately call the `kill` method to manually close the sandbox to release resources. The system will also automatically perform this operation after the task times out.

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(timeout=60)

# Immediately destroy and reclaim sandbox
sandbox.kill()
```