bldr pod

bldr pod

Pods: docker/podman-style container sandboxes for testing images (CID in, stdout/stderr + a diff CID out). Not the way to build things

bldr [BLDR FLAGS] pod <COMMAND>

bldr pod create

Create a pod without starting it. Prints the pod id

bldr [BLDR FLAGS] pod create [CREATE FLAGS] <ROOTFS> [CMD]...

<ROOTFS>

Image reference (e.g. busybox), a rootfs CID, or a named ref

Required.

<CMD>

Command + args; argv[0] is an absolute path inside the image

May be given more than once.

-e, --env <K=V>

Environment variable KEY=VALUE (repeatable)

May be given more than once.

--mount <CID:DEST[:rw]>

Extra mount CID:DEST[:rw] (read-only bind unless :rw; repeatable)

May be given more than once.

--ulimit <NAME=SOFT[:HARD]>

Resource limit NAME=SOFT[:HARD] (e.g. nofile=1024:2048; repeatable)

May be given more than once.

-w, --workdir <DIR>

Working directory override; empty → the image's own WORKDIR

--name <NAME>

Optional human-readable name

--no-tty

Don't allocate a pseudo-terminal (a pty is on by default so tools that gate color on isatty stay colored; stdout+stderr then merge)

Defaults to false.

--internet-access

Give the pod internet access (egress). Isolates the pod in its own network namespace and attaches pasta for egress. Without this (and without --publish) the pod shares the host network

Defaults to false.

-p, --publish <HOST:POD[/udp]>

Publish a host port to the pod: HOST:POD[/udp] (repeatable). Also isolates the pod + attaches pasta. E.g. -p 8080:80

May be given more than once.

bldr pod dag

Run a DAG of pod operations (run/exec/wait/snapshot/kill/stop) from a YAML spec, via the pod.dag function. Streams a build-progress tree (one node per op) and prints the results document. - reads stdin

bldr [BLDR FLAGS] pod dag [DAG FLAGS] <FILE>

<FILE>

Path to the YAML spec (or - for stdin)

Required.

--runtime <RUNTIME>

Name of the container runtime to run on (a runtimes entry in the node config — native runc or a cloud-hypervisor VM). Omit for the node default. Sets the spec's runtime field

bldr pod diff

Capture overlay diffs as FsNode CIDs. By default the rootfs only; --mount <id> (repeatable) diffs specific mutable mounts instead; --all diffs the rootfs plus every mutable mount. Works while running or after exit, until the pod is removed

bldr [BLDR FLAGS] pod diff [DIFF FLAGS] <ID>

<ID>

Pod id

Required.

--mount <ID>

Mutable mount id to diff (repeatable); restricts to these mounts

May be given more than once.

-a, --all

Diff the rootfs and every mutable mount

Defaults to false.

bldr pod kill

Send a signal to a running pod (default SIGKILL)

bldr [BLDR FLAGS] pod kill [KILL FLAGS] <ID>

<ID>

Pod id

Required.

--signal <SIGNAL>

Signal name (e.g. TERM, HUP) or number

Defaults to KILL.

bldr pod list

Also ps.

List pods (running by default; --all includes created/exited)

bldr [BLDR FLAGS] pod ps [PS FLAGS]

-a, --all

Defaults to false.

--build <BUILD_ID>

Only pods owned by this build. A build keeps its pods until the build itself is removed, so this is how you find what it ran — and, with bldr build --profile, where the profiles are. Implies --all: a finished build's pods have exited

bldr pod profile

Fetch a pod's CPU profile: collapsed stacks (proc;frame;frame <count>), ready to pipe into inferno-flamegraph, flamegraph.pl, or speedscope.

Available once the pod has exited, and only if it was profiled — profiling is opt-in via the node's profiling.enabled or a pod.dag run op's profile: true. Symbol names are left mangled; pipe through c++filt or rustfilt to read them.

bldr [BLDR FLAGS] pod profile [PROFILE FLAGS] <ID>

<ID>

Pod id (or name)

Required.

-o, --output <OUTPUT>

Write here instead of stdout

bldr pod pull

Pull an image by reference into the node, printing its CID + sha256 digest and the prepared rootfs CID. (run/create pull automatically.)

bldr [BLDR FLAGS] pod pull [PULL FLAGS] <REFERENCE>

<REFERENCE>

Image reference, e.g. hello-world, docker.io/library/busybox:1.36

Required.

--arch <ARCH>

OCI architecture (e.g. amd64); defaults to the node's

bldr pod rm

Remove one or more pods (--force kills running ones first)

bldr [BLDR FLAGS] pod rm [RM FLAGS] [IDS]...

<IDS>

Pod ids

May be given more than once.

-f, --force

Defaults to false.

bldr pod run

Create + start + attach (docker run). --detach to leave it running; --rm to remove it after it exits

bldr [BLDR FLAGS] pod run [RUN FLAGS] <ROOTFS> [CMD]...

<ROOTFS>

Image reference (e.g. busybox), a rootfs CID, or a named ref

Required.

<CMD>

Command + args; argv[0] is an absolute path inside the image

May be given more than once.

-e, --env <K=V>

Environment variable KEY=VALUE (repeatable)

May be given more than once.

--mount <CID:DEST[:rw]>

Extra mount CID:DEST[:rw] (read-only bind unless :rw; repeatable)

May be given more than once.

--ulimit <NAME=SOFT[:HARD]>

Resource limit NAME=SOFT[:HARD] (e.g. nofile=1024:2048; repeatable)

May be given more than once.

-w, --workdir <DIR>

Working directory override; empty → the image's own WORKDIR

--name <NAME>

Optional human-readable name

--no-tty

Don't allocate a pseudo-terminal (a pty is on by default so tools that gate color on isatty stay colored; stdout+stderr then merge)

Defaults to false.

--internet-access

Give the pod internet access (egress). Isolates the pod in its own network namespace and attaches pasta for egress. Without this (and without --publish) the pod shares the host network

Defaults to false.

-p, --publish <HOST:POD[/udp]>

Publish a host port to the pod: HOST:POD[/udp] (repeatable). Also isolates the pod + attaches pasta. E.g. -p 8080:80

May be given more than once.

-d, --detach

Start detached; print the pod id instead of streaming output

Defaults to false.

--rm

Remove the pod after it exits

Defaults to false.

bldr pod start

Start a created pod. --attach to stream its stdout/stderr

bldr [BLDR FLAGS] pod start [START FLAGS] <ID>

<ID>

Pod id

Required.

-a, --attach

Attach to stdout/stderr and wait

Defaults to false.