bun host describes the machine it runs on and merges the descriptions of several machines into one registry. An agent or a scheduler reads the registry to pick a host: the one with 24 GB of free VRAM, the one with enough RAM for a build.
bun host collect # the card of this machine, JSON
bun host collect --text # one line
bun host schema # JSON Schema of a card
The card
A card (HostInfo, schema: 1) holds:
| Section | Content |
|---|---|
os | family (linux, windows, macos), name, version, Windows build, architecture, libc (glibc, musl, msvc) |
kernel | release, cgroup v2, io_uring, WSL |
cpu | model, physical and logical cores, flags among avx, avx2, avx_vnni, avx512f, avx512bw, avx512vnni, amx_tile, amx_bf16, amx_int8 |
memory | total and available RAM, swap, memory pressure (/proc/pressure/memory, Linux) |
gpus | vendor, name, total and free VRAM, driver, CUDA version |
disks | mount, device, filesystem, size, free space, kind (nvme, ssd, hdd, unknown) |
network | WireGuard interfaces and addresses |
Sizes are in MiB. Collection reads /proc, /sys, /etc/os-release and runs read-only probes; a probe that is missing leaves its section empty.
| OS | Probes |
|---|---|
| Linux | /proc/{cpuinfo,meminfo,uptime,pressure}, nvidia-smi (also /usr/lib/wsl/lib), /sys/class/drm for AMD and Intel, lsblk, df, ip |
| Windows | PowerShell CIM (Win32_OperatingSystem, Win32_Processor, Win32_VideoController, Win32_LogicalDisk, Get-PhysicalDisk), wmic if PowerShell fails, nvidia-smi |
| macOS | sysctl, sw_vers, df (no GPU section yet) |
Win32_VideoController reports at most 4 GiB of VRAM; on NVIDIA GPUs nvidia-smi replaces it. WireGuard interfaces are those named wg* or WireGuard*, or holding an address that starts with a prefix of BUN_HOST_WG_PREFIXES (default 10.200.,10.8.). The host id is --id, BUN_HOST_ID or the machine name.
Registry
The registry is a directory ($BUN_HOST_DIR, default ~/.bun/host): inventory.json and inbox/, where cards dropped by other hosts wait as <id>.json. There is no daemon. One host is the master and pulls; the others push their own card.
# on each machine (a timer or cron entry)
bun host push --to ubuntu@master:.bun/host/inbox -s HOST_SECRET
# on the master
bun host sync -s HOST_SECRET # refresh its own card, merge inbox/ into inventory.json
bun host sync --from vps:.bun/host/inbox -s HOST_SECRET # also pull the cards of a host
bun host list
bun host find --vram-free 24 --cuda
bun host find --ram 16 --os ubuntu --json
A target is a directory, [user@]host:dir or ssh://[user@]host[:port]/dir. Remote targets need a POSIX shell and use the system OpenSSH in BatchMode (keys and agent from ~/.ssh); BUN_HOST_SSH names another ssh program. A relative remote directory starts in the home directory.
Merging is idempotent and does not depend on order: for each host id the card with the newest collected_at wins, and on an exact tie the larger canonical JSON wins. A card whose id is not made of letters, digits, -, _ and ., or whose schema is not 1, is rejected.
Signatures
With a secret, push signs each card with HMAC-SHA256 over its canonical JSON (keys sorted) and every reader rejects cards that are unsigned or badly signed. The secret never travels in argv:
-s NAMEreads the environment variableNAME.--secret-file PATHreads a file; on Unix its mode must be0600.- Without either flag,
BUN_HOST_SECRET_FILEthenBUN_HOST_SECRET_ENV(the name of a variable) apply. Thebun mcptools use these two.
A secret is at least 16 bytes. The HMAC proves that a card comes from a holder of the secret; it does not hide the card.
MCP tools
bun mcp serves two tools over the registry, with the same schema as the command line:
| Tool | Use |
|---|---|
host_inventory | The cards of the registry plus a fresh card of this machine (refresh, default true); host, max_age_s filter |
host_find | Hosts with min_vram_free_gb, min_ram_gb (available), min_disk_free_gb, gpu, os, cuda; most free VRAM first. Cards older than max_age_s (default 86400) are dropped |
The tools read the registry and write nothing.