# Container Images

**Page:** foundation/containers/images

[Download Raw Markdown](./foundation/containers/images.md)

---

# Container Images

**Every container starts with an image.** Choose from Ubuntu, Debian, Alpine, Fedora, and more. Free community images or premium pre-configured environments.

After [creating containers](/foundation/containers/create-edit-delete/), you need to understand **which operating system and software foundation** to build on.

---

## Available Operating Systems

**Quick reference of supported Linux distributions:**

| OS | Latest Version | Image Name | Size | Best For |
|---|---|---|---|---|
| **Debian** | 13 (Trixie) | `debian/13` ⭐ | ~500 MB | Production stability |
| **Debian** | 12 (Bookworm) | `debian/12` | ~500 MB | Long-term support |
| **Ubuntu** | 24.04 LTS | `ubuntu/24.04` | ~1-2 GB | General development |
| **Ubuntu** | 22.04 LTS | `ubuntu/22.04` | ~1-2 GB | Wider compatibility |
| **Alpine** | 3.19 | `alpine/3.19` | ~50-200 MB | Microservices |
| **Alpine** | 3.18 | `alpine/3.18` | ~50-200 MB | Resource optimization |
| **Fedora** | — | `fedora/<release>` | ~1-2 GB | Cutting-edge packages (pick a release from `GET /api/v1/images/public`) |
| **CentOS** | 9 Stream | `centos/9` | ~1-2 GB | Enterprise compatibility |
| **Rocky Linux** | 9 | `rockylinux/9` | ~1-2 GB | RHEL-compatible |


**Recommended default:** `debian/13` provides excellent stability, security, and package availability for most use cases.



**Windows containers:** Support for running Windows inside containers is coming soon. Currently, Windows does not run well on the platform. Use Linux distributions for now.


---

## API Endpoints Summary

**Official Technical Reference:**

This Foundation page explains image concepts and selection. For complete endpoint documentation:

**Public Marketplace:**
- **[GET /api/v1/images/public](/api/container-images/)** - Browse available images
- **[GET /api/v1/images/public/\{id\}](/api/container-images/)** - Get image details
- **[GET /api/v1/images/\{id\}/icon](/api/container-images/)** - Download image icon

**Your Images:**
- **[GET /api/v1/images/user](/api/container-images/)** - List imported/purchased images
- **[POST /api/v1/images/import/\{id\}](/api/container-images/)** - Import free image
- **[POST /api/v1/images/purchase/\{id\}](/api/container-images/)** - Purchase paid image
- **[POST /api/v1/images/rate/\{id\}](/api/container-images/)** - Rate image (0-5 stars)

---

## What Are Container Images?

**A container image is the starting point:** The operating system, pre-installed software, and default configuration that your container boots from.

```
Container Image (Ubuntu 22.04)
        ↓
Container Creation
        ↓
Running Container (Ubuntu 22.04 + your work)
```

**The image provides:**
- ✅ Base operating system (Linux distribution)
- ✅ System libraries and tools
- ✅ Default package manager (apt, apk, dnf, yum)
- ✅ Initial filesystem structure
- ✅ Sometimes: Pre-installed software (databases, web servers, dev tools)

**Your work builds on top:** Install applications, configure services, add data, customize environment.


**Images are immutable templates.** Once a container is created from an image, the image doesn't change. But you can always create NEW containers with different images.



**Custom Hoody Kernel:** All containers run on a custom hardened Hoody kernel. You **cannot change the kernel version** - it's managed at the host level for security and performance optimization. Images only control userspace (OS distribution, packages, configuration).


---

## The Image Marketplace

**Hoody provides a marketplace of container images:**

### Browsing Images



**Filter by criteria:**

You can filter images using query parameters:
- `os` - Filter by operating system (ubuntu, debian, alpine, fedora, centos)
- `architecture` - Filter by CPU architecture (amd64, arm64)
- `min_price` / `max_price` - Filter by price range
- `min_rating` - Filter by minimum rating
- `search` - Search by keyword
- `sort_by` / `sort_order` - Sort results

### Image Properties

**Each image has:**

