AgentHub/docs/plans/remote-clients/README.md

# Remote clients — work runs on each user's machine, the hub only records company spend

Status: **B1–B3 built 2026-11-04 for the Claude pool** (§ Built); B4 and
Codex not started. First decided 2026-10-09, re-scoped 2026-11-04 (this
version). Server mode with S3 stays and runs side by side: a user with a
weak machine keeps working on the hub, a user with their own machine runs
AgentHub local and enrolls it.

## Why

Everyone logging into one machine (server mode, S3) does not scale past ~10
concurrent users: every pane, build and test runs on the hub. Here the compute
moves to each user's machine; the hub keeps identity, the shared accounts, and
the record of what the COMPANY's accounts were used for.

## Decisions (user, 2026-11-04 — replaces the 10-09 list)

1. Each user may install **AgentHub local** on their own machine and enroll it
   with the hub once. **S3 stays** alongside it.
2. **The account decides, not the workspace.** Only a session that runs on a
   company account — the hub's pool or a shared AI Proxy, i.e. one that goes
   through the hub's gateway — is reported. A session on the user's OWN login
   or own proxy sends **nothing**: no conversation, no tokens, no heartbeat,
   not even the workspace's name. Neither does anything run outside AgentHub.
3. What a reported session sends: its **conversation and token usage**, never
   the repository. The hub **never reads the client's source tree, never runs
   anything on the client, never drives it** (no terminal, no start/stop, no
   file access). The client pushes; the hub never connects to a client.
4. Cadence: **one registration** when a company-account session starts
   (session id + device, no content — what the gateway checks), then
   conversation and tokens **once an hour** and once more when the session
   ends. No per-minute heartbeat (user, 11-04). A queue on disk carries what
   an offline machine could not send; it is sent back in the office.
   The conversation is uploaded **whole** (tool results and code included —
   user, 11-04: no stripping); only strings that look like keys, tokens or
   passwords are redacted before sending.
   The hub keeps a conversation **30 days**; token and cost rows are kept.
5. The company account's credential **never leaves the hub**. A client holds a
   device token only; its Claude calls go through the hub's gateway, which adds
   the real credential. Revoking the device token ends access at once.
6. Use of a device token outside AgentHub is **detected**; `remote_gate`
   decides `warn` (default: forward, mark the session unmonitored, alert) or
   `block` (403).
7. The hub is reached over the company LAN only (`10.1.13.7`); a device token
   **expires after 90 days** (`agenthub remote login` again). At home a
   company-account session simply cannot reach the hub — AgentHub local says
   so plainly — while the user's own login works as usual. Working from home
   later means a VPN, never exposing the hub. **No HTTPS** (user, 11-04): plain HTTP
   on the company LAN, accepting that someone already inside the network
   could sniff conversations, hub passwords and device tokens. Adding it
   later is a reverse proxy in front of the hub (docs/SERVER-MODE.md § Put
   HTTPS in front of it), no code change.
8. Company vs own is decided by the **account picked at session start**: an
   enrolled machine's account menu gains "Company account", whose pane talks
   to the hub's gateway; the default login and the user's own AI Proxies are
   their own. It is recorded on the run (`dashboard_runs.proxy`), shown as a
   "Company" badge, and a resume keeps it. A company account is usable only
   through the gateway, so neither side can be mislabelled.
9. Each user can see, on their local AgentHub, what was sent for each
   session and when, and on the hub who (admin/analyst) opened their
   sessions (`audit_log`).
10. On the hub a client's sessions are shown grouped **device › folder** — no
   lane rows are created for them.

## Shape

```
 user machine — AgentHub LOCAL                    hub 10.1.13.7 — SERVER mode
 ┌──────────────────────────────────────┐         ┌──────────────────────────────────┐
 │ pane on a COMPANY account:           │─/v1/… ─▶│ gateway: device token + session  │
 │   ANTHROPIC_BASE_URL = hub gateway   │         │   check → pool credential added  │
 │   ANTHROPIC_AUTH_TOKEN = ahdev_…     │         │   → Anthropic; usage counted now │
 │                                      │─start ─▶│ session registered (id only)     │
 │                                      │─hourly▶│ conversation + tokens            │
 │ pane on the user's OWN login         │  (none) │                                  │
 └──────────────────────────────────────┘         └──────────────────────────────────┘
```

