# Core Concepts

<subtitle>Build a mental model of UCloud Sandbox in the shortest path: Sandbox, Template, Snapshot, and Lifecycle.</subtitle>

Before diving into SDK details, please understand the following core concepts.

---

## Sandbox

A sandbox is an **isolated runtime environment** that provides full operating system capabilities. You can:

- Execute Shell commands and code
- Read and write file system
- Access network (configurable)
- Install software packages

**Lifecycle**: Create → Use → Destroy

```python
from ucloud_sandbox import Sandbox

# Create
sandbox = Sandbox.create(timeout=60)

# Use
result = sandbox.commands.run("echo 'Hello'")

# Destroy
sandbox.kill()
```

>
> For details, see: [Sandbox Lifecycle](/docs/agent-sandbox/sdk/sandbox/01-lifecycle)

---

## Template

A template is a **blueprint** for sandboxes. Through templates, you can:

- Pre-install software dependencies (Python packages, Node modules, etc.)
- Pre-configure files
- Set environment variables
- Start persistent services (such as web servers)

**Core Value**: Move initialization costs forward to the build stage, making subsequent sandbox creation faster and more stable.

```python
from ucloud_sandbox import Template

template = (
    Template()
    .from_base_image()
    .pip_install(["pandas", "numpy"])
    .set_envs({"ENV": "production"})
)
```

>
> For details, see: [Template Quick Start](/docs/agent-sandbox/template/01-quick-start)

---

## Snapshot

When template build completes, a **snapshot** is generated. What makes snapshots special:

- Not only includes file system state
- Also includes **running process state** (memory snapshot)

This allows sandboxes created from templates to directly restore to ready state, typically achieving **50-200ms level ultra-fast startup** (actual time depends on template complexity, network environment, and other factors).

```
┌─────────────────────────────────────────────────────────────┐
│  Traditional: Start container → Install deps → Start service → Ready (minutes)    │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  UCloud Sandbox: Restore from snapshot → Immediately ready (milliseconds)             │
└─────────────────────────────────────────────────────────────┘
```

>
> For details, see: [How Templates Work](/docs/agent-sandbox/concepts/02-how-it-works)

---

## Start Command and Ready Command

When building templates, you can define:

| Command Type | Purpose | Typical Use Cases |
|---------|------|---------|
| **Start Command** | Start background services during build and write their running state to snapshot | Web servers, databases |
| **Ready Command** | Determine if environment has reached usable state, generate snapshot when exit code is 0 | Port detection, file existence detection |

```python
from ucloud_sandbox import Template, wait_for_port

template = (
    Template()
    .from_node_image("20")
    .run_cmd("npm install")
    .set_start_cmd("npm start", wait_for_port(3000))
)
```

>
> For details, see: [Start and Ready Commands](/docs/agent-sandbox/template/08-start-and-ready-commands)

---

## Concept Relationship Diagram

```
┌────────────────────────────────────────────────────────────────┐
│                        Template                          │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Definition: Base image + Dependency installation + Environment variables + Start command          │  │
│  └──────────────────────────────────────────────────────────┘  │
│                            │                                    │
│                            ▼ Build                               │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Snapshot: File system + Memory state                     │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘
                             │
                             ▼ Create
┌────────────────────────────────────────────────────────────────┐
│                        Sandbox                           │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Capabilities: Command execution / File system / Network access / Metrics monitoring          │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘
```

---

## Next Steps

- [Product Architecture](/docs/agent-sandbox/concepts/02-how-it-works) - Understand system components and data flow
- [SDK Quick Start](/docs/agent-sandbox/product/00-quick-start) - Hands-on practice
- [Glossary](/docs/agent-sandbox/troubleshooting/glossary) - Quick reference for terminology