entities-runtime

A standalone Node.js daemon. Install it on any machine, pair with your +Ai account, and your account can then run Claude Code / Codex sessions on that machine on its behalf — from Vault, from Entity Studio, or from anywhere else in +Ai.

Quick start

npx entities-runtime

The first run prints a 5-letter pairing code and a URL:

Pair this runtime with your +Ai account.

  https://vault.add.ai/entity/connect/HDXYC

Enter this code: HDXYC

Open the URL while signed into Vault, enter the code, and the runtime starts polling for work. Capabilities (claude, codex, git, node) are reported every 30 s.

Commands

entities-runtime                  run the daemon (foreground)
entities-runtime status           pairing + capabilities + last-seen
entities-runtime sessions         recent requests handled (--limit N)
entities-runtime unpair --yes     disconnect from +Ai
entities-runtime version          print version

status and sessions work without the daemon running — they hit Supabase directly using the daemon token in ~/.entities-runtime/state.json.

Architecture

See docs/architecture.md for the full picture: Supabase tables, RPC inventory, request lifecycle, and the cancel-watcher flow.

DiskGuard — Codex scratch-dir disk protection

Each Codex run gets a throwaway CODEX_HOME under the OS temp dir (entities-codex-<rand>). Codex writes its state_*.sqlite, logs, caches and shell snapshots there — typically 50–350 MB per run. codex-spawn now deletes that dir on exit, but a SIGKILL, a crash, or an orphan left by a previous runtime process can skip that path. On a dedicated host doing thousands of runs, those leftovers once grew to ~158 GiB and filled the disk (ENOSPC, repeated crashes).

DiskGuard is the safety net. Like a CCTV DVR overwriting the oldest footage when the disk fills, it watches free space on the volume holding the temp dir and, when usage crosses a high-water mark, deletes the oldest inactive scratch dirs — oldest first — until usage drops back below a low-water mark, leaving a buffer for the OS. It runs at startup, on an interval, and opportunistically right before each new Codex run.

Safety guarantees: it only touches directories directly under the temp root whose names match the configured prefix (realpath-validated); it never deletes a dir owned by a live session (in-process, or one whose session.lock PID is still alive) or one younger than the min-age guard; and it removes symlink entries without following them, so the durable ~/.codex targets behind sessions/auth.json are never harmed.

Note: DiskGuard can only reclaim space by deleting scratch dirs it owns. If a disk is full of other data it will evict what it can and log that it couldn't reach the target rather than touching anything it doesn't own.

Configure via environment variables (defaults shown):

| Variable | Default | Meaning | |---|---|---| | DISKGUARD_ENABLED | true | Master switch for the sweeper. Cleanup-on-exit still runs when false. | | DISKGUARD_HIGH_WATER_PCT | 90 | Start evicting when volume usage reaches this %. | | DISKGUARD_LOW_WATER_PCT | 80 | Stop evicting once usage drops below this %. Clamped below high-water. | | DISKGUARD_MIN_AGE_MINUTES | 30 | Never evict a scratch dir younger than this. | | DISKGUARD_CHECK_INTERVAL_SECONDS | 60 | Periodic sweep cadence. | | DISKGUARD_DRY_RUN | false | Log what would be evicted without deleting anything. | | DISKGUARD_PREFIXES | entities-codex- | Comma-separated dir-name prefixes eligible for eviction. | | DISKGUARD_TEMP_ROOT | os.tmpdir() | Override the watched temp root (mainly for testing). |

Development

npm install
npm run build
node dist/cli.js
npm test        # builds, then runs the node:test suite (see test/)