Skip to main content
POST
/
v1
/
templates
/
plan
Return a backend-neutral template build plan without starting a build
import requests

url = "https://api.13-215-85-171.sslip.io/v1/templates/plan"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
{
  "build_plan": {
    "base_template": "<string>",
    "run_steps": [
      "<string>"
    ],
    "build_steps": [
      {}
    ],
    "build_envs": {},
    "env_assignments": [
      [
        "<string>"
      ]
    ],
    "ignored_instructions": [
      "<string>"
    ],
    "start_cmd": "<string>",
    "default_user": "<string>",
    "default_workdir": "<string>",
    "readiness": {
      "kind": "tcp",
      "port": 3000,
      "timeout_secs": 30,
      "interval_ms": 500,
      "startup_grace_secs": 2
    },
    "ignored_instruction_warnings": [
      {
        "instruction": "<string>",
        "line": 123
      }
    ]
  },
  "warnings": [
    "<string>"
  ],
  "requires_base_image_auth": true,
  "source_digest": "<string>",
  "context_manifest": {
    "context_manifest_id": "<string>",
    "context_digest": "<string>",
    "file_count": 123
  },
  "dockerfile_digest": "<string>"
}

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token

Body

application/json
​
name
string

Template name (falls back to alias, then auto-generated)

​
dockerfile
string

Inline Dockerfile content

​
base_image
string

Base OCI image reference imported directly on the Firecracker path (for example ubuntu:22.04). The importer currently supports raw tar, gzip, and zstd layer media types; regular files, directories, symlinks, and hard links; and Linux OCI User values in user, uid, user:group, user:gid, uid:group, or uid:gid form. OCI special files such as sockets, FIFOs, block devices, and character devices are rejected. For image indexes, the importer prefers exact Firecracker-compatible Linux variants for the current host architecture (amd64/v1 or arm64/v8 / arm64/v8.0) and falls back to a variantless Linux manifest when present; manifests with os.version or non-empty os.features are rejected. Guest boot recreates /dev, /dev/pts, /dev/shm, /proc, and /sys through nullspace-init, so those do not need to come from imported OCI layers.

​
alias
string

Alternative name field used by SDK builders

​
tags
string[]

Tags assigned to the built artifact. Omit this field to use ["default"]; explicit empty arrays are invalid.

​
steps
object[]

Declarative builder steps converted to a Dockerfile server-side

​
build_envs
object

Environment variables available during template build only

​
start_cmd
string

Firecracker template start command executed during template build before snapshotting; sandboxes later restore the snapshotted running state instead of rerunning this command, and create-time env injection is not visible to it

​
build_context
object

Explicit local build context used to satisfy COPY/ADD sources during template builds

​
build_config
object

Optional build VM configuration (vCPUs, memory, internet access)

​
build_backend
enum<string>

Optional template build backend. Dockerfile builds default to BuildKit; declarative and external OCI import inputs use the native backend unless explicitly supported otherwise. Dockerfile input with native is rejected.

Available options:
native,
buildkit
​
dockerfile_path
string

Relative Dockerfile path inside the uploaded build context for BuildKit builds.

​
build_args
object

Safe-to-persist Dockerfile build arguments for BuildKit builds.

​
build_target
string

Optional Dockerfile target stage for BuildKit builds.

​
runtime_config
object

Firecracker-only runtime defaults baked into the built template

​
base_image_auth
object

Optional credentials for authenticated external OCI base-image imports. Applies to explicit base_image imports and Dockerfile builds that resolve to exactly one external non-template FROM image. Authenticated Dockerfile-backed imports currently reject variable-based FROM, alias-based imported stages, and multiple external registry hosts.

​
registry_auth
object[]

Optional per-registry request-time credentials for BuildKit Dockerfile pulls. Each registry must match a registry host used by the Dockerfile or base image. Secret values are forwarded only to the build worker and are not stored in durable build records.

​
build_secrets
object[]

Optional request-time BuildKit secrets exposed to Dockerfile RUN --mount=type=secret instructions. Supported only by the BuildKit backend. Values are forwarded only to the build worker and are not persisted in durable build records, cache keys, or context manifests.

​
skip_cache
boolean

Firecracker-only whole-build cache bypass

​
claim_token
string

Optional reserved template-name claim token

Response

Build plan summary

​
build_backend
enum<string>
required

Template build backend. native is retained for declarative/OCI build requests and historical filters; Dockerfile build requests use buildkit.

Available options:
native,
buildkit
​
source_type
enum<string>
required
Available options:
declarative,
dockerfile,
oci_import,
template_base
​
build_plan
object
required

Normalized build plan derived from the template source (Dockerfile or steps).

​
warnings
string[]
required
​
requires_base_image_auth
boolean
required
​
source_digest
string
​
context_manifest
object
​
dockerfile_digest
string