# Example Library
<subtitle>Sandbox build solutions covering basic web applications, multi-runtime environments, and graphical desktops.</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
```

Through the following examples, you can quickly understand how to customize dedicated environments for various complex Agent tasks.

---

## Next.js Full-Stack Application (Node.js)

This example demonstrates how to build an environment pre-installed with Next.js, Tailwind CSS, and shadcn UI.

>
> **Sandbox Pre-loading**: After template build completes, sandbox startup will automatically run `npm run dev`, with the development server ready on port 3000.

```python
# template.py
from ucloud_sandbox import Template, wait_for_url

template = (
    Template()
    .from_node_image("21-slim")
    .set_workdir("/home/user/nextjs-app")
    .run_cmd('npx create-next-app@14.2.30 . --ts --tailwind --no-eslint --import-alias "@/*" --use-npm --no-app --no-src-dir')
    .run_cmd("npx shadcn@2.1.7 init -d")
    .run_cmd("npx shadcn@2.1.7 add --all")
    # Organize directory structure and set start command
    .run_cmd("mv /home/user/nextjs-app/* /home/user/ && rm -rf /home/user/nextjs-app")
    .set_workdir("/home/user")
    .set_start_cmd("npx next --turbo", wait_for_url('http://localhost:3000'))
)
```

---

## High-Performance Web Environment (Bun)

Using Bun runtime can significantly improve dependency installation and hot reload speed.

```python
# template.py
from ucloud_sandbox import Template, wait_for_url

template = (
    Template()
    .from_bun_image("1.3")
    .set_workdir("/home/user/nextjs-app")
    .run_cmd("bun create next-app --app --ts --tailwind --turbopack --yes --use-bun .")
    .run_cmd("bunx --bun shadcn@latest init -d")
    .set_workdir("/home/user")
    .set_start_cmd("bun --bun run dev", wait_for_url('http://localhost:3000'))
)
```

---

## Graphical Desktop Environment (GUI & VNC)

UCloud Sandbox supports running X11 desktop environments and provides real-time interactive interfaces in browsers through NoVNC.

```python
# template.py
from ucloud_sandbox import Template, wait_for_port

template = (
    Template()
    .from_image("ubuntu:22.04")
    # Install all system dependencies required for graphical environment
    .run_cmd([
        "apt-get update",
        "apt-get install -y xfce4 xfce4-goodies xvfb x11vnc xdotool novnc websockify",
        "apt-get clean"
    ])
    # Copy and set VNC startup script
    .copy("start_command.sh", "/start_command.sh")
    .run_cmd("chmod +x /start_command.sh")
    # Start desktop service on startup, wait for port 6080 to be ready
    .set_start_cmd("/start_command.sh", wait_for_port(6080))
)
```

>
> **Resource Recommendation**: Running desktop environments is recommended to configure higher resource limits (such as 8-core CPU, 8GB memory) to ensure smooth control experience.

---

## How to Build the Above Examples?

The build logic is basically the same, just call the `Template.build` interface:

```python
from ucloud_sandbox import Template, default_build_logger
from template import template

if __name__ == '__main__':
    Template.build(
        template,
        alias="my-example-env",
        cpu_count=4,
        memory_mb=4096,
        on_build_logs=default_build_logger(),
    )
```