Build an image

Build a Dockerfile or steps in a Space as pinned checkpoints that Spaces fork from, with a content-hash layer cache.

The call behind cua build: each filesystem step is a pinned checkpoint, a rebuild runs only what changed, and Spaces.fork(tag, name) or SpaceCreateOptions.build starts a Space from the result. See Build an image from a Dockerfile.

Build#

Methods of Spaces.

`Spaces.build`#

Builds an image from a Dockerfile or steps in a Space, as pinned layer checkpoints on this machine. Layers already built are reused (a rebuild of the same recipe is a cache hit that runs nothing; a changed step rebuilds from it on), and identical builds in flight share one run. The result's checkpoint is a fork source: Spaces.fork(result.tag or result.checkpoint, name) starts a Space from it in well under a second, with the image's environment, working directory and user. A failed step is an error that names the step, its exit code and its last output; earlier layers stay cached.

async def build(self, options: BuildOptions) -> BuildResult

Parameter	Type	Default
`options`	`BuildOptions`	required

Returns BuildResult · Async · Raises CuaError

`Spaces.build_with_progress`#

Spaces.build, reporting each step and the lines it prints to listener as they happen.

async def build_with_progress(self, options: BuildOptions, listener: BuildListener) -> BuildResult

Parameter	Type	Default
`options`	`BuildOptions`	required
`listener`	`BuildListener`	required

Returns BuildResult · Async · Raises CuaError

`Spaces.builds`#

The builds on this machine, oldest first, with their tags.

async def builds(self) -> List[BuildInfo]

Returns Vec<BuildInfo> · Async · Raises CuaError

`Spaces.delete_build`#

Deletes a build: its tags and the layer checkpoints no other build uses. build is a tag, a recipe key (or its first 12 characters) or a checkpoint. Returns the checkpoints deleted. Spaces already made from it keep running.

async def delete_build(self, build: str) -> List[str]

Parameter	Type	Default
`build`	`String`	required

Returns Vec<String> · Async · Raises CuaError

`BuildOptions` record#

Options for Spaces.build and super.SpaceCreateOptions.build. Give the recipe as a dockerfile (text) or a base image; steps are applied after it.

Field	Type	Default	Description
`dockerfile`	`Option<String>`	`None`	Dockerfile text. One stage; the instructions `cua build` documents (multi-stage, heredocs, BuildKit flags and `ONBUILD` are refused, naming the line).
`context_dir` / `contextDir`	`Option<String>`	`None`	The build context: the directory `COPY` sources are relative to (`.dockerignore` applies). Default: none, and a `COPY` fails.
`base`	`Option<String>`	`None`	A base image, for a build made of `steps` alone: a Cua image, `ubuntu:<version>`, `debian:<version>` or `python:<version>`.
`steps`	`Vec<BuildStep>`	`[]`	Steps, after the Dockerfile's.
`build_args` / `buildArgs`	`HashMap<String, String>`	`[:]`	Build arguments (`ARG` values).
`tag`	`Option<String>`	`None`	An alias for the result: `Spaces.fork`, `build:<tag>` images and `Spaces.create(build=...)` find the build by it.
`kind`	`Option<String>`	`None`	`vm` (default), `container` or `microvm`.
`on`	`Option<String>`	`None`	Where: `local` (default). A build's checkpoints stay on the machine that took them.
`cpus`	`Option<u32>`	`None`	vCPUs of the build's machine, and so of Spaces made from it (default 2).
`memory_mb` / `memoryMb`	`Option<u64>`	`None`	Memory in MiB (default 4096).
`headless`	`Option<bool>`	`None`	No desktop: only cua-spacesd runs (default true).
`no_cache` / `noCache`	`bool`	`false`	Build every layer again instead of using cached ones.
`step_timeout_ms` / `stepTimeoutMs`	`Option<u64>`	`None`	Budget for each step in milliseconds (default one hour).

`BuildStep` enum#

One build step. Values are literal: a Dockerfile's $VARs are expanded by BuildOptions.dockerfile's parser, not here. Run and Copy steps run as the User, in the Workdir and with the Env set before them.

BuildStep.RUN(command: str)
BuildStep.RUN_EXEC(argv: List[str])
BuildStep.COPY(sources: List[str], dest: str, owner: Optional[str], mode: Optional[str], unpack: bool)
BuildStep.ENV(vars: dict[str, str])
BuildStep.WORKDIR(path: str)
BuildStep.USER(user: str)
BuildStep.EXPOSE(ports: List[str])
BuildStep.CMD(argv: List[str])
BuildStep.ENTRYPOINT(argv: List[str])
BuildStep.SHELL(argv: List[str])
BuildStep.LABEL(labels: dict[str, str])
BuildStep.VOLUME(paths: List[str])
BuildStep.STOP_SIGNAL(signal: str)
BuildStep.HEALTHCHECK(text: str)

