# Defining Templates

<subtitle>Master the complete API for template definition, including file operations, package installation, and command execution.</subtitle>

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

### Method Chaining

All template methods return template instances, allowing fluent API usage:

```python
from ucloud_sandbox import Template, wait_for_timeout

template = (
    Template()
    .from_ubuntu_image("22.04")
    .set_workdir("/app")
    .copy("package.json", "/app/package.json")
    .run_cmd("npm install")
    .set_start_cmd("npm start", wait_for_timeout(10_000))
)
```

### User and Working Directory

Set template working directory and user:

```python
from ucloud_sandbox import Template

template = Template().from_base_image()

# Set working directory
template.set_workdir("/app")

# Set user (subsequent commands will run as this user)
template.set_user("node")
template.set_user("1000:1000")  # User ID and group ID
```

### Copy Files

Copy files from local file system to template:

```python
from ucloud_sandbox import Template

template = Template().from_base_image()

# Copy single file
template.copy("package.json", "/app/package.json")

# Copy multiple files to same destination
template.copy(["file1", "file2"], "/app/file")

# Use copy_items to batch define copy rules
template.copy_items([
    {"src": "src/", "dest": "/app/src/"},
    {"src": "package.json", "dest": "/app/package.json"},
])

# Specify user and file permissions (mode)
template.copy("config.json", "/app/config.json", user="appuser", mode=0o644)
```

### File Operations

Perform various file operations during template build:

```python
from ucloud_sandbox import Template

template = Template().from_base_image()

# Delete file or directory
template.remove("/tmp/old-file")
template.remove("/tmp/old-dir", recursive=True)
template.remove("/tmp/file", force=True)  # Force delete

# Rename file or directory
template.rename("/old/path", "/new/path")
template.rename("/old/path", "/new/path", force=True)  # Force rename

# Create directory
template.make_dir("/app/data")
template.make_dir("/app/data", mode=0o755)  # Set permissions

# Create symbolic link
template.make_symlink("/path/to/target", "/path/to/link")
```

### Install Packages

Install packages using package managers:

```python
from ucloud_sandbox import Template

template = Template().from_base_image()

# Install Python packages
template.pip_install(["requests", "pandas", "numpy"])

# Install for current user (non-global)
template.pip_install(["requests", "pandas", "numpy"], g=False)

# Install Node.js packages
template.npm_install(["express", "lodash"])

# Install Node.js packages (global)
template.npm_install(["express", "lodash"], g=True)

# Install Bun packages
template.bun_install(["express", "lodash"])

# Install Bun packages (global)
template.bun_install(["express", "lodash"], g=True)

# Install system packages (Ubuntu/Debian)
template.apt_install(["curl", "wget", "git"])
```

### Git Operations

Clone Git repositories during template build (requires `git` installed):

```python
from ucloud_sandbox import Template

template = Template().from_base_image()

# Clone repository
template.git_clone("https://github.com/user/repo.git")

# Clone repository to specific path
template.git_clone("https://github.com/user/repo.git", "/app/repo")

# Clone specific branch
template.git_clone("https://github.com/user/repo.git", "/app/repo", branch="main")

# Shallow clone with depth limit
template.git_clone("https://github.com/user/repo.git", "/app/repo", depth=1)
```

### Environment Variables

Set environment variables in templates:

```python
from ucloud_sandbox import Template

template = Template().from_base_image()

template.set_envs({
    "NODE_ENV": "production",
    "API_KEY": "your-api-key",
    "DEBUG": "true",
})
```

### Run Commands

Execute shell commands during template build:

```python
from ucloud_sandbox import Template

template = Template().from_base_image()

# Run single command
template.run_cmd("apt-get update && apt-get install -y curl")

# Run multiple commands
template.run_cmd(["apt-get update", "apt-get install -y curl", "curl --version"])

# Run command as specific user
template.run_cmd("npm install", user="node")
```