[bldr]docs
gRPC APIDaemon

Runs

Runs — run applications built by bldr (a docker-compose-equivalent "runnable"). A run is backed by a build that materialises the selected runnable; with watch, the build watches the workspace and a rebuilt artifact is hot-swapped into (or restarts) the running services. Progress is a task tree (build subtree + service states), like builds/deployments.

Runs — run applications built by bldr (a docker-compose-equivalent "runnable"). A run is backed by a build that materialises the selected runnable; with watch, the build watches the workspace and a rebuilt artifact is hot-swapped into (or restarts) the running services. Progress is a task tree (build subtree + service states), like builds/deployments.

Service builder.Runs, 5 rpcs.

CreateRun(CreateRunRequest) -> stream RunEvent

Create + attach to a run, streaming its progress tree + service snapshots. Detached: cancelling the stream leaves the run running (manage via StopRun).

Request: CreateRunRequest

message CreateRunRequest {
  repeated PortForward publish = 5;
  optional string runnable_cid = 6;
  optional map<string, string> labels = 7;
}
Field
publishHost→service port forwards, overriding/adding to the runnable's declared ports (applied to the runnable's single service, or by service via a service: prefix later). Reuses PortForward.
runnable_cidThe Runnable block to run.
labelsFree-form labels stamped onto the run. bldr.name is the well-known key carrying bldr run --name; it overrides the derived display name.

Response: RunEvent

Streamed by CreateRun / WatchRun: a leading snapshot, then live events.

message RunEvent {
  oneof event {
    Run snapshot = 1;
    TaskEvent task = 2;
  }
}
Field
snapshot 
taska node in the run's progress tree

ListRuns(ListRunsRequest) -> ListRunsResponse

Request: ListRunsRequest

message ListRunsRequest {
  // no fields
}

Response: ListRunsResponse

message ListRunsResponse {
  repeated Run runs = 1;
}
Field
runsnewest first

WatchRuns(WatchRunsRequest) -> stream ListRunsResponse

Request: WatchRunsRequest

message WatchRunsRequest {
  // no fields
}

Response: ListRunsResponse

The same message as ListRunsResponse.

WatchRun(WatchRunRequest) -> stream RunEvent

Request: WatchRunRequest

message WatchRunRequest {
  optional string run_id = 1;
}

Response: RunEvent

The same message as RunEvent.

StopRun(StopRunRequest) -> StopRunResponse

Stop a run: tear down its services + networks and remove it.

Request: StopRunRequest

message StopRunRequest {
  optional string run_id = 1;
}

Response: StopRunResponse

message StopRunResponse {
  optional bool was_stopped = 1;
}
Field
was_stoppedfalse if the run_id was unknown

Types used above

Run

A run: a running application. Returned by Create/List and carried as the leading snapshot on the event streams.

message Run {
  optional string id = 1;
  optional string name = 2;
  optional string runnable = 4;
  optional RunState state = 5;
  optional uint64 generation = 6;
  optional string runnable_cid = 7;
  optional string source_build_id = 8;
  optional string error = 9;
  repeated RunServiceState services = 10;
  optional int64 created_at_seconds = 12;
  optional int64 started_at_seconds = 13;
  optional int64 finished_at_seconds = 14;
  optional map<string, string> labels = 16;
}
Field
id 
namedisplay: the user's --name, else runnable, else the short CID
runnableThe run-target name the build asked for (bldr build … --run &lt;name>). Empty for a run started from a bare CID: a Runnable block carries no name.
state 
generationbumped each time the source build re-targets this run
runnable_cidthe current Runnable block CID
source_build_idThe build whose run target started this, empty when a caller started it from a CID. The only link a run has to a workspace.
errorset when state == FAILED
services 
created_at_seconds 
started_at_seconds 
finished_at_seconds 
labelsFree-form labels attached at create time (same shape as Build.labels / Deployment.labels). bldr.name carries bldr run --name and, when set, is what name above resolves to.

RunServiceState

The live state of one service (a long-lived pod) in a run.

message RunServiceState {
  optional string name = 1;
  optional string pod_id = 2;
  optional RunServiceStatus status = 3;
  optional string log_stream_id = 4;
  optional string image_cid = 5;
  repeated RunMountState mounts = 6;
  repeated RunPortMapping ports = 7;
}
Field
name 
pod_id 
status 
log_stream_idThe pod's stdout/stderr log stream id ({peer}/{tenant}/{uuid}).
image_cid 
mounts 
portsEffective host→service port forwards (the runnable's declared ports plus any CLI -p overrides). The UI turns a TCP mapping into an "open" link.

RunMountState

The live state of one mounted artifact in a service.

message RunMountState {
  optional string dest = 1;
  optional string cid = 2;
  optional bool hotswap = 3;
  optional bool hotswapped = 4;
}
Field
dest 
cidcurrent backing CID
hotswapdeclared hot-swappable
hotswappedthe last update was applied as a live hot-swap

RunPortMapping

A live host→service port forward on a running service.

message RunPortMapping {
  optional uint32 host_port = 1;
  optional uint32 pod_port = 2;
  optional bool udp = 3;
}

RunState

enum RunState {
  RUN_STATE_UNSPECIFIED = 0;
  RUN_STATE_PENDING = 1;
  RUN_STATE_BUILDING = 2;
  RUN_STATE_RUNNING = 3;
  RUN_STATE_FAILED = 4;
  RUN_STATE_STOPPED = 5;
}
Value
RUN_STATE_UNSPECIFIED 
RUN_STATE_PENDINGcreated; backing build not finished yet
RUN_STATE_BUILDINGbacking build running (materialising the runnable)
RUN_STATE_RUNNINGservices are up
RUN_STATE_FAILEDbuild or start failed; error is set
RUN_STATE_STOPPEDstopped by the user

RunServiceStatus

enum RunServiceStatus {
  RUN_SERVICE_STATUS_UNSPECIFIED = 0;
  RUN_SERVICE_STATUS_STARTING = 1;
  RUN_SERVICE_STATUS_RUNNING = 2;
  RUN_SERVICE_STATUS_RESTARTING = 3;
  RUN_SERVICE_STATUS_EXITED = 4;
}
Value
RUN_SERVICE_STATUS_UNSPECIFIED 
RUN_SERVICE_STATUS_STARTING 
RUN_SERVICE_STATUS_RUNNING 
RUN_SERVICE_STATUS_RESTARTINGrestarting after a non-hot-swappable change
RUN_SERVICE_STATUS_EXITED 

On this page