npm - @kilogent/runner - Versions diffs - 0.1.7 → 0.1.9 - Mend

@kilogent/runner 0.1.7 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +127 -326
package/dist/cli.js +7017 -4965
package/dist/kg-session-launcher.mjs +1047 -0
package/dist/provision-root.mjs +877 -0
package/npm-shrinkwrap.json +1129 -0
package/package.json +12 -6

package/README.md CHANGED Viewed

@@ -1,368 +1,169 @@
 # @kilogent/runner
-The **runner daemon** for [Lumi Crew](https://app.kilogent.com) — your agentic organization
-workspace.
+**Kilogent's internal server runner.** It runs the agent jobs of [Kilogent](https://app.kilogent.com)
+workspaces on Kilogent's own servers.
-Crew agents don't run in the cloud. They run **on your machine**, in your checkouts, with your
-tools. This daemon is what makes that happen: it watches the job queues of the Ships you assign it
-to, claims work oldest-first, and executes each job as a headless agent session on the engine the
-agent runs on.
+> **This is not something a customer installs.** A workspace never has machines: it asks for work,
+> and Kilogent decides which of its servers runs it (PRD §15.89). There is no customer enrolment, no
+> approval and no per-workspace setup. If you are a Kilogent customer, there is nothing here for you
+> to do.
-```bash
-npm i -g @kilogent/runner
-kilogent-runner setup
-```
-## Which package to install
-There are **two**, one per environment. They install side by side — different command names,
-different config directories, different service labels — so one machine can run both.
-| Package | Command | Workspace |
-| --- | --- | --- |
-| `@kilogent/runner` | `kilogent-runner` | production |
-| `@kilogent/runner-dev` | `kilogent-runner-dev` | development |
-The Machines page in your workspace prints the one that matches it. **The package IS the channel**:
-each publishes only a `latest` tag, and a machine changes environment by installing the other one.
-## Requirements
-| | |
-|---|---|
-| **Node.js** | 20 or newer |
-| **An engine CLI** | fetched for you — the daemon installs what your crews need (a few hundred MB each). Bring your own with `CREW_<ENGINE>_BIN`, or decline the lot with `config set autoInstallEngines off`. See [Engines](#engines). |
-| **git / gh** | only if your agents work on GitHub repositories |
-| **A Lumi Crew account** | with at least one Ship — [app.kilogent.com](https://app.kilogent.com) |
-The daemon is a *client*. It signs in as you, and every write it makes is checked server-side
-against your Ship membership. No service-account key ever touches your machine.
-## Engines
-An agent runs on an **engine** — the CLI that actually holds the session. The daemon spawns the
-engine's binary per job, and `doctor` checks that every engine a Ship's agents use is installed.
-**You do not have to install them yourself.** The daemon fetches the CLIs its crews need into its
-own folder (`~/.kilogent-runner/tools/<engine>/`) and runs agents on that copy. A CLI you installed
-yourself is never changed or removed, and the two stay independent: upgrade yours whenever you like,
-the crew keeps running on the version the fleet knows works.
-⚠️ **They are large.** The Codex CLI is about 284 MB installed and Claude Code about 202 MB. Each is
-replaced rather than added to on an upgrade, so a machine running both settles around half a
-gigabyte. To decline the whole thing and manage them yourself:
-```
-kilogent-runner config set autoInstallEngines off
-```
-Which version a machine installs comes from the fleet, not from this machine: it takes the version
-known to work, moves to a newer release only after that release has been out for a day, and never
-installs one another machine has proved broken. If a new version breaks a job here, this daemon puts
-the working version back, runs the job again, and — only if that succeeds — tells the fleet, so no
-other machine installs it.
-```
-kilogent-runner engine list                 what each engine needs, what this machine has, and where it came from
-kilogent-runner engine install [engine...]  install now (--check, --dry-run, --force)
-kilogent-runner engine uninstall <engine>   remove this runner's copy, never yours
-```
-| Engine | Binary | Credential |
-|---|---|---|
-| Claude Code | `claude` ([install](https://claude.com/claude-code)) | a `claude setup-token`, pasted once per Ship in the Crew app |
-| Codex CLI | `codex` ([install](https://developers.openai.com/codex)) | a **machine sign-in**: a captain picks this machine in the Crew app, the daemon runs `codex login --device-auth`, and the captain approves the code on a phone. The login stays on this machine — see [Credentials](#credentials). |
-Each engine's binary can be overridden with `CREW_<ENGINE>_BIN` (`CREW_CLAUDE_BIN`), which wins over
-the copy the daemon installed and is the supported way to pin a machine to a particular binary. It
-is also how the test suites substitute a deterministic fake.
-## Connect a machine
+A server is set up by the command the admin console prints for it (see [Adding a server](#adding-a-server)).
+On a Linux server, as root:
 ```bash
-kilogent-runner setup
+apt-get update
+apt-get install -y --no-install-recommends nodejs curl ca-certificates
+curl -fsSLo kg.tgz https://registry.npmjs.org/@kilogent/runner/-/runner-<version>.tgz
+echo "<sha512 from the console>  kg.tgz" | sha512sum -c
+tar xzf kg.tgz && node package/dist/provision-root.mjs --project <projectId> --api-key <webApiKey>
 ```
-That's the whole thing. It opens your browser at Crew's `/connect` page, where you pick which Ships
-this machine should serve and approve it in one click. The CLI is polling and collects its session,
-runner id and Ship list from the approval — nothing is copied or pasted. If you approve as a
-**captain**, the machine is authorized on your Ships immediately.
-`setup` then runs `doctor` and offers to install the background service.
-### A server or VPS
+## How it works
-`setup` is interactive and refuses without a terminal, but it does not need a browser **on that
-machine**:
-```bash
-kilogent-runner setup --no-browser
 ```
-It prints the approval link and an 8-character code. Open the link anywhere you do have a browser,
-approve this Ship, and the server finishes on its own — nothing is pasted back.
-For CI or unattended provisioning, where nobody is at a terminal at all, paste a Ship key from the
-Daemons page instead — that page prints this command with the two values already filled in:
-```bash
-kilogent-runner login --key <shipKey> --api-key <firebaseWebApiKey> --project <projectId>
+key file ──exchangeFleetKey──▶ the server's own session (no workspace in it)
+   heartbeat every 30 s ──▶ slots, memory budget, pinned version, which leases are still ours
+   wake-up signal / a freed slot / every 15 s ──▶ leaseJobs
+each lease ──▶ its own Firebase app, signed in with a ONE-JOB PASS ──▶ the agent session ──▶ app deleted
 ```
-A key exists only once a captain has approved the machine on that Ship's Daemons page, and it only
-appears in that list after one of the two flows above. So this is the **second** visit to a machine,
-not the first.
-### More than one account
+- **The backend places, the server leases.** The scheduler puts each queued job on one server. A
+  server can only lease the jobs placed on itself, and each lease carries a one-job pass.
+- **The pass is the whole authority for a job.** Progress, transcript, finalize, notes, the credit
+  meter, the AI gateway key, GitHub, MCP connections and the Workspace MCP bearer all use it. It can
+  write only its own job, its own task or chat, and its own agent's status.
+- **A job goes back to the queue only through the backend** (`returnLease`): a retry, a release, a
+  usage limit, or a shutdown.
+- **It stops itself before the backend gives up on it.** With no accepted heartbeat for
+  `staleServerMs − 30 s` (60 s by default), or when a heartbeat is refused, it aborts every session and
+  writes nothing more for them. The backend requeues or fails those jobs by its own rules.
-One machine can serve Ships belonging to **different people**. Run `setup` again and choose *Add
-Ships, from this or another account*; the second person approves in their own browser, with their
-own sign-in.
+## Which package
-Nothing is taken away by that. Approving only ever ADDS Ships, so the machine keeps every key and
-every Ship it already had — the `/connect` page can only see the Ships of whoever is signed in to
-it, so it is never allowed to decide that the others should go. To stop serving one, say so
-explicitly: `kilogent-runner ship remove <shipId>`.
-A machine ends up with one identity per account that approved it — `status` lists them — because a
-runner id belongs to an account rather than to hardware. Only `setup`'s *Disconnect and start over*
-removes anything, and it asks twice.
+| Package | Command | Project |
+| --- | --- | --- |
+| `@kilogent/runner` | `kilogent-runner` | production (`kilogent-crew-prod`) |
+| `@kilogent/runner-dev` | `kilogent-runner-dev` | development (`lumi-afb7d`) |
+They install side by side with different command names, config directories and service labels.
+## Adding a server
+1. In the **admin console → Fleet**, press **Add server**. It shows a one-time **enrolment code** (valid for 30
+   minutes) and the one command for a Linux server or the dev Mac.
+2. Run that command on the machine and paste the code when asked.
+   - **Linux, as root:** it downloads the pinned release, checks its sha512, and runs
+     `node package/dist/provision-root.mjs`. That creates the service user, installs Node, Docker, gVisor and
+     the session firewall, installs the runner in the user's own prefix, enrols, and starts the service.
+     `--plan` shows what it would do and changes nothing.
+   - **The dev Mac, as the runner user:** `npx --yes @kilogent/runner-dev@<version> provision`. Before it, install
+     Node 22 and Docker Desktop, open Docker Desktop once, and set it to start when you sign in. The command
+     installs the runner into `~/.local`, enrols and installs the LaunchAgent; the image is pulled by the server
+     itself. The Mac warnings on the Fleet page (FileVault and automatic login, an administrator account, cloud
+     logins in the account) are advice for a dedicated machine and do not stop work.
+3. The server makes its own key; only its hash leaves the machine. If it enrolled from an address the server
+   does not list, **Approve** it in Fleet with the last four characters of the key the server printed.
+`kilogent-runner doctor` and the Fleet page show the same list of what is not ready yet, each with its fix.
+**Retry sandbox** in the console makes the server check again.
+**A lost, damaged or rotated key** is replaced the same way, never by hand: press **New enrolment code** on the
+server's row and run the command it prints. That command ends in `--re-enrol`, so a machine that already has a
+key enrols again and replaces it. The old key keeps working until then. To cut it off sooner, disable the server,
+and enable it again just before you run the command: a code used while the server is disabled is refused.
+**Disabling a server** in the console revokes its sessions and recovers its jobs. The daemon stops its
+sessions, keeps retrying the exchange with backoff, and takes work again once it is enabled.
 ## Commands
 | Command | What it does |
 |---|---|
-| `setup` | One-time onboarding: login → pick Ships → doctor → background service |
-| `login` | Connect this machine (browser approval, `--no-browser` for a server, or `--key` for CI) |
-| `ship add [ids…]` / `remove` / `list` | Which Ships this machine serves (omit ids to pick from a list) |
-| `doctor` | **Preflight** — can this machine actually run a job? Non-zero exit if not |
-| `service install` / `uninstall` / `restart` / `status` | Run the daemon in the background, always |
-| `uninstall` | Remove the service, then tell you the `npm rm -g` step (`--purge` also clears config) |
-| `start` | Run the daemon in the foreground |
-| `status` | Ships, approval state, current job, queue depth, today's tokens |
-| `logs [-f]` | The daemon's own rotating log file |
-| `update [--check]` | Install the latest published version and restart (see **Staying current**) |
-| `config list` / `set <key> <value>` | `notifications`, `keepAwake`, `autoUpdate`, `checkEvery`, `parallel` |
-Global flags: `--json` (machine-readable stdout, and never prompts), `-y/--yes`, `--no-color`.
-Without a TTY the CLI does not prompt at all — it fails naming the flag that would have answered the
-question, because a wizard blocking on a hidden stdin inside a systemd unit is indistinguishable
-from a hang.
-### `doctor`
-Run this first when something isn't working. Everything it checks used to be discovered *inside a
-running job*, surfacing as a failed task on your board minutes later: a missing engine binary,
-unsaved Ship credentials, a machine no captain approved. It checks Node ≥ 20, your stored session,
-per-Ship approval and credentials, the engine binary, `git`/`gh` when an agent uses GitHub, server
-reachability, the background service, whether that service still points at a CLI that exists, and
-whether the **service's own `PATH`** can still reach the binaries your jobs spawn — which is a
-different question from whether your shell can (see below).
-### Background service
-`kilogent-runner service install` writes a real OS service — **no root required**:
-| OS | Mechanism | Note |
-|---|---|---|
-| macOS | `~/Library/LaunchAgents/com.kilogent.runner.plist` (`RunAtLoad` + `KeepAlive`) | |
-| Linux | `~/.config/systemd/user/kilogent-runner.service` (`Restart=always`) | run `sudo loginctl enable-linger $USER` or it stops at logout |
-| Windows | Task Scheduler, at logon | no auto-restart; use pm2 for a true always-on box |
-Your `PATH` is captured into the unit at install time. launchd and systemd start processes with a
-minimal environment, so without that `claude`, `git` and `gh` would not be found.
-**It is captured once, and a restart does not refresh it.** `service restart` re-runs the unit
-exactly as written, so a daemon keeps the `PATH` of whatever shell first installed it. Install a
-tool somewhere new afterwards — `~/.local/bin`, a Homebrew prefix, an nvm switch — and the daemon
-cannot see it, while every check you can run by hand (`which claude`, `kilogent-runner doctor`) is
-answered by your *current* shell and looks fine. The symptom is a job that fails minutes later
-with `spawn claude ENOENT`.
-Two things close that gap: `doctor` reports it as **Service PATH**, and `kilogent-runner setup` now
-reinstalls the service (rather than merely restarting it) when your environment has drifted from
-the installed unit. To fix it directly, from a shell where the tool works:
-```bash
-kilogent-runner service install    # rewrites the unit with your current PATH
-```
-## How many jobs at once
-One, until you say otherwise — the same behaviour this daemon has always had.
-```bash
-kilogent-runner config set parallel 3                    # this machine, across every Ship
-kilogent-runner config set parallel 1 --ship shp_abc123  # cap one Ship's share of it
-kilogent-runner config set parallel default --ship shp_abc123   # back to the machine number
-kilogent-runner config list                              # what is set, and what each Ship gets
-```
-The machine number is a ceiling, not a total: three Ships at `2` each on a machine set to `3` will
-never run more than three sessions. A Ship with no number of its own may use the whole machine.
-Each job is a separate engine process with its own empty working directory, so they don't share
-state — but they do share your CPU, your RAM and your subscription's usage window. Start at 2 and watch a
-real job before going higher. Restart the daemon (`kilogent-runner service restart`) to pick up a change.
-## MCP servers that run on this machine
-A Ship can register MCP connections its agents reach. Most are remote — an `https://` address the
-session talks to. Two kinds are **local**: a program this machine starts (`npx -y some-mcp-server`,
-`node ./my-server.mjs`), and a server already listening on this machine's own loopback address
-(`http://127.0.0.1:3000/mcp`).
+| `provision --project <id> --api-key <key> [--code-stdin] [--re-enrol]` | Set up the dev Mac as this user. A Linux server uses `dist/provision-root.mjs` as root. `--re-enrol` replaces an existing key with the code. |
+| `enrol --project <id> --api-key <key> [--replace]` | Enrol with a one-time code read from stdin; the server makes its own key. `--replace` gives a server that has a key a new one, and puts the old one back if the code is refused. |
+| `connect --key-file <path> --project <id> [--api-key <key>]` | Make this machine a Kilogent server from an existing key file. |
+| `doctor [--fix]` | The readiness list with each fix, and the key exchange, engines and service. Non-zero exit only for what stops work. `--fix` repairs the key file's mode. |
+| `start` | Run the daemon in the foreground. |
+| `service install` / `uninstall` / `restart` / `status` | Run the daemon as an OS service. `restart`, and `install` over a running service, let running jobs finish first; `--now` does not wait. |
+| `status` | What the daemon last wrote about itself (`<configDir>/fleet-state.json`): phase, heartbeat, slots, running jobs, engines, pin. |
+| `logs [-n N] [-f]` | The daemon's rotating log file. |
+| `engine list` / `install` / `uninstall` | The engine CLIs sessions run on. |
+| `update [--check] [--dry-run]` | Install the latest published version by hand. |
+| `config list` / `set <key> on\|off` | `notifications`, `keepAwake`, `autoInstallEngines`. |
+| `uninstall [--purge]` | Remove the service, then print the `npm rm -g` step. `--purge` also deletes the config directory — and the key file only if it lives inside it, which the confirmation says. |
+Global flags: `--json`, `-y/--yes`, `--no-color`.
+Everything that decides what a server does — how many jobs it runs, its memory budget, draining,
+which version the fleet runs, which workspaces are rolled out — is set in the **admin console**, not
+here, and reaches the server with its heartbeat.
+## The sandbox
+Every Kilogent server runs every workspace's jobs, so each session runs in a container from the image its
+release names, by digest, pulled with a short-lived token the server asks for over its own fleet session. A
+server takes no work until it has pulled that image and a probe container has proved a session can run.
+On Linux the runner's user cannot reach Docker at all: every session goes through a root-owned launcher, under
+gVisor, on a network that cannot reach the host, the cloud metadata service or private addresses. The dev Mac
+runs sessions with Docker Desktop and claims no such boundary.
+Where the console turns it on (§15.92), a session starts at a small memory limit and the runner raises it while
+the session runs, up to a max set in the console: the root launcher does it on Linux, the daemon itself on the
+Mac. The heartbeat reports the memory this server has for sessions and what its sessions really use, and the
+backend places work by those numbers. A session stopped at its max fails its job with a sentence saying so; one
+stopped below its max goes back to the queue and runs again from its max.
+A session runs directly on the machine only in a local emulator stack (both `FIRESTORE_EMULATOR_HOST` and
+`FIREBASE_AUTH_EMULATOR_HOST` set).
-**Those are off until you allow them, one Ship at a time.**
-```bash
-kilogent-runner config set local-mcp on --ship shp_abc123    # this Ship may run programs here
-kilogent-runner config set local-mcp off --ship shp_abc123   # stop allowing it
-kilogent-runner doctor                                       # which Ships have local connections, and whether they may run
-```
-There is no machine-wide form on purpose. A captain registers these in a browser and may not be the
-person who owns this computer — and if this daemon serves several Ships, a single switch would enrol
-every one of them, including any added later. So it is granted per Ship, by you, here.
-What a Ship gets when you allow it: the connections a captain registered **on that Ship**, activated
-on the agent running the job, and nothing else. The daemon writes them into the session's config
-file — your own `~/.claude.json` and any `.mcp.json` lying around are still invisible to every agent
-session, exactly as before.
+## Engines
-Credentials for these live on the Ship, not here: a captain marks a variable secret and it is stored
-where nothing reads it back, then handed to the program at start and scrubbed from the transcript.
-Press **Test** on the connection in Ship Settings and this machine runs the test and reports what it
-found — the Crew backend cannot reach a program on your laptop, so it asks you instead. Restart the
-daemon (`kilogent-runner service restart`) after changing this.
+The daemon installs every engine it has an installer for when it starts, reports each engine's state
+on every heartbeat, and installs one on demand when a lease needs it. A binary given by
+`CREW_<ENGINE>_BIN` is the operator's: it is reported as `unmanaged` and never installed over. Deep
+Agents has no installer; point `CREW_DEEPAGENTS_BIN` at it.
-## Staying current
+Which version is installed comes from `crewConfig/engines`. If a new version breaks a job, the
+daemon puts the known-good version back, runs the job again, and — only if that works — reports the
+version so no other server installs it.
-**This machine updates itself.** Every half hour the daemon asks npm whether there is a newer
-version of the package it was installed from. When there is, it stops claiming new work, lets the
-jobs it is already running **finish**, installs the new version, and exits — launchd and systemd
-restart it, which is what picks up the new code. A captain sees all of it on the Daemons page.
+## The pinned version
-It only ever does this when the background service is installed and running, because "exit and be
-restarted" is the whole mechanism: a daemon you started by hand in a terminal tells you about the
-update and leaves it to you. Windows is the same — the running file is locked there and the
-scheduled task does not restart on exit — so `kilogent-runner update` prints the command instead.
+The console pins one exact runner version for the fleet, and records npm's integrity for it. A server whose
+version differs checks that npm still gives the pinned bytes, pulls and probes the next release's image while
+it keeps working, and only then drains (finishes its jobs, takes no new ones), installs **that exact version**
+and exits so the service restarts it. The pin reaches a few servers at a time, so the fleet never stops
+together. When a server cannot move, the reason is shown in the console.
-```bash
-kilogent-runner update --check     # is there a newer version?
-kilogent-runner update             # install it now and restart the service
-```
+## Shutting down
-To pin a machine to a version:
-```bash
-npm i -g @kilogent/runner@0.5.7
-kilogent-runner config set autoUpdate off
-```
-Other settings, all machine-wide:
-```bash
-kilogent-runner config set checkEvery 360     # ask less often (minutes, 5–1440)
-```
-A version is never installed twice: three failed attempts at the same one and the machine stops
-trying until a different version is published. `kilogent-runner doctor` reports whether you are behind,
-always as a warning — being out of date never fails the preflight.
-## While a job runs
-- **Idle sleep is inhibited** (`caffeinate` / `systemd-inhibit`, best-effort on Windows), so a
-  laptop doesn't suspend mid-session. It cannot veto you choosing Shut Down — no background process
-  gets that veto on macOS, and it shouldn't.
-- **Desktop notifications are off by default.** They fire on job start, finish, terminal failure and
-  on a daemon stopped with work in flight — which on a busy machine is an interruption every few
-  minutes carrying nothing the task board and the Daemons live log do not already show. Turn them on
-  with `kilogent-runner config set notifications on`. (Sleep inhibition is a separate setting and stays
-  on: "don't close the lid" is `keepAwake`, not a notification.)
-- **SIGTERM releases the job.** The daemon aborts every running session, hands each job back to the
-  queue with its retry budget **unspent**, and only then writes itself offline. Stopping the daemon
-  never costs you an attempt.
-## Credentials
-Agent-session credentials — a pasted engine token and, if your agents use GitHub, a token for that —
-are **not** stored on this machine. A captain saves them once per Ship in the Crew app's Ship
-Settings, and the daemon fetches them at job time, injects them into the session environment, and
-redacts them from the transcript before upload. `kilogent-runner doctor` tells you when a Ship is
-missing them.
-**Machine sign-ins are the exception, on purpose.** An engine whose account has no static token
-(Codex on a ChatGPT plan: its login rotates a refresh token on every use, so a copy on a second
-machine kills the first) is signed in ON ONE MACHINE. The daemon keeps that login in a private
-directory, `~/.kilogent-runner/engines/<engine>/<ship>/<credential>/`, refreshes it itself, and
-never sends it anywhere. Jobs on that credential run on this machine only; the daemon runs one
-session per sign-in at a time. Deleting the credential in the app signs this machine out and removes
-the directory; so does removing the machine from the Ship, and `kilogent-runner uninstall --purge`.
-`doctor` reports each sign-in this machine holds and whether the engine still accepts it.
-The only other thing stored locally is your own session, in `~/.kilogent-runner/config.json`
-(mode `0600`).
+SIGTERM aborts every session and hands each job back with its retry unused, then sends a last
+heartbeat that takes the server out of placement at once. Whatever did not get back within the grace
+period, the backend recovers.
 ## Uninstalling
-Remove the service **before** the package:
+Remove the service **before** the package, or the service keeps restarting a binary that no longer
+exists:
 ```bash
 kilogent-runner uninstall
 npm rm -g @kilogent/runner
 ```
-Order matters, and getting it wrong is silent. The launchd plist / systemd unit records an
-*absolute path* to the CLI inside `node_modules` — it has to, since the OS needs something to exec.
-`npm rm -g` deletes that file but knows nothing about your service, so the service stays registered
-and keeps respawning a binary that is no longer there, roughly every ten seconds, for as long as
-the machine lives. npm cannot help here: since npm 7 it does not run `preuninstall`/`postuninstall`
-scripts at all, so no package can clean up after itself.
-Already removed the package? Reinstall it, uninstall properly, then remove it again:
-```bash
-npm i -g @kilogent/runner && kilogent-runner uninstall && npm rm -g @kilogent/runner
-```
-`kilogent-runner doctor` reports a machine that is already in this state, naming the missing path.
-Neither command touches `~/.kilogent-runner`. That directory is this machine's **identity** — the
-runner id each account knows it by, and its Ship keys — so uninstalling and reinstalling keeps the
-approvals your captains already granted. Add `--purge` to delete it too, and expect to be approved
-again from scratch, by every account.
-## Upgrading from `crew-runner`
-This package was previously distributed inside the Lumi monorepo as `@lumi/crew-runner`, with a
-`crew-runner` command. If that's what you have:
-```bash
-crew-runner service uninstall
-npm rm -g @lumi/crew-runner
-npm i -g @kilogent/runner
-kilogent-runner service install
-```
-You do **not** need to log in again. `~/.crew-runner` is migrated to `~/.kilogent-runner` automatically
-on the first run, which keeps your machine's identity — and therefore the approvals your captain
-already granted it. `service install` also removes the old `com.lumi.crew-runner` /
-`crew-runner.service` unit if the uninstall above was skipped, so you never end up with two daemons
-claiming from one queue.
 ## Environment variables
 | Var | Effect |
 |---|---|
-| `LUMI_RUNNER_HOME` | Config + log directory (default `~/.kilogent-runner`) |
-| `CREW_<ENGINE>_BIN` | Path to an engine's binary, e.g. `CREW_CLAUDE_BIN`, `CREW_CODEX_BIN` (default: the copy this runner installed, else the engine's own name from `PATH`) |
-| `CREW_MACHINE_LOGIN_TIMEOUT_MS` | How long a machine sign-in may wait for approval before it is reported expired (default: 16 minutes; a test seam) |
-| `CREW_NO_NOTIFY` | Force desktop notifications off, whatever the config says (they are off by default) |
-| `CREW_NO_POWER` | Disable sleep inhibition |
-| `LUMI_RUNNER_REGISTRY` | npm registry to check for updates (default `https://registry.npmjs.org`) |
-`CREW_RUNNER_HOME` is still honoured as a fallback for machines configured before the rename.
+| `CREW_SANDBOX_IMAGE` | A locally built session image, read **only in a local emulator stack**. A server runs its release's image. |
+| `CREW_SANDBOX_RUNTIME` / `CREW_SANDBOX_NETWORK` / `CREW_SANDBOX_USER` | Container runtime, network and user when Docker is used directly (the dev Mac, a local stack). |
+| `CREW_<ENGINE>_BIN` | An engine's binary, e.g. `CREW_CLAUDE_BIN`, `CREW_DEEPAGENTS_BIN`. |
+| `LUMI_RUNNER_HOME` | Config and log directory (default `~/.kilogent-runner`). |
+| `CREW_FUNCTIONS_URL` / `CREW_MCP_URL` | Override the Functions and Workspace MCP endpoints (emulators, e2e). |
+| `CREW_NO_NOTIFY` / `CREW_NO_POWER` | Turn off desktop notifications / sleep inhibition. |
+| `LUMI_RUNNER_REGISTRY` | npm registry for `update` (default `https://registry.npmjs.org`). |
 ## License