# Computer Images reference **Page:** foundation/computers/images/reference [Download Raw Markdown](./foundation/computers/images/reference.md) --- # Computer Images reference Lookup tables for [Computer Images](/foundation/computers/images/). Every call, field and status is in the [Computer Images API](/api/computer-images/). ## Base image | OS | Version | Image Name | Size | |---|---|---|---| | **Debian** | 13 (Trixie) | `debian/13` | ~500 MB | | Rule | Detail | |---|---| | What it is for | `debian/13` is the base image for every workload: development, production services, databases, and Docker or Kubernetes hosts | | What it brings | glibc and the apt package manager, with Debian's full package repository; stable, slow-moving releases with security updates; a minimal but complete environment | | Spellings | Canonical `debian/13`. Also accepted: `debian:13`, `debian-13`, `debian 13`, and `debian` (resolved to `debian/13`) | | Image stays unchanged | Creating a computer from an image does not change the image | | Windows | The computer's base image is `debian/13`. To run Windows inside a computer with KVM enabled, use [Hoody VM](/kit/vm/) | ## API calls | Call | What it does | |---|---| | [`GET /api/v1/images/public`](/api/computer-images/#get-apiv1imagespublic) | Browse available images | | [`GET /api/v1/images/public/{id}`](/api/computer-images/#get-apiv1imagespublicid) | Get image details | | [`GET /api/v1/images/{id}/icon`](/api/computer-images/#get-apiv1imagesidicon) | Download image icon | | [`GET /api/v1/images/user`](/api/computer-images/#get-apiv1imagesuser) | List imported/purchased images | | [`POST /api/v1/images/import/{id}`](/api/computer-images/#post-apiv1imagesimportid) | Import free image | | [`POST /api/v1/images/purchase/{id}`](/api/computer-images/#post-apiv1imagespurchaseid) | Purchase paid image | | [`POST /api/v1/images/rate/{id}`](/api/computer-images/#post-apiv1imagesrateid) | Rate image (0-5 stars) | ## Image fields | Property | Description | Example Values | |----------|-------------|----------------| | **OS** | Operating system | debian | | **Release** | Version/release | 13 | | **Architecture** | CPU architecture | amd64 | | **Size** | Disk space required | about 500 MB | | **Price** | Cost in USD | 0 (free); a paid image shows its USD price | | **Rating** | Community rating | 0.0 - 5.0 stars | | **Variant** | Special configuration | default | The details of one image (`GET /api/v1/images/public/{image_id}`) answer: ```json { "statusCode": 200, "message": "Computer image details retrieved successfully", "data": { "id": "63a3e4b5c6d7e8f9a0b1c2d3", "alias": "debian/13", "description": "Debian 13 (Trixie)", "image_name": "debian/13", "architecture": "amd64", "os": "debian", "release": "13", "serial": "20250809", "variant": "default", "size": 524288000, "price": 0, "added_date": "2023-11-09T00:00:00.000Z", "average_rating": 4.8, "rating_count": 1247, "icon_url": "/api/v1/images/63a3e4b5c6d7e8f9a0b1c2d3/icon" } } ``` Use the details to check the size for storage planning, read the description for pre-installed software and see community ratings for quality. ## Marketplace filters | Query parameter | Filters by | |---|---| | `os` | Operating system (`debian`) | | `architecture` | CPU architecture (amd64, arm64, armhf) | | `min_price` / `max_price` | Price range | | `min_rating` | Minimum rating | | `search` | Keyword, matched against the image's alias, name and description | | `sort_by` / `sort_order` | Sort order of the results | | `max_rating` | Maximum rating; ratings run from 0 to 5 | | `page` / `limit` | Page of results: pages start from 1, and a page holds up to 100 images (default 20). Your library (`GET /api/v1/images/user`) pages the same way; `hoody images list --mine` lists it | ### Sort by rating ```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.com/api/v1/images/public?sort_by=rating&sort_order=desc&limit=10" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` Lists the ten highest-rated public images. ### 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.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" ``` Each link filters the public marketplace to a different price range. ## Architectures An image's `architecture` field (from `GET /api/v1/images/public`) shows which CPU it targets. A create names only `debian/13`, and the computer gets its server's architecture automatically, so there is nothing to match. The values mean: | Architecture | Processors | Notes | |---|---|---| | `amd64` (x86-64) | Standard Intel and AMD processors | The most common value | | `arm64` (ARM 64-bit) | ARM processors, such as Apple Silicon, AWS Graviton, and Raspberry Pi 4 and later | 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 | ## Variants The `variant` field names an image's configuration of its OS version. `debian/13` shows `default`, the default full-featured configuration for general use. Specify the image by its alias (`debian/13`). 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. ## Ratings | Rating | Meaning | |---|---| | 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) | | Rule | Detail | |---|---| | Which images | Only an image in your library: rating any other answers `404` "You do not have access to this image". Import a free image first | | Value | A whole number from 0 to 5; a fraction answers `422` `REQUEST_SCHEMA_INVALID` | | Rating again | Replaces your earlier rating of that image | ## Responses An import answers: ```json { "statusCode": 200, "message": "Free computer image imported successfully", "data": {} } ``` The image is now in your library (`GET /api/v1/images/user`). A purchase answers with the price paid and, when your credentials may read the wallet balance, your remaining balance: ```json { "statusCode": 200, "message": "Computer image purchased successfully", "data": { "price_paid": 15, "remaining_balance": 485 } } ``` ## Docker hosts | What works inside a computer | | |---|---| | Docker daemon | Runs inside the computer | | Docker Compose and Docker Buildx | Included in the dev kit | | Docker images | Building and running them | | Docker networking and volumes | Work as usual | | Resource limits | `--memory` and `--cpus`, and `--privileged` Docker containers | | Multi-container applications | Via Docker Compose | Use `debian/13` as the base image when running Docker. In the Hub, open **Computers**, choose **Get a computer**, select your project and server, and open **More options**. Under **Software**, turn on **Hoody kit** and **Developer kit**, then choose **Get computer**. For the HTTP request below, replace `{id}` with your project ID and `{server_id}` with your server ID ([create a computer](/foundation/computers/create-edit-delete/#image-selection)). ```http POST /api/v1/projects/{id}/computers { "name": "docker-host", "server_id": "{server_id}", "computer_image": "debian/13", "hoody_kit": true } ``` Why Debian: it is stable enough for long-running Docker daemons, its Docker packages are well supported, it has minimal conflicts with container runtimes, and it is well tested in production environments. With the dev kit enabled, Docker is installed and starts when a Docker command first connects to it. After restarting the computer, run `docker ps` to activate Docker; Docker containers using `--restart=always` also wait for this activation. You can use it for single containers, Docker Compose stacks, or a full orchestration platform. The dev kit is on by default when `hoody_kit` is true, unless you set `dev_kit: false`. The nesting is Hoody computer, then Docker daemon, then your application containers: an HTTP-accessible Linux machine that can itself run containerized applications. ## Kubernetes and Podman Kind, Minikube and K3s each run a full Kubernetes cluster inside a Hoody computer. Each one needs a short setup, shown below. Start from a computer created with the dev kit enabled so Docker is already there for Kind and Minikube. ### Kind Kind runs each Kubernetes node as a Docker container, so it uses the Docker that the dev kit installs. It needs no extra settings. 1. Install the `kind` release binary from [Kind's Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start/#installing-from-release-binaries), and `kubectl` from [the Kubernetes install guide](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/). 2. Create the cluster and check it: ```bash kind create cluster kubectl get nodes ``` The node reports `Ready` after about 20 seconds. `kind delete cluster` removes it. ### K3s K3s needs one kubelet setting before you install it. Without it, the K3s service restarts in a loop and the log shows `open /dev/kmsg: no such file or directory`. ```bash sudo mkdir -p /etc/rancher/k3s sudo tee /etc/rancher/k3s/config.yaml >/dev/null <<'EOF' kubelet-arg: - "feature-gates=KubeletInUserNamespace=true" EOF curl -sfL https://get.k3s.io | sudo sh - sudo k3s kubectl get nodes ``` The node reports `Ready` after about 10 seconds. A K3s server uses about 600 MB of memory, so give the computer enough for it plus your workloads. To remove K3s, run `/usr/local/bin/k3s-uninstall.sh`. ### Minikube Minikube runs its node as a Docker container, like Kind. Install `minikube` from [Minikube's Get Started page](https://minikube.sigs.k8s.io/docs/start/) and `kubectl` as for Kind, then start it with the Docker driver and the Docker container runtime: ```bash minikube start --driver=docker --container-runtime=docker kubectl get nodes ``` Pass `--container-runtime=docker` every time: with Minikube's default runtime, containerd, no control-plane pod starts. Right after `minikube start`, give the cluster a few seconds before your first `kubectl run`: until the default service account exists, it fails with `serviceaccount "default" not found`. ### Podman Install Podman from Debian: ```bash sudo apt-get install -y podman slirp4netns ``` As root, Podman works as installed. To run Podman as the default user (rootless), use the `slirp4netns` network, because the default rootless network does not start in a Hoody computer. Make it the default once: ```bash mkdir -p ~/.config/containers cat > ~/.config/containers/containers.conf <<'EOF' [network] default_rootless_network_cmd = "slirp4netns" EOF podman run --rm docker.io/library/alpine wget -qO- https://example.com ``` Or pass `--network=slirp4netns` on each `podman run`. ## Choosing an image | Workload | Image | Then | |---|---|---| | Web application stack (Node.js) | `debian/13` | Install Node.js over the terminal URL or SSH | | Database computer (PostgreSQL) | `debian/13` | Install PostgreSQL with apt | | The same application on AMD64 servers (Intel and AMD) and ARM64 servers (Graviton, Apple Silicon) | `debian/13` on both | Nothing: the architecture follows the target server automatically | ## Practices | Practice | Why | |---|---| | Name the exact image | Name `debian/13` rather than a bare `debian`, so a script keeps working if the default changes | | Use `debian/13` for Docker hosts | When running Docker or Kubernetes inside a computer, start with `debian/13`. Its Docker packages are well supported and it conflicts less with container runtimes | | Importing does not prepare a create | A create accepts only `debian/13`, whatever your library holds, so importing an image first does not speed up later creations | ## Common questions | Question | Answer | |---|---| | What happens if I import an image I already have? | The API returns `400 Bad Request` with the message `You already have this image`. Re-importing is not idempotent, and you do not need to: skip the import step for an image you own. Importing a paid image answers `404` `Free computer image not found`: buy it instead | | Do purchased images work on all my servers? | A purchase is tied to your account, not to one server, so it stays in your library on all of them. Computer creation still accepts only `debian/13` | | Can I roll back to a previous image version? | No. The platform carries one release, `debian/13`. To return to a known state, [snapshot](/foundation/computers/snapshots/) a working computer and copy from that snapshot | | How do I know which image to use for my application? | Use `debian/13`. Check that the packages your application needs are in Debian's repository | | Do I need to match the image's architecture to the server? | No. A create names only `debian/13`, and the computer gets its server's architecture automatically. The `architecture` filter (`GET /api/v1/images/public?architecture=amd64`, or `?architecture=arm64`) only narrows the marketplace list | | Do images affect computer pricing? | Computers are not charged separately. A premium marketplace image has its listed purchase price | ## Troubleshooting | Symptom | Cause | What to do | |---|---|---| | Computer creation fails with "image not found", or returns `400 Invalid base image` | Not a lookup failure: the name is not a base image enabled for the realm. The error lists what is: `debian/13` | Name the canonical `debian/13`; `debian:13`, `debian-13`, `debian 13` and `debian` also resolve to it. Importing the image or finding it in your library does not help, because a create accepts only base images | | Image purchase fails with insufficient funds: `400` "Insufficient balance" | The wallet balance is below the price | Check the wallet balance, add funds if needed, then purchase (below) | | Image purchase answers `403` | An auth token without the `financial.wallet.transfer` permission ("This token does not have permission to spend wallet funds"), or a caller that is neither the signed-in account owner nor an auth token | Buy signed in as the account owner, or with an auth token that has `financial.wallet.transfer` | | Computer takes longer than expected to create | Creation time varies; some creates take a few minutes | Nothing: this is normal | Check your General Balance with `hoody wallet balances general get` (`GET /api/v1/wallet/balances` lists every balance). If it is short, [add funds](/foundation/wallet/#add-funds). Then buy with `hoody images buy IMAGE_ID` (`POST /api/v1/images/purchase/{image_id}`); `hoody images list` shows the ID. Before buying again, check your library with `GET /api/v1/images/user`: a purchase of an image you already own is refused with `400`, the same status as an insufficient balance.