# Base Image

<subtitle>Choose or customize base images for your templates.</subtitle>

>
> Your base image must be based on **Ubuntu** or **Debian**, otherwise the image build will fail.

## 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
```

## Create Template

When creating a template, you can specify options:

```python
from ucloud_sandbox import Template

template = Template(
    file_context_path=".",  # Custom file context path
    file_ignore_patterns=[".git", "node_modules"],  # File patterns to ignore
)
```

**File Ignore**: SDK will automatically read `.dockerignore` file and merge it with your `file_ignore_patterns`. Files matching these patterns will be excluded from upload and hash calculation.

## Define Base Image

Choose from predefined base images or use custom base images:

```python
from ucloud_sandbox import Template

# Predefined base images
template.from_ubuntu_image("lts")  # ubuntu:lts
template.from_ubuntu_image("22.04")  # ubuntu:22.04
template.from_debian_image("slim")  # debian:slim
template.from_debian_image("bullseye")  # debian:bullseye
template.from_python_image("3.13")  # python:3.13
template.from_python_image("3.11")  # python:3.11
template.from_node_image("lts")  # node:lts
template.from_node_image("20")  # node:20
template.from_bun_image("1.3")  # oven/bun:1.3

# Custom base image
template.from_image("custom-image:latest")

# Use default base image
template.from_base_image()

# Build from existing template
template.from_template("existing-template-alias")

# Parse and build from Dockerfile
template.from_dockerfile("Dockerfile")
template.from_dockerfile("FROM ubuntu:22.04\nRUN apt-get update")
```

> You can only call base image methods once per template. Subsequent calls will throw errors.

## Parse Existing Dockerfile

Use `from_dockerfile()` to convert existing Dockerfile to template format:

```python
from ucloud_sandbox import Template, wait_for_timeout

dockerfile_content = """
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
WORKDIR /app
COPY . .
ENV NODE_ENV=production
ENV PORT=3000
USER appuser
"""

template = (
    Template()
    .from_dockerfile(dockerfile_content)
    .set_start_cmd("npm start", wait_for_timeout(5_000))
)
```

### Dockerfile Instruction Support

| Instruction         | Support Status | Behavior                                                              |
| :------------------- | :------: | :---------------------------------------------------------------- |
| `FROM`               |    ✅    | Set base image                                                      |
| `RUN`                |    ✅    | Convert to `run_cmd()`                                                |
| `COPY` / `ADD`       |    ✅    | Convert to `copy()`                                                   |
| `WORKDIR`            |    ✅    | Convert to `set_workdir()`                                            |
| `USER`               |    ✅    | Convert to `set_user()`                                               |
| `ENV`                |    ✅    | Convert to `set_envs()`; supports `ENV key=value` and `ENV key value` formats |
| `CMD` / `ENTRYPOINT` |    ✅    | Convert to `set_start_cmd()`, with 20-second timeout as ready command              |
| `EXPOSE`             |    ❌    | Skip (not supported)                                                    |
| `VOLUME`             |    ❌    | Skip (not supported)                                                    |

> Multi-stage Dockerfiles are not supported.