## What "conversation, not source" can and cannot mean

The hub stores no file of the repository. But a conversation is made of what
the agent read and wrote: a transcript's tool results hold the files Claude
`Read`, its `Edit`/`Write` inputs hold code, and every request through the
gateway carries the whole context (code included) on its way to Anthropic.
So "conversation only" still contains source excerpts. Decided (user,
11-04): they are NOT stripped — the transcript goes whole, only secret-shaped
strings are redacted.

## Gateway checks (verified 2026-10-09, Claude Code 2.1.295)

Every `/v1/messages` call carries `x-claude-code-session-id: <id>`, and
`--session-id <uuid>` sets it — `spawnRun` already starts Claude panes that
way. The gateway checks each request:
- bearer = a device token that is not revoked, of a user who is not disabled —
  else **always 401**;
- `x-claude-code-session-id` = a session that SAME device registered at its
  start. The registration, not the hourly upload, is what this check reads.

Relay spike (2026-10-09, script `~/.cache/agenthub-spike/relay.js`): a client
with no login and a fake `ANTHROPIC_AUTH_TOKEN` worked through a relay that
swapped in a team subscription's OAuth token (+ `anthropic-beta:
oauth-2025-04-20`): answers, `--resume`, local tools, prompt-cache reads,
rate-limit headers. Rules it gave:
- set `ENABLE_PROMPT_CACHING_1H=1` in the pane (a base URL drops to 5-minute
  cache entries otherwise);
- keep a session on ONE pool account (the cache is per account);
- give the gateway through `--settings=<file>` (a repo's `.claude/settings*.json`
  `env` overrides the pane env), as AI Proxy panes already do.
Not checked: `/usage`, claude.ai MCP connectors, Remote Control — likely lost
through a relay.

What is and is not guaranteed:
- **Guaranteed:** no hub account / disabled user / revoked device → no company
  credential, because it never leaves the hub — as long as the admin alone
  holds each shared seat's login.
- **Not guaranteed:** that the AgentHub app was used. A device token copied out
  and used with a plain `claude` is caught by the registration check, unless
  the user also fakes a registration. Hard enforcement needs managed machines.
- Quota and budget on company accounts stay **real-time** despite the hourly
  upload: the gateway counts `usage` from each response it relays.

## What already exists (2026-11-04)

| Need | In the code | Missing |
|---|---|---|
| Hooks from another machine | `POST /api/hooks/ingest-batch` + `push-token.js` (`push:<source>`) | one hub-wide token, no user/device; transcript dropped |
| Credential swap | `proxy-gateway.js` (pane token → real key, SSE streamed) | loopback + pane token only |
| Shared accounts | pools, pool groups, pins, own choice, `refreshLogins` | a path for a remote caller |
| Spend per user | `pool-usage.js`, `user-quota.js`, `session-account.js`, Administration user detail | ownership of a session with no lane |
| Transcript import | `importFromDirectory`, `codex-usage.js` | an upload path |

## Phases

Each ships alone and changes nothing for a local-only install.

**B1 — devices and ownership.** Table `devices` (id, user_id, name,
token_hash, created_at, last_seen_at, revoked_at); `agenthub remote login
http://10.1.13.7:4820` (hub password, throttled like `/api/auth/login`) stores
an `ahdev_` token 0600 in the runtime dir; an admin lists and revokes devices
on the user's page (step-up + `audit_log`). Column `sessions.owner_id`,
written from the device's user; `sessionWhere` honours it, so scoping needs no
lane. Verify: mint/hash/revoke tests; revoked → 401; a developer sees only
their own device sessions.

**B2 — gateway for the Claude pool over LAN.** `proxy-gateway.js` gains the
device-token path: heartbeat check, `pickAccount` + session-sticky account,
`usage` counted per response. The local `spawnRun`, on an enrolled machine and
only when the user picks a company account, points the pane at the hub through
`--settings=` and sets `ENABLE_PROMPT_CACHING_1H=1`. Spike first on one real
pool account. Verify: a pane answers "pong"; a curl with a device token and an
unknown session id is logged (`warn`) or 403 (`block`).

**B3 — registration and hourly upload.** For company-account sessions only:
one registration at start; conversation (Claude transcript, Codex rollout) and
tokens hourly and at session end, incremental by byte offset, disk queue,
never blocking a hook. The hub imports with `importFromDirectory` so cost
matches local sessions; shown device › folder on the user's page.

