@gapi/gcli 1.8.239 → 1.8.240

package/.agents/skills/local-ai-runners/SKILL.md

@@ -23,6 +23,12 @@ security, symptom table): `graphql-server/docs/features/local-ai-runners.md`.
 - Socket close aborts every in-flight Ollama request; a refused token is
   fatal (`RunnerAuthError`), everything else reconnects with backoff.
 - Global `WebSocket` -> Node >= 22.
+- Daemon (`runner:daemon:*`, `daemon.ts`): systemd USER unit; never put the
+  token or other secrets in the unit (it's world-readable-ish config) - it
+  runs `runner:start`, which reads the 0600 `runner.json`. Keep exit code 78
+  for "token refused" in sync with `RestartPreventExitStatus`. Tests must
+  pass an explicit home dir to `SystemdUserService` (os.homedir() ignored a
+  changed HOME under jest and wrote into the real `~/.config` once).
 
 ## Run it against a dev stack
 

package/README-CLI.md

@@ -1,68 +1,54 @@
 Usage: gcli [options] [command]
 
 Options:
-  -V, --version                 output the version number
-  -h, --help                    display help for command
+  -V, --version                                        output the version number
+  -h, --help                                           display help for command
 
 Commands:
-  login [options]               Login to graphql-server
-  lambda:list [options]         List of all lambdas for project
-  lambda:get [options]          Get lambda by id
+  login [options]                                      Login to graphql-server
+  lambda:list [options]                                List of all lambdas for project
+  lambda:get [options]                                 Get lambda by id
   lambda:create [options]
   lambda:update [options]
-  lambda:delete [options]       Get lambda by id
-  lambda:log [options]          Get lambda log
-  lambda:build:log [options]    Get build log
-  lambda:test [options]         Test lambda
+  lambda:delete [options]                              Get lambda by id
+  lambda:log [options]                                 Get lambda log
+  lambda:build:log [options]                           Get build log
+  lambda:test [options]                                Test lambda
   lambda:package [options]
-  project:list                  List of all projects
-  project:use <project>         Adds default project to be used all around the
-                                CLI
-  project:clear                 Clears default project to be used all around
-                                the CLI
-  build [options]               Build bundle using esbuild
-                                https://esbuild.github.io
-  environment:list [options]    List of all environments for project
-  environment:create [options]  Create environment for project
-  environment:update [options]  Update environment for project
-  environment:delete [options]  Delete environment for project
-  environment:get [options]     Get environment for project
-  mcp:start [options]           Start mcp proxy server
-  start [options]               Start bundle using esbuild
-                                https://esbuild.github.io
-  cron:create [options]         Create cron
-  cron:delete [options]         Delete cron
-  cron:list [options]           List of all cron jobs for project
-  cluster:create [options]      Provision a private Talos cluster for a project
-                                (runs in the background - takes several
-                                minutes; use --wait to block)
-  cluster:list [options]        List every private cluster this project has (it
-                                may have several - dev/stage/prod, ...)
-  cluster:teardown [options]    Tear down one of a project's clusters (runs in
-                                the background - use --wait to block)
-  cluster:kubeconfig [options]  Print (or save) a cluster's raw kubeconfig YAML
-                                - only available once it's 'ready'
-  rabbitmq:create [options]     Provision a RabbitMQ broker for a project (a
-                                project may have several)
-  rabbitmq:list [options]       List every RabbitMQ broker for a project
-  rabbitmq:delete [options]     Delete a RabbitMQ broker
-  plugin:list                   List every plugin available in the marketplace
-                                catalog
-  plugin:installed [options]    List plugins installed for a project (may
-                                include the same plugin on several clusters)
-  plugin:install [options]      Install a marketplace plugin for a project
-  plugin:uninstall [options]    Uninstall a plugin from a project (--cluster
-                                picks which installation, if it's on several)
-  runner:start [options]        Connect this machine's Ollama to the Lambforge
-                                chat as a local AI runner (outbound connection
-                                only - works behind NAT, Ollama is never
-                                exposed)
-  runner:list                   List your local AI runners and the models they
-                                serve
-  runner:models [options]       Choose which of a runner's models appear in the
-                                chat model picker (no flags: list them)
-  runner:delete [options]       Delete a local AI runner and revoke its token
-  help [command]                display help for command
+  project:list                                         List of all projects
+  project:use <project>                                Adds default project to be used all around the CLI
+  project:clear                                        Clears default project to be used all around the CLI
+  build [options]                                      Build bundle using esbuild https://esbuild.github.io 
+  environment:list [options]                           List of all environments for project
+  environment:create [options]                         Create environment for project
+  environment:update [options]                         Update environment for project
+  environment:delete [options]                         Delete environment for project
+  environment:get [options]                            Get environment for project
+  mcp:start [options]                                  Start mcp proxy server
+  start [options]                                      Start bundle using esbuild https://esbuild.github.io 
+  cron:create [options]                                Create cron
+  cron:delete [options]                                Delete cron
+  cron:list [options]                                  List of all cron jobs for project
+  cluster:create [options]                             Provision a private Talos cluster for a project (runs in the background - takes several minutes; use --wait to block)
+  cluster:list [options]                               List every private cluster this project has (it may have several - dev/stage/prod, ...)
+  cluster:teardown [options]                           Tear down one of a project's clusters (runs in the background - use --wait to block)
+  cluster:kubeconfig [options]                         Print (or save) a cluster's raw kubeconfig YAML - only available once it's 'ready'
+  rabbitmq:create [options]                            Provision a RabbitMQ broker for a project (a project may have several)
+  rabbitmq:list [options]                              List every RabbitMQ broker for a project
+  rabbitmq:delete [options]                            Delete a RabbitMQ broker
+  plugin:list                                          List every plugin available in the marketplace catalog
+  plugin:installed [options]                           List plugins installed for a project (may include the same plugin on several clusters)
+  plugin:install [options]                             Install a marketplace plugin for a project
+  plugin:uninstall [options]                           Uninstall a plugin from a project (--cluster picks which installation, if it's on several)
+  runner:start [options]                               Connect this machine's Ollama to the Lambforge chat as a local AI runner (outbound connection only - works behind NAT, Ollama is never exposed)
+  runner:daemon:install|runner:start:daemon [options]  Run the runner in the background as a systemd user service: starts with your session, restarts on failure (Linux)
+  runner:daemon:status [options]                       Show the runner service status (systemctl --user status)
+  runner:daemon:logs [options]                         Follow the runner service log (journalctl --user -f)
+  runner:daemon:uninstall [options]                    Stop and remove the runner service (the runner stays registered)
+  runner:list                                          List your local AI runners and the models they serve
+  runner:models [options]                              Choose which of a runner's models appear in the chat model picker (no flags: list them)
+  runner:delete [options]                              Delete a local AI runner and revoke its token
+  help [command]                                       display help for command
 
 --- Subcommand: login ---
 Usage: gcli login [options]
@@ -646,6 +632,50 @@ Options:
   --reset              Forget the saved runner and register a new one
   -h, --help           display help for command
 
+--- Subcommand: runner:daemon:install ---
+Usage: gcli runner:daemon:install|runner:start:daemon [options]
+
+Run the runner in the background as a systemd user service: starts with your session, restarts on failure (Linux)
+
+Options:
+  -n, --name <name>    Runner name when registering (default: hostname)
+  -t, --token <token>  Runner token for a machine without `gcli login`
+  --ollama <url>       Ollama URL (default: $OLLAMA_HOST or
+                       http://127.0.0.1:11434)
+  --wsUrl <url>        Lambforge subscriptions endpoint override
+  --reset              Forget the saved runner and register a new one
+  --service <name>     systemd unit name (default: lambforge-runner)
+  --dry-run            Print the unit file instead of installing it
+  -h, --help           display help for command
+
+--- Subcommand: runner:daemon:status ---
+Usage: gcli runner:daemon:status [options]
+
+Show the runner service status (systemctl --user status)
+
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  -h, --help        display help for command
+
+--- Subcommand: runner:daemon:logs ---
+Usage: gcli runner:daemon:logs [options]
+
+Follow the runner service log (journalctl --user -f)
+
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  --lines <n>       Lines of history to show first (default 50)
+  -h, --help        display help for command
+
+--- Subcommand: runner:daemon:uninstall ---
+Usage: gcli runner:daemon:uninstall [options]
+
+Stop and remove the runner service (the runner stays registered)
+
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  -h, --help        display help for command
+
 --- Subcommand: runner:list ---
 Usage: gcli runner:list [options]
 

package/README.md

@@ -744,6 +744,26 @@ running until Ctrl+C and reconnects on its own.
 | `gcli runner:list` | Your runners: online status, last seen, models |
 | `gcli runner:models` | List which models are shown in the chat; `--show a,b` shows only those, `--all` shows every model, `--none` hides them all; `--id` picks a runner (default: this machine's) |
 | `gcli runner:delete` | Delete a runner and revoke its token (`--id`, default: this machine's) |
+| `gcli runner:start:daemon` / `runner:daemon:install` | Install + start the runner as a systemd user service (Linux); `runner:daemon:status`, `runner:daemon:logs`, `runner:daemon:uninstall` manage it |
+
+### Run it in the background (systemd, Linux)
+
+```bash
+npm i -g @gapi/gcli                 # a stable install - not the npx cache
+gcli login
+gcli runner:start:daemon            # = runner:daemon:install; same options as runner:start
+gcli runner:daemon:status
+gcli runner:daemon:logs             # follow the log (Ctrl+C to stop following)
+gcli runner:daemon:uninstall        # stop + remove the service (runner stays registered)
+```
+
+It installs a systemd **user** service (`~/.config/systemd/user/lambforge-runner.service`,
+no `sudo`) that starts with your session and restarts on failure. The runner
+token stays in `~/.graphql-server/runner.json`, never in the unit file; a
+revoked token stops the service instead of restart-looping. To keep it
+running after logout and start it at boot, enable lingering once:
+`sudo loginctl enable-linger $USER`. Preview the unit with `--dry-run`;
+`--service <name>` installs several runners side by side.
 
 Notes:
 

package/docs/changelog.d/2026-10-11-local-ai-runners-run-the-runner-as-a-systemd-user-service.md

@@ -0,0 +1,36 @@
+## 2026-10-11 - local-ai-runners: run the runner as a systemd user service
+
+**Feature:** local-ai-runners · **Type:** feat
+
+- `gcli runner:daemon:install` (alias `runner:start:daemon`) resolves or
+  registers the runner first (gcli login session, or `--token` saved to the
+  0600 `~/.graphql-server/runner.json`), then writes
+  `~/.config/systemd/user/lambforge-runner.service` and runs
+  `systemctl --user daemon-reload / enable / restart`. The unit runs
+  `<node> <gcli script> runner:start --ollama <resolved URL>` (or the SEA
+  binary), `Restart=always`, `RestartSec=5`, `WantedBy=default.target`.
+  `runner:daemon:status`, `runner:daemon:logs` (journalctl -f) and
+  `runner:daemon:uninstall` manage it; `--service` allows several,
+  `--dry-run` prints the unit.
+- Adapted from packages/cli-builder `SystemctlService`; differences: a user
+  unit (no root, runs as the owner of runner.json), the token never goes
+  into the unit, commands run via execFile (no shell), and
+  `runner:start` now exits 78 on a refused token with
+  `RestartPreventExitStatus=78` so systemd doesn't restart-loop. Warns when
+  gcli runs from the npx cache and when lingering is off (stops at logout).
+- Linux-only for now (clear error elsewhere).
+- **Test:** `npx jest test/runner-daemon.spec.ts --coverage=false` (unit
+  content/quoting, no token, command resolution incl. SEA and npx warning,
+  the systemctl call sequence against a fake exec and a temp home).
+  Manual: `gcli runner:start:daemon --dry-run`, then install,
+  `systemctl --user status lambforge-runner`, reboot or log out/in.
+- **Debug:** `gcli runner:daemon:logs` (= `journalctl --user -u
+  lambforge-runner -f`); service "inactive (dead)" with status 78 = token
+  refused -> `gcli runner:start --reset` then reinstall; stops at logout =
+  `sudo loginctl enable-linger $USER`; ExecStart path gone = gcli was in the
+  npx cache -> install globally and reinstall.
+- **Verification:** gcli 38/38, tsc + eslint clean; `--dry-run` of the built
+  CLI prints the expected unit. Not installed live on the dev machine. A
+  first test version leaked a stub unit into the real ~/.config (home dir
+  not injectable) - removed, and the service now takes the home dir
+  explicitly.

package/docs/features/local-ai-runners.md

@@ -13,6 +13,8 @@ what lives in gcli.
 | `gcli runner:list` | Your runners: online, last seen, models |
 | `gcli runner:models [--id] [--show a,b \| --all \| --none]` | Which models appear in the chat picker; no flag = list |
 | `gcli runner:delete [--id]` | Delete a runner and revoke its token (default: the saved one) |
+| `gcli runner:daemon:install` (alias `runner:start:daemon`) `[runner:start options] [--service] [--dry-run]` | Resolve/register the runner now (saves `runner.json`), then install + enable + restart a systemd USER unit running `runner:start --ollama <resolved>` (Linux) |
+| `gcli runner:daemon:status` / `:logs` / `:uninstall` | `systemctl --user status`, `journalctl --user -f`, disable --now + remove the unit |
 
 Endpoints: `--wsUrl` > `runner.json` > derived from the `gcli login` URL
 (`https://api.lambforge.com` -> `wss://api.lambforge.com/subscriptions`;
@@ -42,6 +44,15 @@ Ollama: `--ollama` > `$OLLAMA_HOST` (scheme optional, `0.0.0.0` -> `127.0.0.1`)
   The backend fits every request to it, because Ollama silently drops the
   oldest messages of a prompt that is too long (see the canonical doc,
   "Context window").
+- `daemon.ts` - `buildUnit` (pure; systemd quoting; `Restart=always`,
+  `RestartPreventExitStatus=78`), `resolveGcliCommand` (node + script, or
+  the SEA binary; warns for the npx cache), `SystemdUserService`
+  (`systemctl --user` via execFile, never a shell; home dir injectable so
+  tests can't touch the real `~/.config`). `daemon-commands.ts` - the
+  `runner:daemon:*` actions. Adapted from cli-builder's `SystemctlService`,
+  but a USER unit (no root) and no secrets in the unit. `runner:start` exits
+  78 (EX_CONFIG) when the token is refused, so systemd stops instead of
+  restart-looping.
 - `config.ts` (saved runner, URL derivation), `start.ts`, `list.ts`,
   `models.ts`, `delete.ts`, `index.ts` (command registration), `types.ts`.
 - `src/services/gql-client.ts` - `createLocalRunner`, `listLocalRunners`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gapi/gcli",
-  "version": "1.8.239",
+  "version": "1.8.240",
   "repository": {
     "type": "git",
     "url": "https://github.com/Stradivario/gapi.git"