# How Templates Work
<subtitle>Deep dive into how UCloud Sandbox achieves millisecond-level sandbox startup and environment restoration through snapshot technology.</subtitle>

## Environment Setup

Before using the SDK, please ensure that the `AGENTBOX_API_KEY` environment variable is configured.

>
> You can obtain your API key from the [Console API Keys page](https://console.ucloud.cn/modelverse/experience/api-keys).

```bash
export AGENTBOX_API_KEY=your_api_key
```

## Overall Process

Each time you initiate a template build request, the system will start a temporary container environment based on your definition (Dockerfile or SDK definition) for preprocessing.

The specific build steps are as follows:

1.  **Environment Initialization**: Start container based on specified image and mount file system.
2.  **Dependency Installation**: Execute your defined `apt_install`, `pip_install`, or `run_cmd` instructions.
3.  **Service Startup** (Optional): Execute your configured [Start Command](/docs/agent-sandbox/template/08-start-and-ready-commands).
4.  **Readiness Check**: Execute [Ready Command](/docs/agent-sandbox/template/08-start-and-ready-commands) to confirm the environment is fully available.
5.  **Snapshot Persistence**: Serialize and save the entire sandbox's file system and **memory state (running processes)** together.

We call this final generated persistent state the **Sandbox Template**.

---

## Core Technology: Sandbox Snapshot

Snapshots are the embodiment of UCloud Sandbox's core competitiveness. They are not just disk images, but complete preservation of running state.

*   **Ultra-Fast Startup**: Since snapshots include memory state, starting sandboxes no longer requires traditional system boot or application initialization, typically entering ready state within **50-200ms**.
*   **State Restoration**: When you create a sandbox from a template, all pre-configured processes (such as databases, web servers) are already in running state and do not need to be started again.

---

## Notes

### Kernel Version
Sandboxes uniformly run on **LTS 6.1 Linux kernel**.

>
> **Kernel Binding Note**: The kernel version is fixed at the **moment of template build**. If the base image library updates the kernel and you want to apply these updates, you must **rebuild the template**. Sandboxes generated from old templates cannot directly upgrade the kernel online.

### User and Directory
For default permissions and working directory within sandboxes, please refer to [User and Work Directory](/docs/agent-sandbox/template/03-user-and-work-dir).