---
title: "Build a custom image from a Dockerfile, an OCI image or a recipe."
method: POST
path: "/v1/images"
tags: ["images"]
---

# Build a custom image from a Dockerfile, an OCI image or a recipe.

`POST /v1/images`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/images`
- Auth: HTTP bearer

Returns at once with state queued; poll GET /v1/images/{id}, follow GET /v1/images/{id}/logs?follow=true, or send Prefer: wait=N. The build runs in its own Firecracker guest with the same public-web egress as a sandbox, never on the host. An organization runs one build at a time until it holds credit, bought or given, then four. An identical plan in the same organization, last built by the same builder version, is copied instead of rebuilt, and a build that shares its first steps with an earlier one starts from that build's checkpoint. Building is free; the image's storage is recorded as usage.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `name` string: Your own handle for the resource. Letters, digits, dot, dash, underscore.
  - `labels` object: Your own key/value tags, at most 32. Filter lists with label=key:value.
  - `region` string: Omit for the default region.
  - `tags` string[]: Tags this build takes when it is ready. A named image with none given takes latest.
  - `dockerfile` string: A Dockerfile: multi-stage builds, ARG, COPY --from, heredocs, ADD from a URL. FROM a public or private image, FROM scratch, or FROM runtime for Runtime's own base. COPY reads `files` or `context`.
  - `image` string: An OCI image to use as it is, plus Runtime's guest agent.
  - `recipe` object: Packages, commands and files on top of a base, like Modal's and E2B's builders.
    - `base` string: runtime (default) or an image reference.
    - `apt` string[]
    - `pip` string[]
    - `npm` string[]
    - `commands` string[]
    - `env` object: Environment every process in the image starts with.
    - `files` object[]
      - `path` string, required: Path in the build context (Dockerfile) or in the image (recipe).
      - `content` string, required: The file's content, UTF-8 text or base64.
      - `encoding` 'utf8' | 'base64'
      - `mode` integer: Permission bits, 0 to 0777 (decimal 0 to 511).
    - `workdir` string
  - `files` object[]: A small build context inline, at most 1 MiB in total. Not with context.
    - `path` string, required: Path in the build context (Dockerfile) or in the image (recipe).
    - `content` string, required: The file's content, UTF-8 text or base64.
    - `encoding` 'utf8' | 'base64'
    - `mode` integer: Permission bits, 0 to 0777 (decimal 0 to 511).
  - `context` object: A build context of up to 100 MiB and 20000 files. The SDKs and CLI make it from a folder and its .dockerignore.
    - `archive` object, required: The context as a tar archive (gzip allowed), cut into 1 MiB pieces, each uploaded first with PUT /v1/images/context/{digest}.
      - `sha256` string, required
      - `size` integer, required
      - `chunks` string[], required
    - `files` object[], required: Every regular file in the archive: what COPY resolves against.
      - `path` string, required
      - `sha256` string, required
      - `size` integer, required
      - `mode` integer
  - `dockerignore` string: The context's .dockerignore; excluded files are never copied.
  - `target` string: Build this stage as the image instead of the last one.
  - `buildArgs` object: Environment every process in the image starts with.
  - `env` object: Environment every process in the image starts with.
  - `start` object, nullable: What a sandbox from this image runs as it starts, and when its create answers. A Dockerfile's CMD, ENTRYPOINT and HEALTHCHECK fill it in; null runs nothing.
    - `command` string: A shell command run in the background when a sandbox starts from the image.
    - `argv` string[]
    - `cwd` string: Default: the image's working directory.
    - `env` object: Environment every process in the image starts with.
    - `readyCommand` string: Create returns once this exits 0 (it is retried). Default when readyPort is absent: none.
    - `readyPort` integer: Create returns once something listens on this port in the sandbox.
    - `readyTimeoutSeconds` integer: How long create waits for ready before answering with start.state timeout.
  - `cache` boolean: Start from, and keep, checkpoints of earlier builds of this organization. false builds every step and pulls the base again. A base named by its tag is pinned to the digest it names now either way, so a moved tag is never served from an old pull.
  - `build` object
    - `vcpu` integer
    - `memoryMiB` integer
    - `diskMiB` integer: The build guest's own scratch disk: earlier stages and the context live here. At least 4096 MiB to fit the builder image.
    - `maxImageMiB` integer: The largest the image may be.
    - `timeoutSeconds` integer
    - `cacheMiB` integer: The most the layer cache kept by this build may hold. Default: maxImageMiB, at most 8192.

## Response `200`

Success

- object
  - `id` string, required
  - `kind` 'image', required
  - `status` string, required
  - `state` 'queued' | 'building' | 'ready' | 'failed' | 'deleting' | 'deleted', required
  - `name` string, nullable
  - `version` integer, nullable
  - `tags` string[]
  - `sizeBytes` integer, nullable: The image's whole file, once it is ready. Its storage is charged on this.
  - `sizeMiB` integer, nullable
  - `storedBytes` integer, nullable: The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is.
  - `error` string, nullable
  - `createdAt` string

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)