# Handoff — per-user Claude, 2026-08-11 Branch `sidecar-app-store`, based on `48ed171`. **Three files, uncommitted at the time of writing.** This is the start of item 4 in `2026-08-11-per-user-accounts-handoff.md` §6 ("Per-user Claude"), and it revises two claims that handoff and `docs/per-user-linux-accounts.md` both make. Written for the agent on the production host, to read **before** running any of it. Nothing here has been executed against a real member account. Items 1–3 of the earlier handoff (bind mount, terminal replay, `deprovisionOsAccount`) were deliberately skipped on the owner's instruction and are still open. --- ## 1. The claim that changed, and why it matters `docs/per-user-linux-accounts.md:226-229` says `query()` from `@anthropic-ai/claude-agent-sdk` "spawns `claude` itself and takes `env`/`cwd` but has nowhere to put a uid", concluding that dropping privileges must happen *outside* the SDK, which makes a member's turn "its own process — a change of shape rather than a flag." **That is stale.** The installed SDK exposes exactly that hook: ``` node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts:951 spawnClaudeCodeProcess?: (options: SpawnOptions) => SpawnedProcess; sdk.d.ts:936 "Custom function to spawn the Claude Code process. Use this to run Claude Code in VMs, containers, or remote environments." ``` `SpawnOptions` (`sdk.d.ts:2006`) supplies `{command, args, cwd, env, signal}`; `SpawnedProcess` (`sdk.d.ts:1965`) wants `{stdin: Writable, stdout: Readable, killed, exitCode, kill(sig), on('exit'|'error')}` — which is what `node:child_process.spawn` returns natively. So the existing sidecar can wrap the CLI spawn in `sudo setpriv` per turn. No second sidecar, no new PM2 entry, no inverted transport. **VERIFIED:** the type declarations above, and that `bunx tsgo` passes with an implementation written against them. Installed SDK is **0.2.59**; `package.json:31` pins `^0.2.41`. **NOT VERIFIED:** that the hook behaves as documented at runtime. It has never been called. If it turns out the SDK also needs to reach the spawned process in a way `setpriv` breaks, this whole approach is wrong and the fallback is the earlier plan (member turn as its own process). Second stale claim, already corrected once: `docs/per-user-linux-accounts.md:230` still says a member's `claude` "needs only `ANTHROPIC_BASE_URL` pointed at the proxy and no key of its own." The previous handoff §5 retracted that. **Both passages need editing; neither has been edited.** Left alone deliberately so this document is the record of what was believed when the code was written, rather than the doc silently agreeing with the code. --- ## 2. Architecture: the platform never runs as a member The owner's constraint, and the design follows it: **there is never a platform process running under a member's uid.** The platform runs once as the service user and spawns everything. This also rules out the tempting reading of "each member runs their own Claude" — a second `officer-agent` under their uid. It does not work, for a reason worth stating because it looks like plumbing and is actually a boundary. That sidecar needs `POSTGRES_URL` (it imports `officerdb` at `user-instance.ts:19`) and the JWT signing secret (it mints a 30-day owner token for the MCP tools at `user-instance.ts:72`). A member-uid process holding those could read every account's data and sign a token as the owner — strictly more than their shell can do. `docs/per-user-linux-accounts.md:60-82` already forbids this shape: `.env` is 600 and `assertSecretsClosed` refuses to boot with `OFFICER_OS_USERS` on while it is group- or world-readable. So the split is: | | runs as | holds | |---|---|---| | `officer-agent` (the harness) | service user | DB, JWT, MCP config, session log | | `claude` (the member's turn) | **the member** | their binary, their `~/.claude` credential, their home | This is the pty sidecar's established shape — one process, per-request identity, privileges dropped at the point the member's code starts (`sidecar/pty/sessions.mjs:85-93`, `:113-125`). It is not a new pattern. **It also avoids the registry rework.** A second sidecar would have needed one: registration is name-keyed and a same-named sidecar evicts the incumbent (`sidecar-registry.ts:52-57`), `RegisteredSidecar` has no identity field, and all nine claude verbs resolve by capability with no selector (`sidecar-registry.ts:275-402`). Under the one-sidecar shape none of that has to change. --- ## 3. What is in the tree ### `src/servers/os-user-claude.ts` (new) - `provisionClaudeCli({email, osUser})` — runs `curl -fsSL https://claude.ai/install.sh | sh` **as the member**, via `runAs`. Same installer the owner's own install uses (`scripts/setup.sh:853`), chosen there for auto-update support. Per-member binary rather than a shared one is the owner's explicit decision: everything Claude-related is user-specific, and a root-owned binary is one a member cannot update. - Idempotent by **skipping when the binary is present**, not by re-running the installer. The retry button reprovisions on every press; re-downloading would cost a network round trip per press and would quietly move a member off a version they had updated to. - `claudeLoginState({email, osUser})` — `{installed, loggedIn}`. Login marker is `~/.claude/.credentials.json`, **not** `~/.claude.json` (which holds settings/history and appears on first run regardless). - Both checks run **as the member**, not as root. A `true` then means the member's own process can reach those files, which is what the answer gets used to promise. This deviates from the earlier handoff §6.4, which said "detect login by reading `~/.claude` as root" — deliberately. - Never throws; returns a result. Same posture as SSH/shell/Docker in `provisionOsAccount`. ### `src/servers/sidecar/claude/spawn-as-member.ts` (new) The `spawnClaudeCodeProcess` implementation, built on the existing `runAsArgv` (`os-user.ts:95`) — i.e. `sudo -n setpriv --reuid --regid --init-groups --reset-env --`. - **Env is an allowlist, not a filter** (`ALLOWED_ENV`). At the moment of the call, the calling process's environment contains `POSTGRES_URL`, the JWT secret and the owner's `ANTHROPIC_API_KEY`. A denylist would have to be right about every variable that exists now and every one added later. `--reset-env` means nothing crosses unless written into the argv (`os-user.ts:120-124`), so the allowlist is the complete answer to "what can this turn see". - `NEVER_ENV` throws rather than leaks if someone later widens the allowlist or the SDK starts merging its own environment into `SpawnOptions.env`. - Sets `HOME` and `CLAUDE_CONFIG_DIR` to the member's home explicitly. `--reset-env` already sets `HOME` from their passwd entry, so `CLAUDE_CONFIG_DIR` is belt — but "which account's credential did this turn use" should be answerable by reading one line. - Uses `node:child_process`, not `Bun.spawn`: its return value satisfies `SpawnedProcess` (Bun gives web streams and no emitter), and `Bun.spawn` silently ignores `uid`/`gid` anyway (`os-user.test.ts:23`). ### `src/servers/api/users/provision-os.ts` (modified) `provisionClaudeCli` called after `seedShellConfig`, before `provisionRootlessDocker`. Non-fatal. Error precedence is now ssh → claude → shell → docker. --- ## 4. What is NOT wired — read this before testing **`spawn-as-member.ts` is never called.** `claude-manager.ts:350-352` still passes the owner's `CLAUDE_BIN` (`:31`), `HOST_HOME` (`:35`) and `cleanEnv` (`:315`) into `query()`. The remaining work is threading a `MemberRun` through `ClaudeSpawnStreamingParams` and the sidecar protocol so a turn carries whose it is. **Therefore both owner gates must stay up:** - `src/servers/api/chat/chat.ts:49-53` — HTTP refusal of non-owners - `src/server.tsx:214-217` — chat socket refusal Pinned by `capabilities/registry.test.ts:157-170` and `:180-185` so one cannot move without the other. Lifting either now would run a member's turn **as the owner, with the owner's credential** — the exact failure they exist to prevent. Do not lift them to "see if it works". Note `chat` is already granted at `write` for every role by default (`f0af723`, seeded at bootstrap), so the permission is live and the route refusal is the only thing standing in the way. **Still owner-bound, untouched:** - `api/chat/claude-sessions.ts:25` — `claudeHome` is a private copy of the owner-home logic; discards its `email` whenever `HOME_DIR` is set. This is the transcript-history half. - `api/chat/websocket.ts:51-60` — `resolveCwd`/`resolveBaseCwd` expand `~` against `getOwnerHomeDir`. - `workspaces/officerdev/src/apps/ChatHistory/PwdSelector.tsx:12` — shortens with `/^\/home\/[^/]+/`, which will not match a member's `DATA_PATH//home`. Cosmetic. The pwd picker itself is already per-caller correct via `DirPickerModal.tsx:16` → `useFilesAPI('home')` → `rootDir`. The pattern for all of these is `resolveHomeDir` in `src/servers/user-home.ts:34`, which already exists from the file-browser move. --- ## 5. Verified vs assumed **VERIFIED on the dev machine:** - `bunx tsgo` clean across the project with all three files in place. - `bunx prettier --write` on those three files only (not `bun format` — the tree has other uncommitted work). - The SDK type declarations quoted in §1. - `~/.claude/.credentials.json` exists mode 600 on a logged-in account; `~/.claude.json` exists separately. - `CLAUDE_CONFIG_DIR` is honoured by the bundled CLI (4 occurrences in `cli.js`) and by `sdk.mjs` (`CLAUDE_CONFIG_DIR ?? join(homedir(),'.claude')`). Zero occurrences anywhere in this repo before this change. **ASSUMED, NOT TESTED — the whole list:** - That `provisionClaudeCli` succeeds for a real member. It needs network egress as the member and a writable home. `--reset-env` means `PATH` comes from their passwd entry; if `curl` is not on that `PATH` the install fails and the account still provisions, reporting the error. - That the installer writes to `~/.local/bin/claude` when run under `setpriv` with a passwd-derived `HOME`. `claudeBinPath` assumes it does. If it picks a different target the install "succeeds" and the `test -x` gate reports failure, which is the safe direction. - That `claudeLoginState` returns `{installed: true, loggedIn: false}` for a freshly provisioned member and flips after they run `claude` once themselves. - That the spawn hook works at all (§1). - Everything about how this behaves with `DATA_PATH` at 711 with ACLs (`docs/per-user-linux-accounts.md:392-415`). Untested for the agent's paths specifically. --- ## 6. Open questions and known risks **Network isolation is not solved and is not in scope of this change.** A member's `claude` has general outbound reach — it must, to authenticate — which includes loopback, where the platform's own services listen. `docs/per-user-linux-accounts.md:221-225` already says this plainly: not a sandbox; members are isolated from each other and from accidents, not from the host. The terminal and rootless Docker have the same property today. If "a member cannot reach the others or the outside" is a requirement rather than an aspiration, it is a separate stage (per-uid firewalling or a network namespace) covering all three surfaces, and it wants looking at **on the host that actually runs members** — not on the dev box. I probed the dev box for this and the results say nothing about the deployment; disregard any such finding from me. **`curl … | sh` per member sits against this repo's supply-chain stance.** `bunfig.toml` sets `frozenLockfile` precisely so nothing resolves that nobody chose, with the 2026-08-04 npm compromise as the reasoning. This adds an unreviewed network fetch executed once per account creation. It is how the tool ships and what the owner's own install does, and the owner accepted the trade — but it should be a conscious one, not a thing discovered later in a diff. **`spawn-as-member.ts` has no test.** It is the one file standing between a member's turn and the owner's credential, and the guarantee is currently a code-read. The test to write is in the shape of `os-user.test.ts`: assert no `NEVER_ENV` name survives into the argv `runAsArgv` produces, and that `HOME` and `CLAUDE_CONFIG_DIR` point inside the member's home. **Untested interaction with `claude-manager.ts`'s module-level state.** `CLAUDE_BIN` (`:31`) and `HOST_HOME` (`:35`) are resolved once at import, from the *sidecar process's* environment. Both are wrong for a member and both are what the wiring in §4 has to override per turn, not globally. --- ## 7. Running it Provisioning lives in the main server, so the change takes effect with: ``` pm2 restart officer ``` `spawn-as-member.ts` is not imported by anything yet, so `officer-agent` does **not** need restarting and restarting it proves nothing about this change. To exercise the provisioning half on the server: press the terminal/retry icon on a member's row in Settings → User management (`provisionOsAccount` is idempotent and will run the new step), then as root: ```bash sudo ls -l ~/.local/bin/claude # expect: present, owned by the member sudo ls -l ~/.claude/.credentials.json # expect: ABSENT until they log in themselves ``` Then have the member open a terminal and run `claude` once to log in with **their own** account. Confirm the credential appears and that `claudeLoginState` flips. Do not log in on their behalf with the owner's account — that is the thing this whole design exists to avoid. Expect **no change to chat behaviour for anyone**, member or owner: the gates in §4 are still up and the spawn hook is not called. If a member's chat starts working after this change, something is wrong.