**B4 — shared skills/plugins.** No AgentHub code: company marketplace (git) +
a `managed-settings.json` template for user machines.

Codex comes after B2 works for Claude (ChatGPT-login auth differs from an API
key; its session-id header is unchecked).

## Built (2026-11-04)

Hub side — `server/hub/`, loaded only in server mode (`server/index.js`
requires it inside `isServerMode()`; `server/__tests__/hub-boundary.test.js`
fails if anything outside the folder requires it):

| File | Does |
|---|---|
| `devices.js` | `ahdev_<32 bytes base64url>` tokens, only the SHA-256 kept; 90 days (`AGENTHUB_DEVICE_TOKEN_DAYS`); revoke |
| `remote-sessions.js` | registration (UUID, absolute cwd, `claude` only); one session = one device — another user's device gets `409 EFOREIGN`, the SAME user's new device (enrolled again) takes it over (`moveSession` moves its copy) |
| `remote-gateway.js` | `/api/remote/gw/v1/*`: device token → registered session (waits `AGENTHUB_REMOTE_REGISTER_GRACE_MS`, 5 s, for one in flight) → `claude-pool.forRemote` (sticky per session) → upstream `AGENTHUB_REMOTE_UPSTREAM`; usage read from a decompressed COPY of the answer (Anthropic sends it gzip/br) |
| `remote-ingest.js` | upload chunks at the hub's own offset (`409 EOFFSET` + `expected`), copy under `<data>/remote/u<uid>/d<did>/<sid>/`, `importFromDirectory` once per round (chunks carry `more: true`, the round's closing request imports; a round cut short is imported after `AGENTHUB_REMOTE_FLUSH_MS`, 2 min), then `sessions.source = device:<id>`, `owner_id`; `purgeOld` after `AGENTHUB_REMOTE_RETAIN_DAYS` (30) keeps token rows |
| `index.js` | `/api/remote/device/*` (device token: login, me, logout, sessions, end, files, upload), `/api/remote/*` (signed in: devices, revoke with password + audit, sessions, "who opened mine"), hourly purge |

Shared: `sessions.owner_id` (scope.js, session-account.js, users.js honour
it); `claude-pool.forRemote` and live remote sessions in the pool ranking;
`auth.checkLogin`.

Client side (local mode): `server/lib/remote-client.js` +
`/api/remote-client` + `agenthub remote login|status|upload|logout`, Settings →
AI tools → Company hub. The reserved AI Proxy name `agenthub.company` ("Company
account", Claude only) writes `<data>/proxy-settings/agenthub.company.json` with the
gateway URL, the device token and `ENABLE_PROMPT_CACHING_1H=1`. A company
session is registered at spawn, again on a new session id (SessionStart /
UserPromptSubmit hooks: `/clear`, a fork), uploaded hourly
(`DASHBOARD_REMOTE_UPLOAD_MS`) and soon after SessionEnd; every JSON line goes
through `privacy.redactValue` first.

Measured (2026-11-04): local mode loads none of `server/hub/` (216 server
modules vs 214 before: `remote-client.js` + its route); startup and RSS
unchanged within noise. E2E on one real pool account: answers, sticky account,
`/clear`, resume, hub totals = transcript totals, no device token or key in the
hub copy, revoke → 401, hub down → `503 EHUBDOWN` at start.

Known limits:
- Claude Code reads `ANTHROPIC_AUTH_TOKEN` once: a pane open across a
  re-login (expired or revoked token) keeps failing with 401 until it is
  resumed.
- An unmonitored session is flagged on the hub (`unmonitored`, a warning in
  the log) and, once it has stayed unregistered for
  `AGENTHUB_REMOTE_UNMONITORED_ALERT_MS` (60 s), fires every enabled
  **Company account outside AgentHub** alert rule (`remote_unmonitored`). A
  registration that was only late clears the flag first.
- `AGENTHUB_REMOTE_GATE=block` is covered by unit tests only.
- A shared AI Proxy as a company account, and Codex, are not built.

## Open questions

- Should an admin be able to mark a workspace "company account required"?
  (Today's answer: no — a user's own login in any workspace is their business.)

## Open risks

- A hub outage stops every company-account session; the machine can still use
  its own login.
- Every byte of a company-account session's context passes through the hub in
  transit; tell users.