Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

Register a custom image

You're going to register your own image from an OCI reference (for example docker.io/r-base:4.4), wait for ScaiBunker to build and scan it, make it available to your workers, and then create a bunker from it.

Roughly 5 minutes, plus the build time: under a minute for small images, a few minutes for large ones.

How a custom image is built#

You don't upload a disk image, and your workers never pull from a registry. ScaiBunker's build service takes your reference (or your uploaded archive) and:

  1. pulls the image (linux/amd64 only), or unpacks your archive, and checks every layer against its digest;
  2. flattens the layers into one root filesystem, dropping anything unsafe (device files, paths that escape the filesystem);
  3. builds an ext4 disk sized to the content (25% plus 128 MiB headroom);
  4. boots it in a Firecracker microVM without network to check it starts and has a shell;
  5. scans it for known vulnerabilities and records a software bill of materials;
  6. publishes it, after which your workers import the checked image.

The image is refused if:

  • it has no /bin/sh (for example distroless or scratch images): bunkers need a shell;
  • the scan finds a critical vulnerability that has a fix available: rebuild it from an updated base;
  • it's private and ScaiBunker has no login for its registry (see Private registries), or the login is refused;
  • it's larger than 20 GiB once flattened.

Because the scan happens here, on the way in, ScaiBunker doesn't re-scan the image later. A new version of your image is a new registration, with its own build and scan.

1. Decide the image's shape#

Settle these before the API call:

  • Source. {"kind": "oci", "ref": "docker.io/r-base:4.4"}. Pin a tag or a digest (...@sha256:…); the build uses whatever the reference points at when it runs. For an image that isn't in any registry, upload it instead: see Upload an archive.
  • Defaults. default_cpu_millicores, default_memory_mb, default_disk_mb are applied when a caller creates a bunker from this image without overriding. Set them to a sensible "this image needs at least this to function" floor.
  • Scope. tenant (default) — only this tenant sees it. partner — every tenant under your partner (needs a partner admin).

You need scaibunker:images:manage to register a new image.

2. Register the image#

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X POST "$SCAIGRID_HOST/v1/modules/scaibunker/images" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "r-stats",
    "display_name": "R 4.4",
    "description": "R statistical computing environment.",
    "build_source": {"kind": "oci", "ref": "docker.io/r-base:4.4"},
    "default_cpu_millicores": 2000,
    "default_memory_mb": 4096,
    "default_disk_mb": 8192
  }'
python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import httpx, os

H = {"Authorization": f"Bearer {os.environ['SCAIGRID_API_KEY']}"}
HOST = os.environ["SCAIGRID_HOST"]

image = httpx.post(
    f"{HOST}/v1/modules/scaibunker/images",
    headers=H,
    json={
        "name": "r-stats",
        "display_name": "R 4.4",
        "build_source": {"kind": "oci", "ref": "docker.io/r-base:4.4"},
        "default_cpu_millicores": 2000,
        "default_memory_mb": 4096,
        "default_disk_mb": 8192,
    },
).json()["data"]
print(image["id"], image["build_status"])  # -> queued
javascript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
const HOST = process.env.SCAIGRID_HOST;
const H = { "Authorization": `Bearer ${process.env.SCAIGRID_API_KEY}` };

const res = await fetch(`${HOST}/v1/modules/scaibunker/images`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "r-stats",
    display_name: "R 4.4",
    build_source: { kind: "oci", ref: "docker.io/r-base:4.4" },
    default_cpu_millicores: 2000,
    default_memory_mb: 4096,
    default_disk_mb: 8192,
  }),
});
const { data: image } = await res.json();
console.log(image.id, image.build_status); // -> queued

Names are unique per scope; reusing one returns 409 IMAGE_NAME_CONFLICT. Any other source kind returns 422 IMAGE_SOURCE_UNSUPPORTED.

Private registries#

To build from a private registry, store a login for it once. ScaiBunker uses it only when building your images, sends it only to that registry, and never returns it:

bash
1
2
3
4
curl -X POST "$SCAIGRID_HOST/v1/modules/scaibunker/registry-credentials" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host": "ghcr.io", "username": "my-bot", "password": "'"$GHCR_READ_TOKEN"'"}'

