Skip to content

feat: ls shows when each VM was last connected to and who made it - #260

Merged
benvinegar merged 3 commits into
masterfrom
claude/boxery-available-vms-87f6cf
Nov 15, 2026
Merged

benvinegar merged 3 commits into
masterfrom
claude/boxery-available-vms-87f6cf

Conversation

@benvinegar

@benvinegar benvinegar commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

boxery ls couldn't tell a VM someone is using from one an agent made a week ago and forgot. Now every listing shows when each VM was last connected to and who made it, so leftovers are easy to spot.

Before / after

Same steps on both sides: web-dev made at the CLI and connected to just now, fix-flaky-test made by Claude Code through MCP a week ago and not touched since, old-box made before this change.

boxery ls

Before (master):

NAME            STATE     SSH              DISK       SHAPE     KIND     STATUS
fix-flaky-test  running   127.0.0.1:22001  0.5/40GiB  standard  desktop  -
old-box         shut off  -                0.5/40GiB  standard  desktop  -
web-dev         running   127.0.0.1:22000  0.5/40GiB  standard  desktop  -

After:

NAME            STATE     SSH              DISK       SHAPE     KIND     CONNECTED  CREATED BY                   STATUS
fix-flaky-test  running   127.0.0.1:22001  0.5/40GiB  standard  desktop  7d ago     ben@macbook via claude-code  -
old-box         shut off  -                0.5/40GiB  standard  desktop  -          -                            -
web-dev         running   127.0.0.1:22000  0.5/40GiB  standard  desktop  just now   ben@macbook                  -

fix-flaky-test now reads as what it is: an agent's VM nobody has connected to in a week. old-box shows -, because nothing was recorded before this change.

boxery ls --json

Three new fields on each VM. They don't exist on master. Shown here with jq -c '.[] | {name, created_at, created_by, last_connected_at}':

{"name":"fix-flaky-test","created_at":1794156458,"created_by":"ben@macbook via claude-code","last_connected_at":1794158258}
{"name":"old-box","created_at":null,"created_by":null,"last_connected_at":null}
{"name":"web-dev","created_at":1794764857,"created_by":"ben@macbook","last_connected_at":1794764858}

The terminal header is a short CONNECTED and the JSON field is the explicit last_connected_at. Agents get the same two columns in vm_info list, plus the JSON fields in its structured output.

Captured on the fake backend in a temp directory (ssh and nc stubbed, no VMs). Connections were made by running boxery-host connect, which is what ssh runs as its ProxyCommand. fix-flaky-test's timestamps were moved back a week and old-box's record was cleared, to show an old VM and one from before the change. The username and machine are replaced with ben@macbook.

How it works

  • last_connected_at: connect, the ssh ProxyCommand that every new connection to a VM goes through, rewrites $BOXERY_CONF/last-connected/NAME with a Bash builtin (no fork, no Node, so connections aren't slower), and ls reads the file's mtime. If the file can't be written, the connection still goes through. A file older than the VM (left by an earlier VM of the same name) is ignored, and rm deletes it.
  • created_at / created_by: written to vm_records by new and fork. The controller sends BOXERY_BY=user@machine, adding via CLIENT when an agent makes the VM: the MCP client's name, per session, or pi. Control characters are stripped and the label is capped at 100 characters. It's a label for people to read, not an identity.
  • Store schema v3 adds the two columns, and only the ones that are missing, so a migration that runs twice is harmless.

What it doesn't measure

The name says "last connected", not "last used", on purpose. Only new ssh connections through boxery count:

  • Work running inside the VM doesn't count: a long run --bg job, or a prompt agent in tmux that nobody checks on.
  • boxery reuses an ssh connection until it has been idle for 10 minutes, so a session kept busy for hours shows the time its connection opened.
  • Host-side operations (start, patch, snapshot, ls --refresh) don't count.

So just now reliably means someone reached in, while 7d ago means probably abandoned, not certainly. That's fine for a list a person reads. Anything automatic (stop, prune) would also need a "busy" signal from inside the VM, which this PR leaves out.

Compatibility

  • Older host, newer controller: the host ignores BOXERY_BY, and the new fields are missing from its output. The tables show -, and vm_info list leaves the columns out.
  • Newer host, older controller: the new JSON fields are extra and older controllers ignore them.
  • Rollback: once a host has run this, its store is at v3, and older releases refuse it, as with any schema change (docs/install.md). Their rollback restores the pre-upgrade copy.
  • VMs made before this change show - in CREATED BY. CONNECTED fills in after their next connection.

Testing

  • npm run lint, npm run typecheck
  • npm test: 541 pass, 0 fail. New tests cover the v2→v3 migration and running it twice, record round trips, the creator cleanup, lastConnected, which ignores a file from an earlier VM, BOXERY_BY reaching local and remote hosts only on new/fork, the per-session client in runTool, ago, and the formatVms columns.
  • npm run test:shell: 1,233 pass, 0 fail, including under bash 3.2. These cover connect writing the file, connect still connecting when the directory is unwritable, rm deleting the file, and the ls --json fields from a real new.
  • test/shell/linux/host-upgrade.sh stood in for a future release by bumping the schema to a hardcoded 3. It now reads the current version and adds one, so it keeps working after real schema bumps. The full shell suite, Linux-only tests included, passes under bash 3.2 in the CI container (bash:3.2).
  • Not run: live checks against real hosts.

This PR description was generated by Claude Code using Claude Opus 5.5

benvinegar and others added 3 commits November 15, 2026 10:03
Abandoned VMs were hard to spot: `ls` said nothing about whether anyone still
reached into a VM or whose it was. Now every VM listing has three more fields:

- last_connected_at: when the VM last got a new ssh connection. `connect`, the
  ssh ProxyCommand every VM connection goes through, rewrites
  $BOXERY_CONF/last-connected/NAME with a Bash builtin (no fork, no Node), and
  ls reads its mtime. A file older than the VM (an earlier VM of that name) is
  ignored; rm removes it. Named for what it records: work running inside the
  VM doesn't count, so it isn't "last used".
- created_at, created_by: written to vm_records by new/fork (schema v3, which
  adds the two columns, only those missing). The controller sends
  BOXERY_BY=user@machine on new/fork, with "via CLIENT" for an agent: the MCP
  client's name per session, or pi. Older hosts ignore the variable.

Text ls gains LAST CONNECTED and CREATED BY columns, and so does vm_info list
for agents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
"LAST CONNECTED" made the table 5 columns wider than its values need. The
values ("just now", "7d ago") read as a sentence after CONNECTED, and the JSON
keeps the explicit last_connected_at.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The rollback test played a broken release that bumps the store to schema 3,
hardcoded. With 3 now the real version, its text edits no longer matched.
It now reads SCHEMA_VERSION from the checkout and bumps it by one, so the next
real schema change doesn't break it again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@benvinegar
benvinegar marked this pull request as ready for review November 15, 2026 18:36
@benvinegar
benvinegar merged commit 9e3b4ba into master Nov 15, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant