Dockyard

Dockyard is the catalog of official images a Dock can start from. The images are built from source in usedock/docklet. Control plane hosts serve only ubuntu-24.04 today; the other images become usable as hosts learn to serve Dockyard images. The dock CLI's local engine boots any of them directly on an amd64 machine.

Images

No image has a coding agent baked in. Bring any agent and install it in the environment setup script (see Concepts).

List images

GET /v1/images returns the catalog. Any authenticated caller can read it.

curl -sS "$DOCK_URL/v1/images" \
  -H "Authorization: Bearer $DOCK_API_KEY"

{
  "ok": true,
  "data": [
    {
      "name": "ubuntu-24.04",
      "description": "Minimal Ubuntu 24.04: systemd, openssh-server, Docker, git, curl, python3",
      "arch": ["amd64"],
      "sizeMiB": 2048,
      "contents": "Ubuntu 24.04 with systemd, openssh-server, Docker, git, curl and python3",
      "available": true
    }
  ]
}

available is true when an online host serves the image. Hosts do not report which images they hold yet, so today only ubuntu-24.04 shows as available, and only while at least one host is online.

Create a Dock from an image

dock new --image ubuntu-24.04

Over the API, send image in POST /v1/docks. An image that is not in the catalog is refused with 400 image_unknown; the message lists the valid names. A catalog image is accepted even when available is false. Each host that does not serve it is skipped, and when no host is left the call fails with 400 image_unavailable and the Dock is left in the error state.

A branch (POST /v1/docks/{id}/branch) copies its source's disk, so it keeps the source's image; sending a different image is refused with 400 validation_error.

Images on your machine

With the dock CLI's local engine, dock images lists the Dockyard images for your machine's architecture, with their size and whether they are already downloaded:

dock images
dock images pull ubuntu-24.04

dock images pull <name> downloads an image into the local cache so the first dock new does not have to. The local engine boots the image directly with its own kernel. Each image file is checked against its size and SHA-256 in the Dockyard index.

The dock binary pins the Dockyard release and the SHA-256 of its dockyard.json index, and refuses an index that does not match. dock v0.2.0 pins the images-2026.10.11 release, whose files are also signed with cosign. Images are amd64 only today, so dock images lists nothing on an arm64 machine. DOCK_DOCKYARD_URL points the CLI at another index; it is then unpinned, the CLI warns, and the index is verified only when DOCK_DOCKYARD_SHA256 is also set.