BUILDBOX-WORKER(1)

📦
version 1.4.16 · 2 versions
, in ubuntu stonking

💖 buildbox-worker(1) — User Commands 💖

okay bestie, strap in. this one is A LOT and we are covering every single flag, no skipping, no "you get the idea". you DO get the idea, but you're getting the details anyway. 💅

🌸 NAME 🌸

buildbox-worker — buildbox-worker.

that's it. that's the description. it's naming itself. queen behavior honestly. 👑

🦋 SYNOPSIS 🦋

buildbox-worker

no arguments on the command line, bestie — everything this thing does, it does through flags. 🫶

✨ DESCRIPTION ✨

buildbox-worker is the little engine running your builds, and every knob it has is listed right here in this section. there are like a hundred of them. we're doing all of them. every default, every [optional], every service-specific twin of every flag. no cap. 💖

🎀 the general / worker-level stuff 🎀

  • --help — shows you the usage and exits. that's it. that's the whole job. 🫡
  • --version — prints the version info and peaces out. [optional]
  • --instance — the instance name you want handed to the Remote Workers API and the CAS servers. [optional, default = ""]
  • --digest-function — set a custom digest function. the supported ones are SHA512, SHA384, SHA256, SHA1, MD5. [optional, default = "SHA256"]
  • --concurrent-jobs — how many jobs run at once. defaults to literally one at a time, which is very "one thing at a time, we're being mindful" of it. [optional, default = 1]
  • --stop-after — terminate after running the given number of jobs. defaults to non-terminating, i.e. it just. keeps. going. [optional, default = -1]
  • --consecutive-errors-threshold — mark the worker as UNHEALTHY after N consecutive errors. disabled by default, and 0 means disabled. [optional, default = 0]
  • --priority — worker priority for job scheduling. lower value = more prioritized than workers with a bigger priority value. so small number, big energy. [optional, default = 0]
  • --disk-usage-health-check — mark the worker as UNHEALTHY if disk usage goes over the threshold. format is --disk-usage-health-check=/path:80%. you can pass it multiple times for different paths. [optional]

🌈 all-services flags (one flag to rule them all) 🌈

