BUILDBOX-CASD(1)

📦
version 1.4.16 · 2 versions
, in ubuntu stonking

🦋 buildbox-casd — BUILDBOX-CASD(1) 🦋

okay bestie, come SIT. this is the User Commands manual for buildbox-casd, and it's a long one so grab a snack 💖 (this is part 1 of 2, we're not even close to done yet)

✨ NAME ✨

buildbox-casd — literally just buildbox-casd. that's the name, that's the whole name. short, sweet, iconic 👑

🌸 SYNOPSIS 🌸

buildbox-casd

no args, no drama. she just runs. 💅

💜 DESCRIPTION 💜

so buildbox-casd is a whole buffet of flags, and fr fr there are a LOT of them. every single one is marked [optional], which is giving "no pressure, choose your own adventure". here's the full menu, no cap, nothing skipped 🫶

🎀 the flags 🎀

✨ the "all services" bunch (she does everything at once, main character energy) ✨

  • --help — shows you how to use her and dips. that's it, that's the whole flag.
  • --version — prints the version info and bounces. [optional]
  • --remote — the URL for all the services. one link to rule them all. [optional]
  • --instance — the instance for all the services. [optional]
  • --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 — the auth token for all services (JWT, OAuth token, whatever you got), and it gets included as an HTTP Authorization bearer token. [optional]
  • --token-reload-interval — the default access token refresh timeout. [optional]
  • --googleapi-auth — use GoogleAPIAuth for all services. [optional]
  • --credential-helper — the 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 — the 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 seconds. the value may be suffixed with K, M, G or T. [optional]
  • --keepalive-time — the gRPC keepalive pings period for all services. set it to 0 to disable keepalive pings. [optional]
  • --load-balancing-policy — gRPC load balancing policy for all services. the valid options are 'round_robin' and 'grpclb'. [optional]

🧊 the CAS service squad 🧊

  • --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 — the 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, in bytes per seconds. the value may be suffixed with K, M, G or T. [optional]
  • --cas-keepalive-time — the gRPC keepalive pings period for the CAS service. set it to 0 to disable keepalive pings. [optional]
  • --cas-load-balancing-policy — gRPC load balancing policy for the CAS service. valid options are 'round_robin' and 'grpclb'. [optional]

🏠 the local server corner 🏠

  • --server-instance — [Deprecated] bestie, use --local-server-instance instead, this one is giving expired. [optional]
  • --local-server-instance — create an extra local CAS server instance. super useful when --cas-remote is specified. [optional]
  • --digest-function — set a custom digest function. default: SHA256. supported functions: SHA512, SHA384, SHA256, SHA1, MD5. [optional]

🍓 the Action Cache crew 🍓

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

🌈 the Remote Asset gang 🌈

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

🔥 the Execution service (she runs things, literally) 🔥

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

🫶 proxy, binding & local cache (the last chunk of this part, we're so close) 🫶

  • --proxy-instance — name of the proxy instance. you can specify multiple values of PROXY_INSTANCE[:REMOTE_INSTANCE]. if REMOTE_INSTANCE exists, the proxy instance uses it for remote connections, and it overrides the --*instance options. [optional]
  • --bind — bind to address:port or a UNIX socket in unix:path. multiple addresses can be specified. [optional]
  • --unix-socket-group — if you're binding to a UNIX socket, this updates its group ownership. [optional]
  • --unix-socket-mode — if you're binding to a UNIX socket, this updates its mode in octal format, e.g. 0775. [optional]
  • --permit-keepalive-time — the minimum allowed time in seconds between keepalive pings coming from clients. [optional]
  • --quota-high — maximum local cache size (e.g., 50G or 2T). [optional]
  • --quota-low — local cache size to retain on LRU expiry, either as an absolute size or as a percentage of quota-high. [optional, default = "50%"]
  • --reserved — reserved disk space (the headroom that gets left when quota-high gets automatically reduced). [optional, default = "2G"]
  • --protect-session-blobs — do not expire blobs created or used in the current session. [optional, default = false]

okay and that's genuinely just the top of the iceberg 🧚 part 2 is coming and she has more to say, so don't go anywhere bestie 💖

  • --fail-fast-during-cleanup — bestie, the moment LRU cleanup is happening, write requests get rejected IMMEDIATELY with RESOURCE_EXHAUSTED 🚫 no waiting, no queuing, just nope. (optional, default = false)
  • --buildbox-run — the absolute path to your runner executable, which is what switches on the local execution service ✨ (optional)
  • --runner-arg — the args you wanna hand off to buildbox-run whenever buildbox-casd runs a job 🏃 (optional)
  • --jobs — max number of jobs running at the same time for local execution. gather round, the limit is real 😌 (optional, default = 4)
  • --exec-hybrid-queue-limit — the maximum queue length for local execution when you're in a proxy instance 🧚 (optional)
  • --exec-fallback-to-local — if the remote server can't schedule what the client asked for (like, say, it's throttling y'all), it falls back to local execution 🫶 and heads up: those fallback executions are excluded from the --exec-hybrid-queue-limit value. You need --buildbox-run set for this to even work. (optional, default = false)
  • --cache-failures — caches local actions that exited with a non-zero exit code 💀 (optional, default = true)
  • --findmissingblobs-cache-ttl — how many seconds to cache the results of FindMissingBlobs() calls when you're in proxy mode ⏳ (optional, default = 0)
  • --capture-allow-file-moves — when a LocalCAS capture request has its move_files flag set, this attempts to move files into the CAS instead. That's a win because it avoids a copy only when the file lives on the same filesystem as the LOCAL_CACHE directory AND is owned by the user running casd 👑
⚠️ NOTE: only turn this on if your clients can be trusted not to break the consistency of the storage. Like, for real.

(optional, default = false)

  • --metrics-mode — Metrics Mode: --metrics-mode=MODE — the options for MODE are udp://<hostname>:<port>, file:///path/to/file, and stderr 📊 (optional)
  • --metrics-publish-interval — how often metrics get published 🕒 (optional, default = 15)
  • --metrics-prefix — the prefix stuck onto your metric names 🏷️ (optional, default = "buildboxcasd")
  • --read-only-remote — says whether casd should update the remote CAS with local build artifacts 🤔 (optional)
  • --store-writable-objects — stores object files with writable mode (644) 🔓 (optional)
  • --num-digest-threads — how many threads hash files into digests. Default = min(hardware-concurrency,16) 🧵 (optional)
  • --num-io-threads — how many threads proxy CAS instances use to upload/download blobs to and from the remote CAS. Default = min(hardware-concurrency*2,64) 🚀 (optional)
  • --shutdown-deadline — force-terminate pending requests this many seconds after a shutdown was requested (SIGINT/SIGTERM) ⏰ (optional)
  • --allow-pre-unstage-command — a list of absolute paths to executables that are allowed to run before staged directories get unstaged 💅 (optional)
  • --ac-validation-cache-ttl — how many seconds to cache the results of GetActionResult() validations when in proxy mode 🗂️ (optional, default = 0)
  • --log-level — the log level. Your choices are debug, error, info, trace, warning 📝 (optional, default = "error")
  • --verbose — just sets the log level to debug for you, no thoughts, head empty 🐛 (optional)
  • Cache path — POSITIONAL (required) 📍

and that's the whole page, bestie, we ATE 💅✨ this was buildbox-casd version 1.4.16, hailing from August 2026, and yes, it is still living its BUILDBOX-CASD(1) main character era 👑🌈 go forth and cache responsibly 🫶🎀

📦 where this page comes from