host is the registry part of your references (ghcr.io, registry.example.com:5000; Docker Hub is docker.io). Use a read-only token. From then on, register images from that registry as usual; the build logs in by itself. Change the token with PATCH /registry-credentials/{id}, remove it with DELETE. A refused login fails the build with registry refused the stored credentials.

Upload an archive#

For an image that isn't in a registry, upload the output of docker save (or an OCI image layout as a tar, optionally gzipped) holding exactly one linux/amd64 image:

bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
docker save my-app:1 -o my-app.tar
SIZE=$(stat -c %s my-app.tar)

RESP=$(curl -s -X POST "$SCAIGRID_HOST/v1/modules/scaibunker/images" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "build_source": {"kind": "archive", "size_bytes": '"$SIZE"'}}')
IMAGE_ID=$(echo "$RESP" | jq -r .data.id)

# up to 5 GiB: one PUT to the upload URL (valid 1 hour)
curl -X PUT --upload-file my-app.tar "$(echo "$RESP" | jq -r .data.upload.url)"

curl -X POST "$SCAIGRID_HOST/v1/modules/scaibunker/images/$IMAGE_ID/upload/complete" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" -H "Content-Type: application/json" -d '{}'

The image is uploading until you call upload/complete, then the build runs as for a reference. Above 5 GiB the response holds upload.multipart instead: send each part_size slice to its part URL and pass the parts' ETags to upload/complete ({"parts": [{"part_number": 1, "etag": "…"}]}). Expired URLs can be renewed with GET /images/{id}/upload. Finish within 24 hours, or the image fails and the upload is deleted; the archive is also deleted once the build ends.

3. Wait for the build#

Poll the image until build_status is ready or failed:

bash
1
2
curl "$SCAIGRID_HOST/v1/modules/scaibunker/images/$IMAGE_ID" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"
  • uploading — waiting for your archive (archives only).
  • queued — waiting for the build service.
  • building — being built.
  • ready — built, scanned and published.
  • failed — build_error says why, for example image has no /bin/sh, fixable CRITICAL vulnerabilities or pull failed: …. Fix the cause and register again under a new name.

Creating a bunker from an image that isn't ready returns 409 IMAGE_NOT_READY.

Once the image is ready, scan_status shows the result of its build scan within a couple of minutes: passed (no critical or high findings) or failed (high findings, which are reported but don't block the image), with the counts in scan_report.

4. Make it available to your workers#

Images are imported by the workers in the image's availability groups. If your tenant's images don't sit in a group yet, create one and put the image in it:

python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
group = httpx.post(
    f"{HOST}/v1/modules/scaibunker/availability-groups",
    headers=H,
    json={"name": "stats-tenant-default", "description": "R + Python stats workers"},
).json()["data"]

httpx.post(
    f"{HOST}/v1/modules/scaibunker/availability-groups/{group['id']}/images",
    headers=H,
    json={"ref": image["id"]},
)

A built image in a group is imported automatically. To start or repeat that yourself:

bash
1
2
curl -X POST "$SCAIGRID_HOST/v1/modules/scaibunker/images/$IMAGE_ID/warm" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"

Then watch one row per worker until every row is ready:

bash
1
2
curl "$SCAIGRID_HOST/v1/modules/scaibunker/images/$IMAGE_ID/cache" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"

5. Create a bunker from the new image#

Reference the image by name or id. The scheduler picks a worker that has it.

bash
1
2
3
4
5
6
7
8
curl -X POST "$SCAIGRID_HOST/v1/modules/scaibunker/bunkers" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "r-stats",
    "lifecycle_mode": "ephemeral",
    "network_profile": "registry"
  }'

If no worker has the image yet, the call fails with NO_SUITABLE_WORKER: wait for step 4 to finish.

6. Deactivate when retiring#

bash
1
2
curl -X DELETE "$SCAIGRID_HOST/v1/modules/scaibunker/images/$IMAGE_ID" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"

Deactivation is a soft delete: existing bunkers keep running, but new bunkers can't be created from it. ScaiBunker also removes the image from your workers within a minute; each worker frees the disk once the last bunker on the image ends.

Done#

Your image is built, checked, scanned and ready. To update it, register the new version under a new name; there's no in-place update, so each version keeps its own build and scan.

Updated 2026-11-17 10:07:48 View source (.md) rev 43