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, 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

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 - Browse available images
GET /api/v1/images/public/{id} - Get image details
GET /api/v1/images/{id}/icon - Download image icon

Your Images:

GET /api/v1/images/user - List imported/purchased images
POST /api/v1/images/import/{id} - Import free image
POST /api/v1/images/purchase/{id} - Purchase paid image
POST /api/v1/images/rate/{id} - 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.

The Image Marketplace

Hoody provides a marketplace of container images:

Browsing Images

GET Browse available images

/api/v1/images/public

Click "Run" to execute the request

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

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.

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:

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

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.

Importing and Purchasing Images

Import Free Images

Most OS images are free:

First, find images in the marketplace:

GET Find free Ubuntu images

/api/v1/images/public

Click "Run" to execute the request

Then import to your library:

POST Import image to your library

/api/v1/images/import/{image_id}

Click "Run" to execute the request

Response:

{
  "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):

GET Get image details

/api/v1/images/public/{image_id}

Click "Run" to execute the request

Then purchase the image:

POST Purchase premium image

/api/v1/images/purchase/{image_id}

Click "Run" to execute the request

Response:

{
  "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

GET List your imported/purchased images

/api/v1/images/user

Click "Run" to execute the request

Shows only images you can use when creating containers.

Image Rating System

Help the community by rating images:

POST Rate an image

/api/v1/images/rate/{image_id}

Click "Run" to execute the request

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:

GET Browse the public catalog; look for images with `prespawn: true` in the response

/api/v1/images/public

Click "Run" to execute the request

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

POST Create container with specific image

/api/v1/projects/{project_id}/containers

Click "Run" to execute the request

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

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.

One perfect setup → infinite instantiations.

Image Discovery and Searching

Search by Keyword

# 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

// 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' });

# 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

# Highest rated images
hoody images list --sort-by rating --sort-order desc --limit 10

// Highest rated images
const topImages = await client.api.images.listPublic({
  page: 1,
  limit: 10,
  sort_by: 'rating',
  sort_order: 'desc',
});

# 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

# 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

// 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 });

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

GET Get detailed image information

/api/v1/images/public/{image_id}

Click "Run" to execute the request

Response:

{
  "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:

Snapshot your data
Create new container with desired image
Transfer data manually or via storage shares
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.

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:

Import the image first:

# Find image in marketplace
GET /api/v1/images/public?search=ubuntu

# Import it
POST /api/v1/images/import/{image_id}

Check image name format:

# ✅ Correct: "ubuntu/24.04"
# ❌ Wrong: "ubuntu:24.04"
# ❌ Wrong: "ubuntu-24.04"
# ❌ Wrong: "ubuntu"

Verify image in your library:

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:

Check server architecture:

GET /api/v1/servers/{server_id}
# Note: architecture field

Filter images by architecture:

GET /api/v1/images/public?architecture=amd64
# Or: ?architecture=arm64

Import matching image:

POST /api/v1/images/import/{correct_architecture_image_id}

Insufficient Balance for Purchase

Problem: Image purchase fails with insufficient funds

Solution:

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

Choose smaller image:
- Alpine instead of Ubuntu
- Minimal variant instead of standard
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:

Create, Edit, Delete → - Use images in container creation
Managing → - Operate containers regardless of image
Snapshots → - Snapshot configured containers as templates
Copy & Sync → - Duplicate configured environments

Explore the Hoody Kit:

🛠️ The Hoody Kit → - 18 HTTP services work on ANY image
📚 API Reference → - 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.