@gapi/gcli 1.8.239 → 1.8.241

package/.agents/skills/cluster-targeting/SKILL.md

@@ -68,3 +68,26 @@ shared with or generated from gql-fission's copy.
 `jest.config.js` has no `moduleNameMapper` for the `~/` tsconfig path alias
 — new test files must use relative imports (e.g. `'../src/helpers'`), not
 `'~/helpers'`, or the test silently fails to resolve the module.
+
+## Managing a private cluster itself (scaling, topology, autoscale)
+
+The `cluster:*` commands that change or watch ONE cluster
+(`status`, `health`, `scale-events`, `cost`, `scale`,
+`scale:control-planes`, `multi-node`, `single-node`, `autoscale`,
+`load-balancer`) share `commands/cluster/helpers/cluster-change.ts`:
+`resolveClusterTarget` (`--cluster <id>` or `--clusterName <name>`,
+required), `parseIntOption`, and `runClusterChange` (mutate → print →
+`--wait` via `pollUntilReady`; ending in `error` exits non-zero). Their
+selections and types live in `commands/cluster/types.ts` (newer than the
+hand-kept `@introspection`).
+
+`cluster:apply` is the declarative path: the `cluster:` section of
+lambforge.yaml (`ClusterDesired` in `helpers/plan.ts`, also the type of
+`load-spec.ts`'s `cluster`). Keep `planClusterChanges` pure and ordered
+(create | topology → workers → control planes → load balancer →
+autoscale): each step is one background job and the cluster must be
+`ready` before the next. A new cluster setting = a key in `ClusterDesired`,
+a check in `validateDesired`, a step in the plan, a test in
+`test/cluster-apply.spec.ts`, and the README "Declarative clusters" block.
+The server merges partial autoscale input into the stored policy, so the
+plan sends only changed keys.

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,65 @@
 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:apply [options]                              Make a private cluster match the `cluster:` section of lambforge.yaml: creates it if missing, then applies topology, workers, control planes, load balancer and autoscaling
+  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'
+  cluster:status [options]                             Every cluster's status, agent, nodes, CPU/memory load, autoscaling and open issues (or one with --cluster)
+  cluster:health [options]                             The latest health report of a cluster's agent, with every node
+  cluster:scale-events [options]                       Manual and autoscaler scale history, newest first
+  cluster:cost [options]                               Month-to-date cost and the monthly estimate of the project's private clusters
+  cluster:scale [options]                              Set the number of worker nodes (1-10) of a multi-node cluster - billed per node-hour
+  cluster:scale:control-planes [options]               Set the number of control-plane nodes (1, 3 or 5)
+  cluster:autoscale [options]                          Change the worker autoscaling policy - only the flags you pass change
+  cluster:multi-node [options]                         Convert a single-node cluster to dedicated worker nodes (required for autoscaling)
+  cluster:single-node [options]                        Convert a multi-node cluster back to a single node (removes the worker nodes)
+  cluster:load-balancer [options]                      Add or remove the cluster's load balancer (billed per hour while enabled)
+  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]
@@ -522,6 +519,19 @@ Options:
   --wait                     Block until the cluster is ready (or errors)
   -h, --help                 display help for command
 
+--- Subcommand: cluster:apply ---
+Usage: gcli cluster:apply [options]
+
+Make a private cluster match the `cluster:` section of lambforge.yaml: creates it if missing, then applies topology, workers, control planes, load balancer and autoscaling
+
+Options:
+  -p, --project <project>
+  -spec, --spec <spec>     Spec file (default: lambforge.yaml / cluster.yaml)
+  --dry-run                Print the plan, change nothing
+  --yes                    Also apply steps that remove capacity or the load
+                           balancer IP
+  -h, --help               display help for command
+
 --- Subcommand: cluster:list ---
 Usage: gcli cluster:list [options]
 
@@ -553,6 +563,135 @@ Options:
   -o, --output <output>    Write to this file instead of stdout
   -h, --help               display help for command
 