| Property | Description | Example Values |
|----------|-------------|----------------|
| **OS** | Operating system | ubuntu, debian, alpine, fedora, centos |
| **Release** | Version/release | 22.04, 12, 3.18, 38 |
| **Architecture** | CPU architecture | amd64, arm64, armhf |
| **Size** | Disk space required | 500 MB - 5 GB |
| **Price** | Cost in USD | 0 (free), 5, 10, 25 |
| **Rating** | Community rating | 0.0 - 5.0 stars |
| **Prespawn** | Fast-start optimized | true/false |
| **Variant** | Special configuration | cloud, minimal, standard |

---

## Operating Systems

**Choose based on your needs:**

### Ubuntu (Most Popular)

**Recommended:** `ubuntu/24.04` or `ubuntu/22.04` (LTS releases)

**Best for:**
- ✅ General purpose development
- ✅ Web servers (nginx, Apache)
- ✅ Application deployments (Node.js, Python, Go)
- ✅ Most tutorials and documentation assume Ubuntu
- ✅ Large package repository (apt)

**Characteristics:**
- Larger size (~1-2 GB)
- More pre-installed tools
- Familiar to most developers
- Long-term support releases

### Debian

**Recommended:** `debian/13` (Trixie, latest) or `debian/12` (Bookworm, stable)

**Best for:**
- ✅ Production servers (rock-solid stability)
- ✅ Security-conscious deployments
- ✅ Minimal but complete environment

**Characteristics:**
- Similar to Ubuntu (Ubuntu is Debian-based)
- More conservative updates
- Excellent stability
- Smaller size than Ubuntu

### Alpine Linux

**Recommended:** `alpine/3.19` or `alpine/3.18`

**Best for:**
- ✅ Microservices (minimal footprint)
- ✅ Container optimization (fast startup)
- ✅ Resource-constrained scenarios
- ✅ Security-focused deployments

**Characteristics:**
- Very small size (~5-50 MB)
- Uses musl libc (not glibc)
- apk package manager
- Fast bootup


**Alpine uses musl instead of glibc.** Some pre-compiled binaries built for glibc won't work. Most interpreted languages (Node.js, Python, Go) work fine, but check compatibility for native binaries.


### Fedora

**Recommended:** any Fedora release available in `GET /api/v1/images/public?os=fedora`

**Best for:**
- ✅ Cutting-edge software versions
- ✅ RedHat ecosystem development
- ✅ Testing new kernel features

**Characteristics:**
- Latest packages (sometimes too bleeding-edge)
- dnf package manager
- RedHat-like environment
- Shorter support cycle than Ubuntu LTS

### CentOS / Rocky Linux

**Recommended:** `centos/9` or `rockylinux/9`

**Best for:**
- ✅ Enterprise applications
- ✅ Long-term stability requirements
- ✅ RedHat compatibility

**Characteristics:**
- Enterprise-focused
- Long support cycles
- Conservative package versions
- yum/dnf package manager

---

## CPU Architecture

**Match image architecture to your server:**

### amd64 (x86-64)

**Most common.** Standard Intel/AMD processors. Nearly all deployments use amd64 unless you specifically have ARM servers.

### arm64 (ARM 64-bit)

**ARM processors.** Apple Silicon, AWS Graviton, Raspberry Pi 4+. Used for ARM-based servers and cost-optimized cloud instances.

### armhf (ARM hard float)

**Older ARM devices.** Raspberry Pi 3 and earlier. Rarely needed in modern deployments.


**Check your server architecture** via `GET /api/v1/servers/{id}` before selecting images. Mismatched architecture = container won't start.


---

## Running Docker, Kubernetes, and Container Orchestration

**Hoody containers fully support Docker, Kubernetes, and any container orchestration platform.**

### Docker Inside Containers

**You can run Docker inside Hoody containers** - this is a supported and common use case:

```bash
# After container creation with debian/13
# Install Docker inside container via terminal
apt-get update
apt-get install -y docker.io
systemctl start docker

# Now use Docker normally
docker run hello-world
docker-compose up
```

