feat(hub): custody-backed 'Carried into boxes' + fold box-image into the Docker row

[madarco]

Implements two items from docs/remote-hub-backlog.md for the remote hub's System page.

Item A — "Carried from this machine" makes no sense on a remote hub

On a deployed/exposed control box, homedir() is the VPS's home, so the old section listed ~1 path and told the operator nothing about what a hub-created box actually receives. The real answer there lives in custody.

• Custody enabled (deployed/exposed hub): the section retitles to "Carried into boxes" and answers "what will a box created here actually get?" — a per-agent rollup of the custody agents scope (entry counts / sizes / last update) under an Agent credentials · custody subheading, alongside the still-valid host-carried skills the control box itself carries, with a link across to /custody.
• Custody disabled (plain localhost hub): unchanged — keeps today's "Carried from this machine" title and host-carried list.
• Custody page: the not-enabled empty state now links back to /system ("Carried from this machine"), so the two pages point at each other in whichever mode applies.

Done as a second client-side fetch of /api/v1/custody (the hub web layer is a pure REST client — no new server plumbing, route seams untouched). New pure helper summarizeAgentCredentials() in custody-view.ts (reuses groupCustody; unit-tested).

Item B — the "Box image" section was docker-only

The box-image fields (registry / pull tag / stamped fingerprint / local image ref) now fold into the Docker row of the Providers section; the standalone "Box image" section is deleted. Only the docker row gets them. Data source unchanged (/api/v1/system boxImage).

Verification

pnpm --filter @agentbox/hub lint, typecheck, and test all green (79 tests, incl. new summarizeAgentCredentials cases).

Smoke-tested both modes against the standalone build in this box (rebuilt + restarted per CLAUDE.md), rendered with a headless browser.

Localhost mode — /api/v1/custody → {"enabled":false}; System page keeps "Carried from this machine", box-image fields fold into the Docker row, Custody page links to /system:

=== /api/v1/system (localhost) ===
boxImage: {"registry":"ghcr.io/madarco/agentbox/box","pullTag":"ghcr.io/madarco/agentbox/box:sha-733849e4c898c6eb","stampedFingerprint":"733849e4c898","imageRef":"agentbox/box:dev"}
providers ids: docker,daytona,hetzner,vercel,e2b,digitalocean
=== /api/v1/custody (localhost) ===
{"enabled":false,"entries":[]}

System page rendered text (docker row):

Docker  baked   733849e4c898
  REGISTRY ghcr.io/madarco/agentbox/box
  PULL TAG ghcr.io/madarco/agentbox/box:sha-733849e4c898c6eb
  STAMPED FINGERPRINT 733849e4c898
  LOCAL IMAGE agentbox/box:dev
...
CARRIED FROM THIS MACHINE   6 PATH(S) PRESENT

Custody page (localhost): Custody isn't enabled on this hub. … keeps credentials on your machine directly — see Carried from this machine (link → /system).

Exposed/control-box mode — ran the standalone hub with an admin token so custody turns on (hub setup needs a gh credential this box lacks; custody-enabled mode is driven purely by the admin token, so the direct run exercises the identical /api/v1/custody enabled:true → UI code path), seeded fake custody entries under ~/.agentbox/hub/custody:

=== /api/v1/custody (exposed) ===
enabled: true entries: 8
agents/claude/.claude.json
agents/claude/.credentials.json
agents/codex/auth.json
agents/opencode/auth.json
boxes/box-demo/ssh/id_ed25519 (+ .pub)
prepared/hetzner.json
projects/express-server/seed/.env

System page rendered text:

CARRIED INTO BOXES                                    Custody ↗
What a box created on this control box receives: agent logins held in custody,
plus the skills this control box carries.
AGENT CREDENTIALS · CUSTODY
  Claude    2 files  58 B  updated 30s ago
  Codex     1 file   25 B  updated 30s ago
  OpenCode  1 file   12 B  updated 30s ago
SKILLS · THIS CONTROL BOX
  Shared agent skills  15 skills  ~/.agents
  Claude               15 skills  ~/.claude
  Codex                 0 skills  ~/.codex

Teardown: killed the direct hub, removed the seeded custody + test control-plane.env, restarted the plain localhost hub (custody back to enabled:false). Box left clean.

Docs

Updated apps/web/content/docs/deployed-hub.mdx (the Custody / System & Build descriptions) to reflect the cross-links and the "Carried into boxes" behaviour. The /system API response shape is unchanged, so api.mdx stays accurate.

https://claude.ai/code/session_019M5TG6UdiUN2PfYUBcLruY

---

Note

Low Risk
Dashboard-only UI and read-only REST clients; no API shape changes or credential exposure beyond existing metadata-only custody listings.

Overview
System & Build now distinguishes localhost hubs from deployed control boxes for what gets shown as “carried” into new boxes. It loads /api/v1/custody (alongside the existing system fetch) and waits on that before picking a mode so the UI doesn’t flash the wrong framing.

When custody is disabled, behavior is unchanged: “Carried from this machine” lists host paths from hostCarried. When custody is enabled, the section becomes “Carried into boxes” with a per-agent credential rollup (counts, sizes, last update via new summarizeAgentCredentials() in custody-view.ts), skills-only rows from the control box host, and links to /custody.

The standalone Box image block is removed; registry, pull tag, fingerprint, and local image ref render inside the Docker provider row only (BoxImageDetail).

Custody’s disabled empty state links to /system (“Carried from this machine”). Docs in deployed-hub.mdx describe the cross-links and the two carried modes.

^{Reviewed by Cursor Bugbot for commit bfdce68. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentbox-web	Ready	Preview, Comment	Jul 29, 2026 7:59am