+--- Subcommand: cluster:status ---
+Usage: gcli cluster:status [options]
+
+Every cluster's status, agent, nodes, CPU/memory load, autoscaling and open issues (or one with --cluster)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:health ---
+Usage: gcli cluster:health [options]
+
+The latest health report of a cluster's agent, with every node
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:scale-events ---
+Usage: gcli cluster:scale-events [options]
+
+Manual and autoscaler scale history, newest first
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --limit <limit>              How many events (default 20)
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:cost ---
+Usage: gcli cluster:cost [options]
+
+Month-to-date cost and the monthly estimate of the project's private clusters
+
+Options:
+  -p, --project <project>
+  -h, --help               display help for command
+
+--- Subcommand: cluster:scale ---
+Usage: gcli cluster:scale [options]
+
+Set the number of worker nodes (1-10) of a multi-node cluster - billed per node-hour
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --workers <workers>          Worker nodes, 1-10
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:scale:control-planes ---
+Usage: gcli cluster:scale:control-planes [options]
+
+Set the number of control-plane nodes (1, 3 or 5)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --count <count>              Control planes: 1, 3 or 5
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:autoscale ---
+Usage: gcli cluster:autoscale [options]
+
+Change the worker autoscaling policy - only the flags you pass change
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --enable                     Turn autoscaling on (multi-node clusters only)
+  --disable                    Turn autoscaling off
+  --min <min>                  Minimum workers (1-10)
+  --max <max>                  Maximum workers (1-10)
+  --cpuUp <percent>            Scale up at this CPU % (1-100)
+  --memUp <percent>            Scale up at this memory % (1-100)
+  --cpuDown <percent>          Scale down below this CPU % (1-100)
+  --memDown <percent>          Scale down below this memory % (1-100)
+  --samples <n>                Consecutive readings before acting (1-20)
+  --cooldown <minutes>         Minutes between scale actions (1-1440)
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:multi-node ---
+Usage: gcli cluster:multi-node [options]
+
+Convert a single-node cluster to dedicated worker nodes (required for autoscaling)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --workers <workers>          Worker nodes, 1-10
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:single-node ---
+Usage: gcli cluster:single-node [options]
+
+Convert a multi-node cluster back to a single node (removes the worker nodes)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:load-balancer ---
+Usage: gcli cluster:load-balancer [options]
+
+Add or remove the cluster's load balancer (billed per hour while enabled)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --enable                     Add the load balancer
+  --disable                    Remove the load balancer
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
 --- Subcommand: rabbitmq:create ---
 Usage: gcli rabbitmq:create [options]
 
@@ -646,6 +785,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

