Support sandboxed sessions (e.g. using docker sbx)

[chrisfowles]

Just dropping this issue here so that I'm not looking at it if someone else is - but the workflow I'm moving more towards as agents require less supervision to stay on track is sandboxed sessions using docker sbx.

It would be good if cctop could consolidate the utilisation from those sandboxed sessions as well as non-sandboxed.

Not sure if this is even feasible yet, let alone practical - but I'll take a look in the next week or two myself if nothings happening here.

[cleanunicorn]

I dug into how docker sbx works to see what's feasible here. The short version: it's doable, but not through cctop's current discovery model, which is a two-way join between the host process table and host ~/.claude (collectRows() in src/collect.ts). A sandboxed session breaks both halves at once:

• The agent runs in a microVM (own kernel), so the process never appears in the host process table — no PID to correlate, no CPU/mem to sample.
• Docker's docs are explicit that sandboxes don't pick up host ~/.claude — the session registry, transcripts, and any --capture-usage output are written inside the VM's filesystem.

The only shared channels that exist today are the workspace directory (bind-mounted read-write at the same path in direct-mount mode) and the docker sandbox CLI itself (sbx ls, sbx exec).

One helpful simplification: the 5h/7d rate limits are account-wide, so the existing --capture-usage tap on any host session already reflects sandbox consumption. What's actually missing is the per-session view (live rows) and per-transcript token history (the h dashboard).

Proposal: two layers

Layer 1 — teach cctop about "detached sessions" (sessions without a host PID). Support scanning extra Claude roots (repeatable --claude-dir, or an extraRoots list in ~/.claude/cctop/config.json). Sessions found there become rows keyed by root + sessionId instead of PID, with liveness inferred from registry updatedAt / transcript mtime freshness rather than the process table. They'd render with a distinct host tag (e.g. sbx) and simply lack the process-only affordances: no CPU/MEM, no kill, no ports. The history dashboard merges transcripts across all roots — which is the consolidated utilisation this issue asks for. This layer is generic: it also serves devcontainers, remote-synced setups, and any future sandbox runtime.

Layer 2 — a thin, opt-in Docker adapter that materializes sandbox state into a host cache. A separate command, e.g. cctop sync-sandboxes, that runs docker sandbox ls and per sandbox uses sbx exec to incrementally copy ~/.claude/sessions/ and the tails of changed transcripts into ~/.claude/cctop/sandboxes/<name>/. Layer 1 then treats each cache dir as just another root. Keeping this as its own command (manual, cron, or a background --sync mode) quarantines the one necessary violation of cctop's "read-only, spawns no processes" promise — the TUI itself stays pure.

A zero-docker-CLI alternative for Layer 2: since the workspace is mounted at the same path on both sides, a status-line tap inside the sandbox (extending the existing --capture-usage pattern) could heartbeat session metadata into <workspace>/.sbx/cctop/, which the host sees for free. Cheaper, but needs per-sandbox setup and solves discovery less cleanly, so probably a fallback rather than the main path.

Feasibility caveats:

• Transcripts get large, so the sync must be mtime-gated and tail-based.
• sbx exec into a microVM has real latency — polling belongs in the sync command at a relaxed interval, not the TUI's refresh rate.
• PID-reuse validation can't apply to detached rows, so staleness needs a time-based cutoff instead.

[cleanunicorn]

Honestly, first look seems like it's way too complicated to set this up.

However, I am looking for a way to centralize sessions in a single place (even from multiple machines). I haven't found a good solution yet.