**Full Docker capabilities:**
- ✅ Docker daemon runs inside container
- ✅ Docker Compose works perfectly
- ✅ Build and run any Docker images
- ✅ Docker networking and volumes
- ✅ Multi-container applications via Docker Compose

### Kubernetes and Orchestration

**Run Kubernetes clusters inside containers:**
- K3s (lightweight Kubernetes)
- Minikube for development
- Kind (Kubernetes in Docker)
- Any container orchestration platform

**Freedom of choice:** Use Docker, Podman, containerd, or any container runtime. Hoody containers are general-purpose Linux environments - you control the stack.

### Recommended Base Image for Docker

**Use `debian/13` as base image when running Docker:**

```bash
POST /api/v1/projects/{id}/containers
{
  "name": "docker-host",
  "server_id": "{server_id}",
  "container_image": "debian/13",
  "hoody_kit": true
}
```

**Why Debian:**
- Rock-solid stability for long-running Docker daemons
- Excellent Docker package support
- Minimal conflicts with container runtimes
- Well-tested in production environments

**Then install Docker via terminal/SSH** and use it however you need - single containers, Docker Compose stacks, or full orchestration platforms.


**Nested Containers Pattern:** Hoody container → Docker daemon → Your application containers. This gives you HTTP-accessible Linux machines that can themselves run containerized applications.


---

## Importing and Purchasing Images

### Import Free Images

**Most OS images are free:**

First, find images in the marketplace:



Then import to your library:



**Response:**

```json
{
  "statusCode": 200,
  "message": "Free image imported successfully",
  "data": {}
}
```

**Now available for container creation** using the image name format `ubuntu/22.04`.

### Purchase Premium Images

**Some images include pre-installed commercial software:**

First, check image details (including price):



Then purchase the image:



**Response:**

```json
{
  "statusCode": 200,
  "message": "Image purchased successfully",
  "data": {
    "price_paid": 15,
    "remaining_balance": 485
  }
}
```

**Deducted from wallet balance.** One-time payment, permanent access.

### Your Image Library



**Shows only images you can use** when creating containers.

---

## Image Rating System

**Help the community by rating images:**