@@ -11,6 +11,7 @@ Whether you are deploying scalable serverless functions, managing cloud environm
 - [Managing Infrastructure](#managing-infrastructure)
 - [Serverless Functions (Lambdas)](#serverless-functions-lambdas)
 - [AI Integration (Model Context Protocol)](#ai-integration-model-context-protocol)
+  - [AI agent skill](#ai-agent-skill)
 - [Local AI Models (Ollama runner)](#local-ai-models-ollama-runner)
 - [Build System](#build-system)
 - [Command Reference](#command-reference)
@@ -24,7 +25,7 @@ You can install `gcli` using a pre-built binary or via NPM.
 For a standalone installation without Node.js dependencies:
 
 ```bash
-curl -L "https://github.com/Stradivario/gapi/releases/download/v1.8.198/gcli-linux" -o ~/.local/bin/gcli
+curl -L "https://github.com/Stradivario/gapi/releases/latest/download/gcli-linux" -o ~/.local/bin/gcli
 chmod +x ~/.local/bin/gcli
 ```
 
@@ -95,6 +96,10 @@ gcli environment:get --name 'staging'
 # (omit --clusterId to use the shared cluster - the default). Immutable
 # after creation.
 gcli environment:create --name 'staging' --clusterId '<clusterId>'
+
+# Resize it, or remove it
+gcli environment:update --name 'staging' --maxCpu 800 --maxMemory 1024
+gcli environment:delete --name 'staging'
 ```
 
 ### Private Clusters
@@ -119,17 +124,79 @@ gcli cluster:kubeconfig --cluster '<clusterId>' --output ./kubeconfig.yaml
 gcli cluster:teardown --cluster '<clusterId>' --wait
 ```
 
-`cluster.yaml`:
+Scale, reshape and watch a cluster (the same operations as the dashboard's
+cluster page). Changes run in the background; `--wait` blocks until the
+cluster is `ready` again. `--clusterName <name>` works instead of
+`--cluster <id>` everywhere.
+
+```bash
+# Health, load, autoscaling and open issues of every cluster (or one)
+gcli cluster:status [--cluster '<clusterId>']
+gcli cluster:health --cluster '<clusterId>'        # latest agent report, per node
+gcli cluster:scale-events --cluster '<clusterId>'  # manual + autoscaler history
+gcli cluster:cost                                  # month-to-date + monthly estimate
+
+# Worker nodes (1-10, billed per node-hour) and control planes (1, 3 or 5)
+gcli cluster:scale --cluster '<clusterId>' --workers 3 --wait
+gcli cluster:scale:control-planes --cluster '<clusterId>' --count 3 --wait
+
+# Topology: dedicated workers (needed for autoscaling) or back to one node
+gcli cluster:multi-node --cluster '<clusterId>' --workers 2 --wait
+gcli cluster:single-node --cluster '<clusterId>' --wait
+
+# Autoscaling - only the flags you pass change
+gcli cluster:autoscale --cluster '<clusterId>' --enable --min 2 --max 6
+gcli cluster:autoscale --cluster '<clusterId>' --cpuUp 75 --cpuDown 25 --cooldown 20
+gcli cluster:autoscale --cluster '<clusterId>' --disable
+
+# Load balancer (billed per hour while enabled)
+gcli cluster:load-balancer --cluster '<clusterId>' --enable --wait
+```
+
+#### Declarative clusters (`cluster:apply`)
+
+Write the cluster you want in the `cluster:` section of `lambforge.yaml`
+(or a standalone `cluster.yaml`) and let `cluster:apply` make it so: it
+creates the cluster when it doesn't exist, then applies topology, workers,
+control planes, the load balancer and autoscaling - one change at a time,
+waiting for the cluster to be ready between them. Keys you leave out are
+left as they are.
 
 ```yaml
-name: prod
-imageId: <hcloud-image-id>
-serverType: cpx22
-location: nbg1
-workers: 2
-singleNode: false
+cluster:
+  name: prod
+  # needed only to create it
+  imageId: <hcloud-image-id>
+  serverType: cpx22
+  location: nbg1
+  # desired state
+  singleNode: false        # true = one node runs everything (cheapest, dev/stage)
+  workers: 3               # 1-10; only the initial size while autoscale is enabled
+  controlPlanes: 1         # 1, 3 or 5
+  loadBalancer: true
+  autoscale:
+    enabled: true          # needs singleNode: false
+    minWorkers: 2
+    maxWorkers: 6
+    cpuScaleUpPercent: 70  # scale up above this (of allocatable)
+    memScaleUpPercent: 70
+    cpuScaleDownPercent: 30
+    memScaleDownPercent: 30
+    samplesToScale: 3      # consecutive readings before acting
+    cooldownMinutes: 15
 ```
 
+```bash
+gcli cluster:apply --dry-run     # print the plan, change nothing
+gcli cluster:apply               # apply it
+gcli cluster:apply --yes         # also steps that remove capacity or the LB IP
+gcli cluster:apply --spec cluster.yaml
+```
+
+Steps that remove capacity or release the load balancer's IP (going back to
+`singleNode: true`, `loadBalancer: false`) are skipped unless you pass
+`--yes`. Nodes and the load balancer are billed per started hour.
+
 ### RabbitMQ Brokers
 
 A project may have several RabbitMQ brokers, each optionally scoped to one of its private clusters.
@@ -285,15 +352,25 @@ options:
     external: []
 ```
 
-The same file can also carry `cluster:`, `rabbitmq:`, and `plugin:` sections, read by `cluster:create`, `rabbitmq:create`, and `plugin:install` respectively (each also accepts its own dedicated `--spec` file, e.g. `cluster.yaml`, if you'd rather keep them separate):
+The same file can also carry `cluster:`, `rabbitmq:`, `plugin:` and `triggers:` sections, read by `cluster:apply` / `cluster:create`, `rabbitmq:create`, `plugin:install` and `cron:create` respectively (each also accepts its own dedicated `--spec` file, e.g. `cluster.yaml`, if you'd rather keep them separate):
 
 ```yaml
-cluster:
+cluster:          # every key: see "Declarative clusters" above
   name: prod
   imageId: <hcloud-image-id>
   serverType: cpx22
   location: nbg1
   workers: 2
+  loadBalancer: false
+  autoscale:
+    enabled: true
+    minWorkers: 2
+    maxWorkers: 5
+
+triggers:
+  time:
+    triggerName: nightly
+    cron: '0 2 * * *'   # cron syntax or @every 5m / @daily
 
 rabbitmq:
   name: events-broker
@@ -361,7 +438,7 @@ gcli lambda:create --project <projectId> --spec ./lambforge.yaml
 `--mcp` and `--mcpGraph <name>` are also available as CLI flags; the array fields
 (`mcpOperations`, `mcpHeaders`, `mcpForwardHeaders`) are spec-only. A full annotated example lives in
 [`example/mcp/lambforge.yaml`](./example/mcp/lambforge.yaml). Client connects at
-`https://<host>/<projectId>/<route>/mcp`.
+`https://<host>/<projectId>/<route>` (with `route: mcp`: `https://<host>/<projectId>/mcp`).
 
 ### Conditional Configuration (Environment-Aware Specs)
 
@@ -638,10 +715,23 @@ gcli environment:update
 
 ### Function Lifecycle
 
+- **List**: `gcli lambda:list` (`--clusterName <name>` for one cluster's lambdas)
 - **Update**: `gcli lambda:update --name 'my-function' --file ./new-index.ts`
 - **Delete**: `gcli lambda:delete --name 'my-function'`
 - **Get Details**: `gcli lambda:get --name 'my-function'`
 
+### Schedules (cron)
+
+One time trigger per lambda. The platform calls the lambda's root with a
+GET and an `X-Fission-Timer-Name` header.
+
+```bash
+gcli cron:create --lambdaName 'my-function' --triggerName nightly --cron '0 2 * * *'
+gcli cron:create                 # reads triggers.time (and function.name) from lambforge.yaml
+gcli cron:list
+gcli cron:delete --lambdaName 'my-function'
+```
+
 ### Monitoring & Testing
 
 Debug your functions directly from the terminal.
@@ -715,6 +805,33 @@ To use this with Claude Desktop or other MCP-compatible tools, add the following
 }
 ```
 
+### AI agent skill
+
+Give a coding agent (Claude Code and other agents that read skills) the
+whole platform. Paste this into the agent:
+
+```text
+Install the Lambforge skill from https://lambforge.com/skills/platform.md and follow its setup.
+```
+
+Or by hand for Claude Code:
+
+```bash
+mkdir -p ~/.claude/skills/lambforge && cd ~/.claude/skills/lambforge
+for f in $(curl -fsSL https://lambforge.com/skills/files.txt); do
+  curl -fsSLO "https://lambforge.com/skills/$f"
+done
+cp platform.md SKILL.md
+claude mcp add --scope user lambforge -- gcli mcp:start
+```
+
+`platform.md` covers setup (install gcli, the login command you run from
+Profile -> CLI - the agent never handles your token, `gcli mcp:start`) and
+the rules, and indexes topic files the agent reads on demand: gcli, MCP
+tools, deploy, REST code and testing, GraphQL and federation, websites,
+MCP servers, secrets, cron and queues, clusters and plugins, operations and
+costs, memory and plans. Source: gql-fission `src/skills/`.
+
 ## Local AI Models (Ollama runner)
 
 Use models running on your own machine in the Lambforge chat - including
@@ -744,6 +861,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.