Variant	Description
`Run`	A shell command line (`/bin/sh -c`, or the last `Shell`). Fields: `command: String`
`RunExec`	A command and arguments, run without a shell. Fields: `argv: Vec<String>`
`Copy`	Files of the build context copied in (`COPY`; `unpack`: `ADD`). Fields: `sources: Vec<String>`, `dest: String`, `owner: Option<String>`, `mode: Option<String>`, `unpack: bool`
`Env`	Environment for later steps and for commands run in the image. Fields: `vars: HashMap<String, String>`
`Workdir`	The working directory (created when missing). Fields: `path: String`
`User`	The user later steps and the image's commands run as. Fields: `user: String`
`Expose`	Ports the image listens on. Fields: `ports: Vec<String>`
`Cmd`	The image's default command. Fields: `argv: Vec<String>`
`Entrypoint`	The image's entrypoint. Fields: `argv: Vec<String>`
`Shell`	The shell `Run` uses. Fields: `argv: Vec<String>`
`Label`	Image labels. Fields: `labels: HashMap<String, String>`
`Volume`	Volume mount points. Fields: `paths: Vec<String>`
`StopSignal`	The stop signal. Fields: `signal: String`
`Healthcheck`	The health check, as written. Fields: `text: String`

`BuildResult` record#

The result of Spaces.build.

Returned by Spaces.build, Spaces.build_with_progress.

Field	Type	Description
`checkpoint`	`String`	The final layer's checkpoint: `Spaces.fork` and `cua sb fork` start Spaces from it.
`tag`	`Option<String>`	The tag, when one was asked for.
`key`	`String`	The recipe's cache key.
`cached`	`bool`	Every layer was cached: nothing ran.
`steps`	`Vec<BuildStepResult>`	One per step, base first.
`config`	`BuildImageConfig`	What commands run in the image get.
`seconds`	`f64`	Seconds the build took.

`BuildStepResult` record#

One step of a finished build.

Field	Type	Description
`index`	`u32`	The step (0: the base image).
`text`	`String`	The step as a line (`RUN make`).
`cached`	`bool`	Served from a cached layer: nothing ran.
`seconds`	`f64`	Seconds it took (0 when cached).
`checkpoint`	`Option<String>`	The layer's checkpoint, for a step that makes one.

`BuildImageConfig` record#

What an image configures for commands run in it.

Field	Type	Description
`base`	`String`	The `FROM` reference.
`env`	`HashMap<String, String>`	Environment from `ENV` steps.
`workdir`	`Option<String>`	Working directory, when a step set one.
`user`	`Option<String>`	User, when a step set one.
`driver_user` / `driverUser`	`String`	The user cua-spacesd runs as in the image.
`cmd`	`Option<Vec<String>>`	Default command.
`entrypoint`	`Option<Vec<String>>`	Entrypoint.
`shell`	`Option<Vec<String>>`	The shell `Run` used.
`exposed`	`Vec<String>`	Exposed ports.
`labels`	`HashMap<String, String>`	Labels.
`volumes`	`Vec<String>`	Volumes.
`stop_signal` / `stopSignal`	`Option<String>`	Stop signal.
`healthcheck`	`Option<String>`	Health check, as written.

`BuildInfo` record#

A build on this machine (Spaces.builds).

Returned by Spaces.builds.

Field	Type	Description
`checkpoint`	`String`	The final layer's checkpoint.
`key`	`String`	The recipe's cache key.
`tags`	`Vec<String>`	Tags naming it.
`base`	`String`	The `FROM` reference.
`layers`	`Vec<String>`	Layers it is made of (checkpoints), base first.
`created_at` / `createdAt`	`String`	RFC 3339 build time.
`config`	`BuildImageConfig`	Image configuration.

`BuildProgress` record#

What a build is doing (Spaces.build_with_progress).

Field	Type	Description
`event`	`String`	`note`, `step`, `output`, `step_done` or `finished`.
`index`	`u32`	The step (0: the base image).
`total`	`u32`	Steps after the base.
`text`	`String`	The step as a line, a note, or an output line.
`cached`	`bool`	`step`: served from a cached layer. `finished`: nothing ran.
`seconds`	`f64`	`step_done` and `finished`: seconds taken.
`checkpoint`	`String`	`step_done`: the layer's checkpoint.

`BuildListener`#

Receives BuildProgress while Spaces.build_with_progress runs, in order, ending with finished. Called on an SDK worker thread; return quickly.

You implement BuildListener and pass it to the SDK (a callback interface): subclass it in Python, implement the interface in TypeScript, the BuildListener protocol in Swift, the interface in Kotlin and the trait in Rust.

Method	Description
`on_progress`	The build moved on.

`BuildListener.on_progress`#

The build moved on.

def on_progress(self, progress: BuildProgress) -> None

Parameter	Type	Default
`progress`	`BuildProgress`	required

All items#

8 items, across this page and its subpages, grouped by page (each item's section is on its page). Methods are listed on their object.

Build an image: BuildImageConfig, BuildInfo, BuildListener, BuildOptions, BuildProgress, BuildResult, BuildStep, BuildStepResult

Build an image

Build#

Spaces.build#

Spaces.build_with_progress#

Spaces.builds#

Spaces.delete_build#

BuildOptions record#

BuildStep enum#

BuildResult record#

BuildStepResult record#

BuildImageConfig record#

BuildInfo record#

BuildProgress record#

BuildListener#

BuildListener.on_progress#