**Rating scale (0-5):**
- 5 stars: Excellent (works perfectly, well-configured)
- 4 stars: Good (minor issues or missing documentation)
- 3 stars: Average (works but needs tweaking)
- 2 stars: Poor (significant issues)
- 1 star: Broken (doesn't work as advertised)
- 0 stars: Lowest possible rating (also accepted by the API)

**Your ratings help others choose images** and improve marketplace quality.

---

## Choosing the Right Image

### Decision Matrix


  
    **Recommended:** `ubuntu/24.04` or `ubuntu/22.04` LTS
    
    **Why:**
    - Most documentation assumes Ubuntu
    - Large package repository (apt)
    - Good balance of features vs size
    - Long-term support releases
  
  
    **Recommended:** `debian/13` or `debian/12`
    
    **Why:**
    - Rock-solid stability
    - Security-focused
    - Smaller than Ubuntu
    - Well-suited for long-running services
  
  
    **Recommended:** `alpine/3.19` or `alpine/3.18`
    
    **Why:**
    - Minimal size (fast startup)
    - Perfect for single-purpose services
    - Lower resource usage
    - Security hardened by default
  
  
    **Recommended:** the latest Fedora/CentOS release available in `GET /api/v1/images/public`
    
    **Why:**
    - RedHat-compatible environment
    - RPM package management (dnf/yum)
    - Enterprise software compatibility
  


### Size Considerations

| Image | Typical Size | Boot Time | Best For |
|-------|-------------|-----------|----------|
| **Alpine** | 50-200 MB | 3-5 seconds | Microservices, utilities |
| **Debian** | 500 MB - 1 GB | 5-10 seconds | Production servers |
| **Ubuntu** | 1-2 GB | 8-15 seconds | Development, general use |
| **Fedora** | 1-2 GB | 8-15 seconds | Cutting-edge packages |

**Smaller images:**
- ✅ Faster container creation
- ✅ Less storage cost
- ✅ Faster snapshots
- ❌ Fewer pre-installed tools

**Larger images:**
- ✅ More tools included
- ✅ Batteries-included experience
- ❌ Slower creation/snapshots
- ❌ Higher storage cost

---

## Prespawn-Optimized Images

**Some images are marked `prespawn: true`:**



**What this means:**
- Image optimized for instant container creation
- Used in prespawn templates
- Pre-cached on servers
- Sub-5-second container startup

**Use prespawn images when:**
- You need instant container availability
- Auto-scaling scenarios
- On-demand environments
- Interactive demos

**See:** Prespawn templates allow pre-created container pools that are claimed in milliseconds.

---

## Using Images in Container Creation

### Specify Image During Creation



**The `container_image` parameter:**
- Format: `{os}/{release}` (e.g., `debian/13`, `ubuntu/24.04`)
- Must match an image in your library
- If omitted or null: Uses project/system default

### Default Image Selection

**If you don't specify `container_image`:**

The system default image is used (currently `debian/13`). Specify `container_image` explicitly on every `POST /api/v1/projects/{project_id}/containers` call to pin the OS you want.

---

## Image Selection Examples

### Example 1: Web Application Stack

Node.js application with Ubuntu - create container with `ubuntu/24.04`, then install Node.js via terminal URL or SSH.

### Example 2: Lightweight API Service

Python FastAPI on Alpine using `alpine/3.19` for minimal footprint and cost-optimized microservice deployment.

### Example 3: Database Container

PostgreSQL on Debian using `debian/13` for stability-focused production database, then install PostgreSQL via package manager.

### Example 4: Multi-Architecture Support

Same application deployed on both AMD64 servers (Intel/AMD) and ARM64 servers (Graviton/Apple Silicon). Use `ubuntu/24.04` on both - architecture determined by target server automatically.

---

## Image Variants

**Some images come in specialized variants:**

| Variant | Description | When to Use |
|---------|-------------|-------------|
| **standard** | Default full-featured | General use |
| **minimal** | Stripped-down version | Size-constrained scenarios |
| **cloud** | Optimized for cloud deployment | Production servers |
| **desktop** | Includes GUI components | When using [displays](/kit/displays/) |

**Format:** `ubuntu/24.04` (standard), `ubuntu/24.04-minimal` (minimal variant), `ubuntu/24.04-cloud` (cloud-optimized)

**Check marketplace** for available variants of each OS.

---

## Creating Image-Based Templates

**Use images + snapshots for instant environment provisioning:**

### The Template Workflow


  
    Start with clean Ubuntu container using `ubuntu/24.04` image with Hoody Kit enabled.
  
  
    Install Node.js, tools, and dependencies via terminal URL. Set up global npm packages (TypeScript, pnpm, yarn), configure Git, and prepare development environment.
  
  
    Capture the perfect state as a snapshot with user-friendly alias "nodejs-dev-template-2025". Set expiry to null for permanent storage.
  
  
    Copy from template snapshot to new projects. All tools pre-installed - ready to code immediately without setup overhead. One perfect setup, infinite instantiations.
  


**One perfect setup → infinite instantiations.**

---

## Image Discovery and Searching

### Search by Keyword


  
    ```bash
    # Find Docker-related images
    hoody images list --search docker

    # Find database images
    hoody images list --search database

    # Find Node.js images
    hoody images list --search nodejs
    ```
  
  
    ```typescript
    // Find Docker-related images
    const dockerImages = await client.api.images.listPublic({ search: 'docker' });

    // Find database images
    const dbImages = await client.api.images.listPublic({ search: 'database' });
    ```
  
  
    ```bash
    # Find Docker-related images
    curl "https://api.hoody.icu/api/v1/images/public?search=docker" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # Find database images
    curl "https://api.hoody.icu/api/v1/images/public?search=database" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # Find Node.js images
    curl "https://api.hoody.icu/api/v1/images/public?search=nodejs" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    ```
  


**Searches:** Image name, description, and tags.

### Sort by Popularity


  
    ```bash
    # Highest rated images
    hoody images list --sort-by rating --sort-order desc --limit 10
    ```
  
  
    ```typescript
    // Highest rated images
    const topImages = await client.api.images.listPublic({
      page: 1,
      limit: 10,
      sort_by: 'rating',
      sort_order: 'desc',
    });
    ```
  
  
    ```bash
    # Highest rated images
    curl "https://api.hoody.icu/api/v1/images/public?sort_by=rating&sort_order=desc&limit=10" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    ```
  


### Filter by Price Range


  
    ```bash
    # Free images only
    hoody images list --min-price 0 --max-price 0

    # Budget images ($0-$10)
    hoody images list --min-price 0 --max-price 10

    # Premium images ($25+)
    hoody images list --min-price 25
    ```
  
  
    ```typescript
    // Free images only
    const freeImages = await client.api.images.listPublic({ min_price: 0, max_price: 0 });

    // Budget images ($0-$10)
    const budgetImages = await client.api.images.listPublic({ min_price: 0, max_price: 10 });

    // Premium images ($25+)
    const premiumImages = await client.api.images.listPublic({ min_price: 25 });
    ```
  
  
    ```bash
    # Free images only
    curl "https://api.hoody.icu/api/v1/images/public?min_price=0&max_price=0" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # Budget images ($0-$10)
    curl "https://api.hoody.icu/api/v1/images/public?min_price=0&max_price=10" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # Premium images ($25+)
    curl "https://api.hoody.icu/api/v1/images/public?min_price=25" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    ```
  


---

## Image Metadata

**Get detailed information:**



**Response:**

```json
{
  "statusCode": 200,
  "data": {
    "id": "63a3e4b5c6d7e8f9a0b1c2d3",
    "alias": "ubuntu/22.04",
    "description": "Ubuntu 22.04 LTS (Jammy Jellyfish) - Long-term support until 2027",
    "image_name": "ubuntu-22.04-amd64",
    "architecture": "amd64",
    "os": "ubuntu",
    "release": "22.04",
    "serial": "20231109",
    "variant": "default",
    "size": 1572864000,
    "price": 0,
    "added_date": "2023-11-09T00:00:00.000Z",
    "average_rating": 4.8,
    "rating_count": 1247,
    "icon_url": "/api/v1/images/63a3e4b5c6d7e8f9a0b1c2d3/icon",
    "prespawn": true
  }
}
```

**Use to:**
- Verify architecture matches server
- Check size for storage planning
- Read description for pre-installed software
- See community ratings for quality

---

## Best Practices

### 1. Match Architecture to Server

Always verify server architecture before selecting images. Query `GET /api/v1/servers/{server_id}` and filter images by that architecture. Mismatched architecture = container won't start.

### 2. Import Images Before Bulk Creation

If creating many containers with the same image, import it once first. Then all subsequent creations skip the import wait - faster, more reliable.

### 3. Use Specific Versions, Not "latest"

Specify exact versions like `debian/13` or `ubuntu/24.04`. Avoid "latest" tags - they change over time and break reproducibility.

### 4. Test Images in Development First

Try new images (especially Alpine with musl) in development environments before production. Verify your application's dependencies are compatible with that distribution.

### 5. Use debian/13 for Docker Hosts

When running Docker/Kubernetes inside containers, start with `debian/13`. Excellent Docker package support, minimal conflicts with container runtimes.

### 6. Rate Images After Use

After successfully using an image, rate it honestly (0-5 stars). Help the community make better choices and improve marketplace quality.

### 7. Choose Image Based on Purpose

Production services: `debian/13` (stability). General development: `ubuntu/24.04` (familiarity). Microservices: `alpine/3.19` (minimal footprint). Match image to workload characteristics.

---

## Useful Questions

### Can I change a container's image after creation?

No. The image is permanent once container is created. To use a different OS:
1. [Snapshot](/foundation/containers/snapshots/) your data
2. Create new container with desired image
3. Transfer data manually or via [storage shares](/foundation/storage/sharing-files/)
4. Delete old container

### What happens if I import an image I already have?

The API returns success (idempotent operation). Image isn't duplicated—you just re-confirm it's in your library.

### Do purchased images work on all my servers?

Yes. Once purchased, an image is available for ANY container creation across ALL your servers (of matching architecture).

### Can I create my own custom images?

Not directly via the API currently. Template workflow (base image → configure → snapshot → copy from snapshot) achieves similar result. The snapshot becomes your reusable template.

### What's the difference between image variants?

Variants are different configurations of the same OS version. "minimal" has fewer pre-installed packages (smaller size), "cloud" is optimized for cloud deployment, "desktop" includes GUI components for [display service](/kit/displays/).

### Do images include the Hoody Kit?

No. Images are base operating systems only. The Hoody Kit (18 HTTP services) is installed **when you create the container** if you set `hoody_kit: true` in the creation request.

### Can I roll back to a previous image version?

Images don't version like software. If a new image release has issues, create containers from older release explicitly: `ubuntu/22.04` instead of `ubuntu/24.04`.

### How do I know which image to use for my application?

Check your application's system requirements (documentation, Docker images, deployment guides). Match OS, architecture, and ensure required packages are available in that distribution's repository.

### Do images affect container pricing?

Indirectly: Larger images require more storage (higher storage cost). Some premium images have purchase cost. But image choice doesn't affect compute pricing (CPU/RAM charges are based on allocation, not OS).

---

## Troubleshooting

### Image Not Found During Container Creation

**Problem:** Container creation fails with "image not found"

**Solutions:**

1. **Import the image first:**
   ```bash
   # Find image in marketplace
   GET /api/v1/images/public?search=ubuntu
   
   # Import it
   POST /api/v1/images/import/{image_id}
   ```

2. **Check image name format:**
   ```bash
   # ✅ Correct: "ubuntu/24.04"
   # ❌ Wrong: "ubuntu:24.04"
   # ❌ Wrong: "ubuntu-24.04"
   # ❌ Wrong: "ubuntu"
   ```

3. **Verify image in your library:**
   ```bash
   GET /api/v1/images/user
   # Ensure image appears in list
   ```

### Architecture Mismatch

**Problem:** Container creation fails or crashes immediately

**Cause:** Image architecture doesn't match server

**Solution:**

1. **Check server architecture:**
   ```bash
   GET /api/v1/servers/{server_id}
   # Note: architecture field
   ```

2. **Filter images by architecture:**
   ```bash
   GET /api/v1/images/public?architecture=amd64
   # Or: ?architecture=arm64
   ```

3. **Import matching image:**
   ```bash
   POST /api/v1/images/import/{correct_architecture_image_id}
   ```

### Insufficient Balance for Purchase

**Problem:** Image purchase fails with insufficient funds

**Solution:**

```bash
# Check wallet balance
GET /api/v1/wallet/balances

# Add funds if needed
# (via platform billing system)

# Then purchase
POST /api/v1/images/purchase/{image_id}
```

### Container Creation Slow

**Problem:** Container takes longer than expected to create

**Possible cause:** Large image size

**Solutions:**

1. **Choose smaller image:**
   - Alpine instead of Ubuntu
   - Minimal variant instead of standard

2. **First creation on server is slower:**
   - Image must be pulled to server
   - Subsequent containers with same image are faster
   - This is normal, not an issue

---

## What's Next

**Build on your image foundation:**

1. **[Create, Edit, Delete →](./create-edit-delete/)** - Use images in container creation
2. **[Managing →](./managing/)** - Operate containers regardless of image
3. **[Snapshots →](./snapshots/)** - Snapshot configured containers as templates
4. **[Copy & Sync →](./copy-sync/)** - Duplicate configured environments

**Explore the Hoody Kit:**
- 🛠️ [The Hoody Kit →](/kit/) - 18 HTTP services work on ANY image
- 📚 [API Reference →](/api/authentication/) - Complete endpoint documentation

**Understanding gained:**
- ✅ Images are OS templates for containers
- ✅ Choose based on size, stability, package ecosystem
- ✅ Import free images or purchase premium
- ✅ Images are immutable (can't change after creation)
- ✅ Prespawn images enable instant creation
- ✅ Architecture must match server
- ✅ Rate images to help community

---

> **Start with the right foundation.**
> **Debian for production. Ubuntu for general use. Alpine for microservices.**
> **Import once, use forever. One perfect setup, infinite containers.**