these are the "for all services" versions — set them once and they apply everywhere. 😌

  • --remote — URL for all services. [optional]
  • --instance — instance for all services. [optional] (yep, --instance shows up twice in this page. we don't make the rules, we just document them 💀)
  • --server-cert — server TLS certificate for all services, PEM-encoded. [optional]
  • --client-key — client private TLS key for all services, PEM-encoded. [optional]
  • --client-cert — client TLS certificate for all services, PEM-encoded. [optional]
  • --access-token — auth token for all services (JWT, OAuth token, whatever you got). it gets included as an HTTP Authorization bearer token. [optional]
  • --token-reload-interval — default access token refresh timeout. [optional]
  • --googleapi-auth — use GoogleAPIAuth for all services. [optional]
  • --credential-helper — credential helper executable for all services. [optional]
  • --retry-limit — retry limit for gRPC errors for all services. [optional]
  • --retry-delay — retry delay for gRPC errors for all services. [optional]
  • --retry-on-code — gRPC status code(s) as string(s) to retry on for all services, e.g. 'UNKNOWN', 'INTERNAL'. [optional]
  • --request-timeout — timeout for gRPC requests for all services. set it to 0 to disable the timeout entirely. [optional]
  • --min-throughput — minimum throughput for gRPC requests for all services, in bytes per second. the value can be suffixed with K, M, G or T. [optional]
  • --keepalive-time — gRPC keepalive pings period for all services. set it to 0 to turn keepalive pings off. [optional]
  • --load-balancing-policy — gRPC load balancing policy for all services. valid options are 'round_robin' and 'grpclb'. [optional]

🤖 Bots service (the --bots- girlies) 🤖

  • --bots-remote — URL for the Bots service. [optional]
  • --bots-instance — name of the Bots instance. [optional]
  • --bots-server-cert — server TLS certificate for Bots, PEM-encoded. [optional]
  • --bots-client-key — client private TLS key for Bots, PEM-encoded. [optional]
  • --bots-client-cert — client TLS certificate for Bots, PEM-encoded. [optional]
  • --bots-access-token — auth token for Bots (JWT, OAuth token etc), included as an HTTP Authorization bearer token. [optional]
  • --bots-token-reload-interval — access token refresh timeout for the Bots service. [optional]
  • --bots-googleapi-auth — use GoogleAPIAuth for the Bots service. [optional]
  • --bots-credential-helper — credential helper executable for the Bots service. [optional]
  • --bots-retry-limit — retry limit for gRPC errors for the Bots service. [optional]
  • --bots-retry-delay — retry delay for gRPC errors for the Bots service. [optional]
  • --bots-retry-on-code — gRPC status code(s) as string(s) to retry on for the Bots service, e.g. 'UNKNOWN', 'INTERNAL'. [optional]
  • --bots-request-timeout — timeout for gRPC requests for the Bots service. set it to 0 to disable the timeout. [optional]
  • --bots-min-throughput — minimum throughput for gRPC requests for the Bots service, bytes per second. the value can be suffixed with K, M, G or T. [optional]
  • --bots-keepalive-time — gRPC keepalive pings period for the Bots service. 0 disables keepalive pings. [optional]
  • --bots-load-balancing-policy — gRPC load balancing policy for the Bots service. valid options are 'round_robin' and 'grpclb'. [optional]

📦 CAS service (content-addressed, --cas- coded) 📦

  • --cas-remote — URL for the CAS service. [optional]
  • --cas-instance — name of the CAS instance. [optional]
  • --cas-server-cert — server TLS certificate for CAS, PEM-encoded. [optional]
  • --cas-client-key — client private TLS key for CAS, PEM-encoded. [optional]
  • --cas-client-cert — client TLS certificate for CAS, PEM-encoded. [optional]
  • --cas-access-token — auth token for CAS (JWT, OAuth token etc), included as an HTTP Authorization bearer token. [optional]
  • --cas-token-reload-interval — access token refresh timeout for the CAS service. [optional]
  • --cas-googleapi-auth — use GoogleAPIAuth for the CAS service. [optional]
  • --cas-credential-helper — credential helper executable for the CAS service. [optional]
  • --cas-retry-limit — retry limit for gRPC errors for the CAS service. [optional]
  • --cas-retry-delay — retry delay for gRPC errors for the CAS service. [optional]
  • --cas-retry-on-code — gRPC status code(s) as string(s) to retry on for the CAS service, e.g. 'UNKNOWN', 'INTERNAL'. [optional]
  • --cas-request-timeout — timeout for gRPC requests for the CAS service. set it to 0 to disable the timeout. [optional]
  • --cas-min-throughput — minimum throughput for gRPC requests for the CAS service, bytes per second. the value can be suffixed with K, M, G or T. [optional]
  • --cas-keepalive-time — gRPC keepalive pings period for the CAS service. 0 disables keepalive pings. [optional]
  • --cas-load-balancing-policy — gRPC load balancing policy for the CAS service. valid options are 'round_robin' and 'grpclb'. [optional]

🧚 LogStream service (all the --logstream- things) 🧚

  • --logstream-remote — URL for the LogStream service. [optional]
  • --logstream-instance — name of the LogStream instance. [optional]
  • --logstream-server-cert — server TLS certificate for LogStream, PEM-encoded. [optional]
  • --logstream-client-key — client private TLS key for LogStream, PEM-encoded. [optional]
  • --logstream-client-cert — client TLS certificate for LogStream, PEM-encoded. [optional]
  • --logstream-access-token — auth token for LogStream (JWT, OAuth token etc), included as an HTTP Authorization bearer token. [optional]
  • --logstream-token-reload-interval — access token refresh timeout for the LogStream service. [optional]
  • --logstream-googleapi-auth — use GoogleAPIAuth for the LogStream service. [optional]
  • --logstream-credential-helper — credential helper executable for the LogStream service. [optional]
  • --logstream-retry-limit — retry limit for gRPC errors for the LogStream service. [optional]
  • --logstream-retry-delay — retry delay for gRPC errors for the LogStream service. [optional]
  • --logstream-retry-on-code — gRPC status code(s) as string(s) to retry on for the LogStream service, e.g. 'UNKNOWN', 'INTERNAL'. [optional]
  • --logstream-request-timeout — timeout for gRPC requests for the LogStream service. set it to 0 to disable the timeout. [optional]
  • --logstream-min-throughput — minimum throughput for gRPC requests for the LogStream service, bytes per second. the value can be suffixed with K, M, G or T. [optional]
  • --logstream-keepalive-time — gRPC keepalive pings period for the LogStream service. 0 disables keepalive pings. [optional]
  • --logstream-load-balancing-policy — gRPC load balancing policy for the LogStream service. valid options are 'round_robin' and 'grpclb'. [optional]

🍓 Asset service (these say --ra-, don't ask) 🍓

  • --ra-remote — URL for the Asset service. [optional]
  • --ra-instance — name of the Asset instance. [optional]
  • --ra-server-cert — server TLS certificate for Asset, PEM-encoded. [optional]
  • --ra-client-key — client private TLS key for Asset, PEM-encoded. [optional]
  • --ra-client-cert — client TLS certificate for Asset, PEM-encoded. [optional]
  • --ra-access-token — auth token for Asset (JWT, OAuth token etc), included as an HTTP Authorization bearer token. [optional]
  • --ra-token-reload-interval — access token refresh timeout for the Asset service. [optional]
  • --ra-googleapi-auth — use GoogleAPIAuth for the Asset service. [optional]
  • --ra-credential-helper — credential helper executable for the Asset service. [optional]
  • --ra-retry-limit — retry limit for gRPC errors for the Asset service. [optional]
  • --ra-retry-delay — retry delay for gRPC errors for the Asset service. [optional]
  • --ra-retry-on-code — gRPC status code(s) as string(s) to retry on for the Asset service, e.g. 'UNKNOWN', 'INTERNAL'. [optional]
  • --ra-request-timeout — timeout for gRPC requests for the Asset service. set it to 0 to disable the timeout. [optional]
  • --ra-min-throughput — minimum throughput for gRPC requests for the Asset service, bytes per second. the value can be suffixed with K, M, G or T. [optional]
  • --ra-keepalive-time — gRPC keepalive pings period for the Asset service. 0 disables keepalive pings. [optional]
  • --ra-load-balancing-policy — gRPC load balancing policy for the Asset service. valid options are 'round_robin' and 'grpclb'. [optional]

👑 the last three, and yes they matter 👑

  • --max-wait-time — sets the maximum amount of time, in seconds, between the worker polling the Bots service. [optional, default = 60]
  • --graceful-shutdown-timeout — sets how many seconds to wait for ongoing executions to finish during a graceful shutdown before it escalates to a forceful shutdown. if you don't provide it, ongoing executions just run all the way to completion during graceful shutdown. [optional]
  • --preserve-update-bot-session — when an execution is completed, the previous UpdateBotSession RPC gets preserved. if you don't provide it, the previous RPC gets cancelled instead. [optional, default = false]
not even close to done bestie — this is part 1 and there is MORE. don't go anywhere. 🫶
  • --runner-use-job-instance — turn this on and the worker does a little ✂️ surgery on the lease ID: it splits at the last / and uses the prefix as the instance name for runner CAS and asset connections. [optional, default = false]
  • --buildbox-run — the absolute path to the runner executable. bestie this one is required, no skipping it 🫶 [required]
  • --runner-arg — extra args you wanna hand to buildbox-run whenever the worker runs a job. super handy if the buildbox-run implementation you're using vibes with non-standard options ✨ [optional]
  • --platform — adds a key-value pair to the 'Platform' message the worker sends to the server (peep the Remote Workers API specification for the keys and values you're allowed to use 👀). the format is literally --platform KEY=VALUE [optional]
  • --metrics-mode — format is --metrics-mode=MODE where MODE is one of:
    • udp://<hostname>:<port>
    • file:///path/to/file
    • stderr

[optional]

  • --metrics-publish-interval — how often metrics get published, the interval itself 💅 [optional]
  • --metrics-statsd-format — if you set this to any value, it's the format the statsd publisher uses when tagging is on. it supports influx, graphite and dog, and defaults to influx 🐶 [optional, default = "influx"]
  • --log-level — log verbosity level, aka how chatty this thing is gonna be 📢 [optional, default = "info"]
  • --verbose — sets the log level to debug. full tea, every detail, no secrets 🍵 [optional]
  • --log-directory — writes logs into this directory, with filenames shaped like <program name>.<hostname>.<user name>.log.<severity level>.<date>.<time>.<pid> — yes it's giving extremely specific and we love that for us 🌸 [optional, default = ""]
  • --config-file — the absolute path to a config file 📄 [optional, default = ""]

and that's the last one on the flag roster bestie, but there's one more thing sitting quietly at the end of the list, and it's a positional 👑

  • BOT Id POSITIONAL [optional]
lowkey that's exactly how it shows up in the manpage, so I'm handing it to you character for character — no notes, no edits, periodt 💅

<h2>okay that's a wrap 🎀</h2>

you just survived the whole thing, iconic behavior honestly 🌈 this page is from buildbox-worker 1.4.16, dated August 2026, and it answers to the name BUILDBOX-WORKER(1) when it's out in public 💖

now go run something, bestie, you've got this 🦋✨

📦 where this page comes from