BUILDBOX-RUN(1)

📦
version 1.4.16 · 2 versions
, in ubuntu stonking

✨ NAME ✨

buildbox-run — bestie, it's literally just called buildbox-run 💖 (yes the manpage name section is that iconic and that short, no cap)

🦋 DESCRIPTION 🦋

okay so here's the vibe: you run it like this 🫶

usage: debian/buildbox/usr/bin/buildbox-run [OPTIONS]

and then it does its little runner thing. now let's get into the options, because there are so many and I am obsessed with every single one 💅

  • --help — prints this message and then dips. bye! 👋
  • --version — prints version info and exits. the classic.
  • --action=PATH — the path where we read the input Action from 📥
  • --action-result=PATH — the path where we write the output ActionResult to 📤
  • --log-level=LEVEL — log verbosity, default is info. your choices are trace/debug/info/warning/error. pick your fighter ✨
  • --verbose — sets the log level to debug, aka chaos mode (affectionate) 🐛
  • --digest-function — sets the digest function 🔐
  • --log-directory=DIR — write logs into this directory, with filenames shaped like debian/buildbox/usr/bin/buildbox-run.<hostname>.<username>.log.<severity level>.<date>.<time>.<pid> 📝
  • --disable-localcas — do not use LocalCAS protocol methods, periodt 🚫
  • --workspace-path=PATH — the location on disk that the runner uses as root when it executes jobs 🏠
  • --stdout-file=FILE — file to redirect the command's stdout into 🎀
  • --stderr-file=FILE — file to redirect the command's stderr into 🙈
  • --no-logs-capture — do not capture and upload whatever got written to stdout and stderr. no receipts, we move on 💅
  • --collect-execution-stats — gathers execution_stats.proto metrics and attaches the digest of the message in CAS to ActionResult.execution_metadata.auxiliary_metadata 📊
  • --validate-parameters — only checks whether all the required parameters are being passed and that no unknown options were given. exits with a status code holding the result (0 if it all worked out) ✅
  • --post-action-command=COMMAND — a command to run once the action is done. it can take one parameter, which is the path to the staged directory. heads up bestie: these commands are blocking if --disable-localcas is set 😭
  • --output-bypass-local-cache — skips caching output blobs in the LocalCAS storage when you're using the LocalCAS API. lowkey important: this has no effect if --disable-localcas is set 🧊
  • --staging-mode=MODE — how to stage directories and files when handling StageTreeRequest. valid values: [fuse, copy-or-link, default], and default would favor fuse if it's available 🗂️
  • --graceful-shutdown-seconds=SECONDS — how long to wait after sending a SIGTERM to the executed command because of a timeout or runner shutdown. by default a SIGKILL is sent immediately 💀 (fr fr, no grace period unless you ask for one)
  • --remote=URL — URL for the CAS service 🌐
  • --instance=NAME — name of the CAS instance 🏷️
  • --server-cert=PATH — public server certificate for TLS (PEM-encoded) 🔒
  • --client-key=PATH — private client key for TLS (PEM-encoded) 🗝️
  • --client-cert=PATH — public client certificate for TLS (PEM-encoded) 📜
  • --access-token=PATH — access Token for authentication (like JWT, OAuth access token, etc). it gets included as an HTTP Authorization bearer token 👑
  • --token-reload-interval=MINUTES — time to wait before refreshing the access token from disk again. you can optionally add suffixes: M (minutes), H (hours). if you don't add a suffix, the value defaults to minutes ⏰
  • --googleapi-auth — uses GoogleAPIAuth when this flag is set 🌈
  • --credential-helper=PATH — path to the credential helper executable for dynamic authentication. Example: --credential-helper=/usr/bin/helper 🧚
  • --retry-limit=INT — how many times to retry on grpc errors 🔁
  • --retry-delay=MILLISECONDS — how long to wait before the first grpc retry ⏳
  • --retry-on-code — which gRPC status code(s) to retry on 📟
  • --request-timeout=SECONDS — how long to wait for gRPC request responses ⌛
  • --min-throughput=BPS — minimum throughput in bytes per second. the value may be suffixed with K, M, G or T 🚀
  • --keepalive-time=SECONDS — the period after which a keepalive ping is sent 💓
  • --load-balancing-policy — which grpc load balancing policy to use. valid options are round_robin and grpclb ⚖️
  • --ra-remote=URL — URL for the Asset service 📦
  • --ra-instance=NAME — name of the Asset instance 🏷️
  • --ra-server-cert=PATH — public server certificate for TLS (PEM-encoded) 🔒
  • --ra-client-key=PATH — private client key for TLS (PEM-encoded) 🗝️
  • --ra-client-cert=PATH — public client certificate for TLS (PEM-encoded) 📜
  • --ra-access-token=PATH — access Token for authentication (like JWT, OAuth access token, etc). it gets included as an HTTP Authorization bearer token 👑
  • --ra-token-reload-interval=MINUTES — time to wait before refreshing the access token from disk again. you can optionally add suffixes: M (minutes), H (hours). if you don't add a suffix, the value defaults to minutes ⏰
  • --ra-googleapi-auth — uses GoogleAPIAuth when this flag is set 🌈
  • --ra-credential-helper=PATH — path to the credential helper executable for dynamic authentication. Example: --credential-helper=/usr/bin/helper 🧚
  • --ra-retry-limit=INT — how many times to retry on grpc errors 🔁
  • --ra-retry-delay=MILLISECONDS — how long to wait before the first grpc retry ⏳
  • --ra-retry-on-code — which gRPC status code(s) to retry on 📟
  • --ra-request-timeout=SECONDS — how long to wait for gRPC request responses ⌛
  • --ra-min-throughput=BPS — minimum throughput in bytes per second. the value may be suffixed with K, M, G or T 🚀
  • --ra-keepalive-time=SECONDS — the period after which a keepalive ping is sent 💓
  • --ra-load-balancing-policy — which grpc load balancing policy to use. valid options are round_robin and grpclb ⚖️
  • --nested-instance=NAME — the instance to use for nested remote execution 🪆
  • --nested-ac-enable-update — allows action cache updates for nested remote execution 🔄
  • --bind-mount=HOSTPATH:PATH — bind mount a file or directory from the host into the sandbox 🪢
  • --enable-tmp-outputs — allow capturing outputs under the /tmp directory in the sandbox 🗃️
  • --ro-bind-mount=[CONTENT:]HOST_PATH:CHROOT_PATH — bind a read-only path from HOST_PATH on the host filesystem to CHROOT_PATH inside the constructed chroot. if CONTENT is set, the bind only happens if the action has a property inject=CONTENT 🔐
  • --oci-auth-token=PATH — path to the authentication token file for private registries 🐳
  • --num-parallel-layer-threads=N — set the number of parallel threads for OCI layer processing. Default: min(hardware-concurrency, 8) 🧵

and that's the whole page bestie, you ate that 💅✨

mwah 💖 this was buildbox-run 1.4.16, from August 2026 — see you in the next manpage, iykyk 🎀🦋

📦 where this page comes from