{
    "product": "Cenvero Stratum",
    "generated_at": "2026-10-10T15:58:07+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "compute/images",
            "title": "Images",
            "category": "Compute",
            "url": "https://www.stratum.cenvero.com/docs/compute/images",
            "headings": [
                {
                    "level": 1,
                    "text": "Images"
                },
                {
                    "level": 2,
                    "text": "Which images work"
                },
                {
                    "level": 2,
                    "text": "Registering an image"
                },
                {
                    "level": 2,
                    "text": "Listing, showing and deleting"
                },
                {
                    "level": 2,
                    "text": "Over the API"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 904,
            "markdown": "# Images\n\nA virtual machine starts from a **base image**: a Linux cloud image registered\nonce on the node. Each machine gets its own disk layered on top of the image, so\nmany machines can share one image and the image itself never changes.\n\n> Part of [Compute](/docs/compute/overview), in early access.\n\n## Which images work\n\n- **Linux cloud images** that configure themselves on first boot with\n  cloud-init from a \"NoCloud\" data source — the official cloud images of Debian\n  (\"genericcloud\"), Ubuntu, and most other distributions. The first-boot\n  configuration arrives on a small read-only disk labelled `cidata`\n  ([what it contains](/docs/compute/virtual-machines#first-boot)).\n- **Formats:** qcow2 or raw. A raw image is converted to qcow2 on the way in.\n- **Self-contained files only.** An image that refers to a backing file or keeps\n  its data in a separate file is refused, as is an encrypted one.\n- **Up to 50 GiB** per image file.\n- **x86_64** guests (see [Current limits](/docs/compute/limits)).\n\nImages that do not run cloud-init still boot, but nothing inside them is set up\nfor you: give them their address yourself, or turn on DHCP for their network.\n\n## Registering an image\n\nFrom an `http://` or `https://` URL — the SHA-256 is required, and the image\ncannot be used unless the download matches it:\n\n```bash\nsudo cenvero-str-ctl image register --name debian-13 \\\n  --url https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2 \\\n  --sha256 <sha256 of that file> --wait\n```\n\nMost distributions publish checksums next to their images. Debian publishes\nSHA-512 sums: download the image once, check it against them, and use\n`sha256sum` on the same file for the value above.\n\nOr copy a file that is already on the node, from any directory (the SHA-256 is\nthen optional, and checked when given):\n\n```bash\nsudo cenvero-str-ctl image register --name cirros --path /root/cirros-0.6.3-x86_64-disk.img --wait\n```\n\nThe command opens the file itself and hands the open file to the agent, which\ncopies and checks it exactly like a download — so a file in your home directory\nor a temporary directory works too. The path must name a regular file — not a\nlink, directory, device or pipe. Copying from a path is only possible on the\nnode's own command line, never over the API.\n\nRegistration runs in the background. `--wait` waits until the image is `ready`\n(or `failed`, with the reason); without it the command returns at once and the\nimage shows as `downloading`. At most two images are fetched at a time.\n\nThe image name may use letters, digits, `.`, `_` and `-` (up to 64 characters,\nstarting with a letter or digit) and must be unique on the node.\n\n## Listing, showing and deleting\n\n```bash\ncenvero-str-ctl image list\ncenvero-str-ctl image show img-3f9a1c2e\nsudo cenvero-str-ctl image delete img-3f9a1c2e\n```\n\n```json\n{\n  \"image\": {\n    \"id\": \"img-3f9a1c2e\",\n    \"name\": \"debian-13\",\n    \"state\": \"ready\",\n    \"sha256\": \"5754395abffb1d384d50f6d0945d46d1beb7be42a7e786e4fc4a6f27270ab16f\",\n    \"format\": \"qcow2\",\n    \"source_format\": \"qcow2\",\n    \"virtual_size\": 3221225472,\n    \"file_size\": 340983808,\n    \"source_url\": \"https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2\",\n    \"created_at\": \"2026-09-28T09:14:02Z\"\n  }\n}\n```\n\n| `state` | Meaning |\n|---|---|\n| `downloading` | Being fetched or copied, checked and converted |\n| `ready` | Machines can be created from it |\n| `failed` | See `error` (a checksum mismatch, a refused format, a download error, …). The partial file is gone; delete the entry and register again |\n\nAn image cannot be deleted while any machine's disk is made from it (the error\nnames those machines), nor while it is still downloading. An image that was\nstill downloading when the node restarted is marked `failed` — register it again.\n\n`virtual_size` is the size of the disk inside the image, in bytes: a machine's\ndisk can never be smaller than that.\n\n## Over the API\n\n```bash\n# register from a URL (202: it downloads in the background)\ncurl -k -X POST \"$NODE/api/v1/images\" -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"debian-13\",\"url\":\"https://…/debian-13-genericcloud-amd64.qcow2\",\"sha256\":\"<hex>\"}'\n\ncurl -k \"$NODE/api/v1/images\" -H \"Authorization: Bearer $TOKEN\"\ncurl -k \"$NODE/api/v1/images/img-3f9a1c2e\" -H \"Authorization: Bearer $TOKEN\"\ncurl -k -X DELETE \"$NODE/api/v1/images/img-3f9a1c2e\" -H \"Authorization: Bearer $TOKEN\"\n```\n\nRegistering from a path on the node is refused over the API.\n\nThe registration answers with the **task** that brings the image in (`\"task\"`).\nIts progress is in bytes — of the size the server announces, when it does — and\nit can be stopped while it runs; the image is then marked failed, and you delete\nit or register it again:\n\n```bash\ncurl -k \"$NODE/api/v1/tasks/{task}\" -H \"Authorization: Bearer $TOKEN\"\ncurl -k -X POST \"$NODE/api/v1/tasks/{task}/cancel\" -H \"Authorization: Bearer $TOKEN\"\nsudo cenvero-str-ctl task log {task} --follow     # the same on the node\n```\n\nAt most two images come in at a time; a third waits (its task reads `queued`).\nA download the agent was in the middle of when it restarted is marked failed\n(\"interrupted; register it again\"), and so is its task.\n\n**A note on download addresses.** Image downloads may not connect to loopback,\nlink-local or unspecified addresses. Private addresses are allowed, so you can\nkeep images on a mirror inside your network — which also means anyone holding an\noperator API token can make the node fetch from your internal network.\n\n## See also\n\n- [Creating virtual machines](/docs/compute/virtual-machines)\n- [Current limits](/docs/compute/limits)\n"
        }
    ]
}