Container Images

Every container starts from an image: the operating system, pre-installed software, and default configuration it boots with. The marketplace carries Ubuntu, Debian, Alpine, Fedora, and others, both free community images and paid images that arrive pre-configured.

This page covers how to pick an image, how to import or purchase one, and how to use it when you create a container.

Available operating systems

OS	Latest Version	Image Name	Size	Best For
Debian	13 (Trixie)	`debian/13`	~500 MB	Production stability
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	Varies	`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

This page explains image concepts and selection. The endpoint reference carries the full request and response schemas.

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 an image provides

Creating a container instantiates an image:

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, and change the environment.

The image marketplace

Browse images

GET Browse available images

/api/v1/images/public

Click "Run" to execute the request

Filter with query parameters:

os - Filter by operating system (ubuntu, debian, alpine, fedora, centos)
architecture - Filter by CPU architecture (amd64, arm64, armhf)
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	default, null

Distributions in detail

Choose based on what the workload needs:

Ubuntu

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)

Best for:

Production servers
Security-conscious deployments
Minimal but complete environment

Characteristics:

Similar to Ubuntu (Ubuntu is Debian-based)
More conservative updates
Stable, slow-moving releases
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 (~50-200 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 the image’s architecture to the server it will run on.

amd64 (x86-64)

The most common choice: standard Intel and AMD processors. Nearly all deployments use amd64 unless you specifically have ARM servers.

arm64 (ARM 64-bit)

ARM processors, such as Apple Silicon, AWS Graviton, and Raspberry Pi 4 and later. 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.

Docker and Kubernetes inside containers

Hoody containers support Docker, Kubernetes, and other container orchestration platforms.

Docker inside containers

Running Docker inside a Hoody container is supported:

# 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

What works:

Docker daemon runs inside the container
Docker Compose
Building and running any Docker image
Docker networking and volumes
Multi-container applications via Docker Compose

Kubernetes and orchestration

Run Kubernetes clusters inside a container:

K3s (lightweight Kubernetes)
Minikube for development
Kind (Kubernetes in Docker)
Any container orchestration platform

Use Docker, Podman, containerd, or another container runtime. A Hoody container is a general-purpose Linux environment, so the stack is yours to choose.

Recommended base image for Docker

Use debian/13 as the 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:

Stable enough for long-running Docker daemons
Docker packages are well supported
Minimal conflicts with container runtimes
Well-tested in production environments

Install Docker over the terminal or SSH, then use it as you need: single containers, Docker Compose stacks, or a full orchestration platform.

Import and purchase 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": {}
}

The image is now available for container creation, using the 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
  }
}

The price is deducted from your wallet balance. It is a one-time payment, and access is permanent.

Imported and purchased images

GET List your imported/purchased images

/api/v1/images/user

Click "Run" to execute the request

The response lists only images you can use when creating containers.

Image ratings

Rate images to help other people choose:

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)

Choose an 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

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)
Suited to 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
Fewer packages to install after creation
Slower creation and 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

Prespawn templates keep pools of pre-created containers that are claimed in milliseconds.

Use an image at creation

Specify the image

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

If you omit container_image, the system default 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

Web application stack

A Node.js application on Ubuntu: create the container with ubuntu/24.04, then install Node.js over the terminal URL or SSH.

Lightweight API service

A Python FastAPI service on alpine/3.19, for a minimal footprint and a cost-optimized microservice.

Database container

PostgreSQL on debian/13 for a stability-focused production database. Install PostgreSQL with the package manager.

Multi-architecture support

The same application on both AMD64 servers (Intel and AMD) and ARM64 servers (Graviton, Apple Silicon). Use ubuntu/24.04 on both; the architecture follows the target server automatically.

Image variants

Some images come in specialized variants:

Variant	Description	When to Use
default	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: Specify the image by its alias (e.g., ubuntu/24.04). The variant is exposed as a separate variant field in each image’s marketplace metadata; it is not selected by appending a suffix to the alias.

Check the marketplace for the variants available for each OS.

Build templates from images

Images and snapshots together give you reusable environment templates:

The template workflow

Start with a clean Ubuntu container from the ubuntu/24.04 image, with Hoody Kit enabled.

Discover and search images

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.com/api/v1/images/public?search=docker" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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

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

One request, one link

cURL runs inside your container and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

Slashes, colons and braces pass through as they are. The one character you must encode is an & inside a value, which happens when the wrapped URL carries its own query string. Left raw it ends the value early, and the rest is read as cURL's own parameters, so you get a 200 on a request you did not make.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Each link searches the public marketplace for a different keyword.

# Docker images
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/images/public?search=docker&method=GET&bearer_token=TOKEN&response=transparent

# Database images
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/images/public?search=database&method=GET&bearer_token=TOKEN&response=transparent

# Node.js images
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/images/public?search=nodejs&method=GET&bearer_token=TOKEN&response=transparent

The link carries a credential and executes with it, so it is as sensitive as the credential itself — and it passes through the cURL service's request log on the way, not just the target's. Share it only where you would share the secret, and prefer a delegated token with minimal permissions and an expiry: see API tokens.

Searches: image name, description, and tags.

Sort by rating

# 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.com/api/v1/images/public?sort_by=rating&sort_order=desc&limit=10" \
  -H "Authorization: Bearer $HOODY_TOKEN"

One request, one link

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Lists the ten highest-rated public images.

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/images/public?sort_by=rating%26sort_order=desc%26limit=10&method=GET&bearer_token=TOKEN&response=transparent

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.com/api/v1/images/public?min_price=0&max_price=0" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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

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

One request, one link

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Each link filters the public marketplace to a different price range.

# Free images only
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/images/public?min_price=0%26max_price=0&method=GET&bearer_token=TOKEN&response=transparent

# Budget images ($0-$10)
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/images/public?min_price=0%26max_price=10&method=GET&bearer_token=TOKEN&response=transparent

# Premium images ($25+)
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/images/public?min_price=25&method=GET&bearer_token=TOKEN&response=transparent

Image metadata

Get detailed information about a single image:

GET Get detailed image information

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

Click "Run" to execute the request

Response:

{
  "statusCode": 200,
  "message": "Public image details retrieved successfully",
  "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

Match architecture to the server

Verify the server’s architecture before selecting an image. Query GET /api/v1/servers/{id} and filter images by that architecture. A mismatch means the container will not start.

Import before bulk creation

If you are creating many containers from the same image, import it once first. Later creations then skip the import wait.

Pin specific versions

Specify exact versions such as debian/13 or ubuntu/24.04. A “latest” tag changes over time and breaks reproducibility.

Test images in development first

Try new images, especially Alpine with musl, in development before production. Verify that your application’s dependencies work on that distribution.

Use debian/13 for Docker hosts

When running Docker or Kubernetes inside a container, start with debian/13. Its Docker packages are well supported and it conflicts less with container runtimes.

Rate images after use

After using an image, rate it honestly on the 0 to 5 scale. Ratings are what the next person sees when picking an image.

Choose the image for the workload

Production services: debian/13 for stability. General development: ubuntu/24.04 for familiarity. Microservices: alpine/3.19 for a minimal footprint.

Useful questions

Can I change a container’s image after creation?

No. The image is fixed once the container exists. 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 400 Bad Request with the message Image is not free or already imported. Re-importing is not idempotent. You do not need to re-import anyway: images already in your library are immediately available, so skip the import step entirely for an image you own.

Do purchased images work on all my servers?

Yes. Once purchased, an image is available for any container creation on any of your servers with a matching architecture.

Can I create my own custom images?

Not directly through the API. The template workflow gets close: start from a base image, configure it, snapshot it, then copy from that snapshot. 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 do not version like software. If a new image release has problems, create containers from an older release explicitly: ubuntu/22.04 rather than 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 need more storage, which costs more, and premium images carry a purchase price. Image choice does not affect compute pricing: CPU and RAM are charged on allocation, not on the OS.

Troubleshooting

Image not found at 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 your server details:

GET /api/v1/servers/{id}
# Review the server's CPU to know which architecture to target

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

Next pages:

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

The Hoody Kit:

The Hoody Kit → - 18 HTTP services, on any image
API Reference → - Complete endpoint documentation

What this page covered:

Images are OS templates for containers
Choose one on size, stability, and package ecosystem
Import free images or purchase premium ones
Images are immutable and cannot change after creation
Prespawn images allow near-instant creation
Architecture must match the server
Rating an image helps the next person choose