tracebloc resources — one knob for how much of this machine tracebloc may use

[LukasWodka]

Design approved by Lukas (2026-07-06). One user-facing concept: how much of this machine tracebloc may use. No jobs, no pods, no ceilings in the UX — that math is ours, done silently.

The whole surface — top-level tracebloc resources

$ tracebloc resources

  This machine     8 CPU · 32 GiB
  tracebloc uses   up to 2 CPU · 8 GiB     (right now: 1.2 CPU · 4 GiB)

  Give it more:  tracebloc resources set --memory 16Gi --cpu 4

$ tracebloc resources set --memory 16Gi --cpu 4
  ✔ tracebloc can now use up to 4 CPU · 16 GiB of this machine

$ tracebloc resources set max
  ✔ tracebloc can now use everything this machine has (8 CPU · 30 GiB —
    2 GiB kept for the system)

Locked decisions: explicit numbers + max only (no other presets). Top-level command (tracebloc resources), not under cluster. Validation speaks the user's language — never a Kubernetes word ("This machine has 32 GiB — tracebloc can use at most 30.").

What happens silently underneath (grounded)

• Training size derived: allowance − platform overhead (~1 CPU / 3 GiB) → written to chart values env.RESOURCE_REQUESTS/env.RESOURCE_LIMITS (requests == limits, the lockstep client-runtime expects) via helm upgrade --reuse-values --set … — persists across the hourly auto-upgrade CronJob. jobs-manager rolls; the next run gets the new size; one run gets everything (sequential, max power — parallelism stays implicit).
• Machine ceiling (macOS): if the allowance exceeds the Docker VM, raise the VM in the same command — edit ~/Library/Group Containers/group.com.docker/settings-store.json (Cpus/MemoryMiB) + docker desktop restart, behind one consent line (~1 min, running training interrupted; k3d containers come back with the daemon, nodes report the new capacity). Linux: the host is the ceiling — honest message, nothing to raise.
• Reads for show: node allocatable (k8s API), jobs-manager env (current training size — same source cluster doctor's checkNodeFit already parses), platform = sum of chart requests, live usage via metrics/summary API where available.
• Dashboard follows free: the jobs-manager heartbeat already reports pod sizing and the resource-monitor reports node capacity to edge-device-heartbeat/ — zero backend changes for v1.
• Fit check after apply: reuse checkNodeFit logic to confirm the derived training size schedules; report honestly if not.

Phasing

• P1 — tracebloc resources (show): pure reads, no mutations. Buildable now.
• P2 — set --cpu/--memory + max: derive training size, apply via helm (helm is on every installed machine — the installer puts it there; customers still never touch it), post-apply fit check.
• P3 — macOS VM raise (consent + docker desktop restart); Linux honest-ceiling message.
• Home screen + --help mention once shipped.

Groundwork already merged/in flight

• Install-time default override: TRACEBLOC_TRAINING_RESOURCES="cpu=4,memory=16Gi" — fix(installer): make the training size configurable at install (TRACEBLOC_TRAINING_RESOURCES) client#308 (this command becomes the friendly runtime layer over the same values).
• Silent-hang fix (unschedulable CPU training pods now stop + report with "give tracebloc more of this machine" guidance instead of pending forever) — client-runtime PR (linked below). That failure message is this command's front door.

Non-goals (v1)

• Per-experiment sizing (backend has no requirements field end-to-end — separate product conversation).
• Parallel-run configuration (implicit: one run gets the full allowance).
• Multi-node/BYO clusters: show works everywhere; set targets the installer-provisioned single-node path first, BYO keeps values-file control.

Refs: design thread grounded 2026-07-06 (chart values + jobs-manager env + heartbeat fields + k3d/Docker mechanics verified against code and a live cluster). Related: tracebloc/client#308, backend#992 (installer UX v2 umbrella).

🤖 Generated with Claude Code

[LukasWodka]

Groundwork shipped: tracebloc/client#308 (install-time default override TRACEBLOC_TRAINING_RESOURCES) · tracebloc/client-runtime#159 (unschedulable training pods now stop + report with the "give tracebloc more of this machine" message — this command's front door).