@gapi/gcli 1.8.237 → 1.8.239

package/README-CLI.md

@@ -14,6 +14,7 @@ Commands:
   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
@@ -29,6 +30,38 @@ Commands:
   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
 
 --- Subcommand: login ---
@@ -50,8 +83,16 @@ Usage: gcli lambda:list [options]
 List of all lambdas for project
 
 Options:
-  -p, --project <project>  Specify custom token generated from the website
-  -h, --help               display help for command
+  -p, --project <project>           Specify custom token generated from the
+                                    website
+  -cid, --clusterId <clusterId>     Only lambdas whose environment targets this
+                                    cluster (empty string for
+                                    shared-cluster-only; omit for all)
+  -cn, --clusterName <clusterName>  Same as --clusterId but by the cluster's
+                                    human-readable name (see cluster:list) -
+                                    resolved to its id before the request;
+                                    --clusterId wins if both are given
+  -h, --help                        display help for command
 
 --- Subcommand: lambda:get ---
 Usage: gcli lambda:get [options]
@@ -59,11 +100,17 @@ Usage: gcli lambda:get [options]
 Get lambda by id
 
 Options:
-  -l, --lambda <lambda>    get by lambda id
-  -n, --name <name>        get by lambda name
-  -p, --project <project>  get by lambda name
-  -p, --spec <spec>        get by lambda name
-  -h, --help               display help for command
+  -l, --lambda <lambda>             get by lambda id
+  -n, --name <name>                 get by lambda name
+  -p, --project <project>           get by lambda name
+  -p, --spec <spec>                 get by lambda name
+  -cid, --clusterId <clusterId>     Disambiguates which lambda to fetch when
+                                    --name matches more than one across
+                                    different clusters
+  -cn, --clusterName <clusterName>  Same as --clusterId but by the cluster's
+                                    human-readable name (see cluster:list);
+                                    --clusterId wins if both are given
+  -h, --help                        display help for command
 
 --- Subcommand: lambda:create ---
 Usage: gcli lambda:create [options]
@@ -72,6 +119,8 @@ Options:
   --name <name>                                    Function name
   --project <project>                              Project in which this lambda is defined
   --env <env>                                      Environment name for function can be NODEJS
+  --clusterId <clusterId>                          Disambiguation hint: which of the project's clusters --env lives on (see cluster:list); omit for the shared cluster. Only needed once a project has private clusters and a duplicate-named environment across them.
+  --clusterName <clusterName>                      Same as --clusterId but by the cluster's human-readable name (see cluster:list); --clusterId wins if both are given. Can also be set as `clusterName` in the lambforge.yaml spec's function block.
   --method <method...>                             HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method
   --spec <spec>                                    Spec file yml or json path
   --packageJson <packageJson>                      Define packageJson in string format
@@ -79,10 +128,18 @@ Options:
   --buildBashScript <buildBashScript>              Package build command for builder to run with
   --script <script>                                Package build script path
   --params <params>                                Array from strings which defines route params
+  --configs <configs...>                           List of kubernetes config names
+  --secrets <secrets...>                           List of kubernetes secret names
+  --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
   --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
   --route <route>                                  Lambda route in which will be accessible
   --code <code>                                    URL or local path for single file source code
   --file <file>                                    Main lambda file
+  --customUploadFileId <customUploadFileId>        Id of a pre-uploaded archive to use as the lambda source
+  --federation                                     Provision this lambda as a GraphQL Federation gateway instead of a regular function
+  --subgraphs <subgraphs...>                       Lambda names (within the project) to expose as subgraphs of the federation gateway
+  --mcp                                            Provision this lambda as an Apollo MCP Server in front of a federation graph
+  --mcpGraph <mcpGraph>                            Federation gateway lambda name the MCP server connects to (operations/headers via spec yaml)
   --executorType <executorType>                    Executor type for execution; one of 'poolmgr', 'newdeploy'
   --maxCpu <maxCpu>                                Maximum CPU to be assigned to pod (In millicore, minimum 1)
   --minCpu <minCpu>                                Minimum CPU to be assigned to pod (In millicore, minimum 1)
@@ -104,6 +161,8 @@ Options:
   --name <name>                                    Function name
   --project <project>                              Project in which this lambda is defined
   --env <env>                                      Environment name for function can be NODEJS
+  --clusterId <clusterId>                          Disambiguation hint: which of the project's clusters --env lives on (see cluster:list); omit for the shared cluster. Only needed once a project has private clusters and a duplicate-named environment across them.
+  --clusterName <clusterName>                      Same as --clusterId but by the cluster's human-readable name (see cluster:list); --clusterId wins if both are given. Can also be set as `clusterName` in the lambforge.yaml spec's function block.
   --method <method...>                             HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method
   --spec <spec>                                    Spec file yml or json path
   --packageJson <packageJson>                      Define packageJson in string format
@@ -111,10 +170,18 @@ Options:
   --buildBashScript <buildBashScript>              Package build command for builder to run with
   --script <script>                                Package build script path
   --params <params>                                Array from strings which defines route params
+  --configs <configs...>                           List of kubernetes config names
+  --secrets <secrets...>                           List of kubernetes secret names
+  --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
   --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
   --route <route>                                  Lambda route in which will be accessible
   --code <code>                                    URL or local path for single file source code
   --file <file>                                    Main lambda file
+  --customUploadFileId <customUploadFileId>        Id of a pre-uploaded archive to use as the lambda source
+  --federation                                     Provision this lambda as a GraphQL Federation gateway instead of a regular function
+  --subgraphs <subgraphs...>                       Lambda names (within the project) to expose as subgraphs of the federation gateway
+  --mcp                                            Provision this lambda as an Apollo MCP Server in front of a federation graph
+  --mcpGraph <mcpGraph>                            Federation gateway lambda name the MCP server connects to (operations/headers via spec yaml)
   --executorType <executorType>                    Executor type for execution; one of 'poolmgr', 'newdeploy'
   --maxCpu <maxCpu>                                Maximum CPU to be assigned to pod (In millicore, minimum 1)
   --minCpu <minCpu>                                Minimum CPU to be assigned to pod (In millicore, minimum 1)
@@ -135,10 +202,19 @@ Usage: gcli lambda:delete [options]
 Get lambda by id
 
 Options:
-  -n, --name <name>        get by lambda name
-  -p, --project <project>  get by lambda name
-  -s, --spec <spec>        get by lambda name
-  -h, --help               display help for command
+  -n, --name <name>                 get by lambda name
+  -p, --project <project>           get by lambda name
+  -s, --spec <spec>                 get by lambda name
+  -e, --env <env>                   disambiguates which lambda to delete when
+                                    --name matches more than one across
+                                    environments/clusters
+  -cid, --clusterId <clusterId>     disambiguates which lambda to delete when
+                                    --name matches more than one across
+                                    different clusters
+  -cn, --clusterName <clusterName>  Same as --clusterId but by the cluster's
+                                    human-readable name (see cluster:list);
+                                    --clusterId wins if both are given
+  -h, --help                        display help for command
 
 --- Subcommand: lambda:log ---
 Usage: gcli lambda:log [options]
@@ -146,11 +222,17 @@ Usage: gcli lambda:log [options]
 Get lambda log
 
 Options:
-  -l, --lambda <lambda>    get by lambda id
-  -n, --name <name>        get by lambda name
-  -p, --project <project>  get by lambda name
-  -s, --spec <spec>        get by lambda name
-  -h, --help               display help for command
+  -l, --lambda <lambda>             get by lambda id
+  -n, --name <name>                 get by lambda name
+  -p, --project <project>           get by lambda name
+  -s, --spec <spec>                 get by lambda name
+  -cid, --clusterId <clusterId>     disambiguates which lambda to fetch logs
+                                    for when --name matches more than one
+                                    across different clusters
+  -cn, --clusterName <clusterName>  Same as --clusterId but by the cluster's
+                                    human-readable name (see cluster:list);
+                                    --clusterId wins if both are given
+  -h, --help                        display help for command
 
 --- Subcommand: lambda:build:log ---
 Usage: gcli lambda:build:log [options]
@@ -158,11 +240,17 @@ Usage: gcli lambda:build:log [options]
 Get build log
 
 Options:
-  -l, --lambda <lambda>    get by lambda id
-  -n, --name <name>        get by lambda name
-  -p, --project <project>  get by lambda project
-  -s, --spec <spec>        use configuration
-  -h, --help               display help for command
+  -l, --lambda <lambda>             get by lambda id
+  -n, --name <name>                 get by lambda name
+  -p, --project <project>           get by lambda project
+  -s, --spec <spec>                 use configuration
+  -cid, --clusterId <clusterId>     disambiguates which lambda to fetch build
+                                    logs for when --name matches more than one
+                                    across different clusters
+  -cn, --clusterName <clusterName>  Same as --clusterId but by the cluster's
+                                    human-readable name (see cluster:list);
+                                    --clusterId wins if both are given
+  -h, --help                        display help for command
 
 --- Subcommand: lambda:test ---
 Usage: gcli lambda:test [options]
@@ -177,8 +265,52 @@ Options:
   -qp, --queryParams <queryParams>  Adds query params to request
   -pp, --pathParams <pathParams>    Adds query params to request
   -b, --body <body>                 Add body to request
+  -m, --method <method>             HTTP Methods: GET,POST,PUT,DELETE,HEAD. To
+                                    mention single method
   -h, --help                        display help for command
 
+--- Subcommand: lambda:package ---
+Usage: gcli lambda:package [options]
+
+Options:
+  --name <name>                                    Function name
+  --project <project>                              Project in which this lambda is defined
+  --env <env>                                      Environment name for function can be NODEJS
+  --clusterId <clusterId>                          Disambiguation hint: which of the project's clusters --env lives on (see cluster:list); omit for the shared cluster. Only needed once a project has private clusters and a duplicate-named environment across them.
+  --clusterName <clusterName>                      Same as --clusterId but by the cluster's human-readable name (see cluster:list); --clusterId wins if both are given. Can also be set as `clusterName` in the lambforge.yaml spec's function block.
+  --method <method...>                             HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method
+  --spec <spec>                                    Spec file yml or json path
+  --packageJson <packageJson>                      Define packageJson in string format
+  --package <package>                              Path to package.json
+  --buildBashScript <buildBashScript>              Package build command for builder to run with
+  --script <script>                                Package build script path
+  --params <params>                                Array from strings which defines route params
+  --configs <configs...>                           List of kubernetes config names
+  --secrets <secrets...>                           List of kubernetes secret names
+  --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
+  --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
+  --route <route>                                  Lambda route in which will be accessible
+  --code <code>                                    URL or local path for single file source code
+  --file <file>                                    Main lambda file
+  --customUploadFileId <customUploadFileId>        Id of a pre-uploaded archive to use as the lambda source
+  --federation                                     Provision this lambda as a GraphQL Federation gateway instead of a regular function
+  --subgraphs <subgraphs...>                       Lambda names (within the project) to expose as subgraphs of the federation gateway
+  --mcp                                            Provision this lambda as an Apollo MCP Server in front of a federation graph
+  --mcpGraph <mcpGraph>                            Federation gateway lambda name the MCP server connects to (operations/headers via spec yaml)
+  --executorType <executorType>                    Executor type for execution; one of 'poolmgr', 'newdeploy'
+  --maxCpu <maxCpu>                                Maximum CPU to be assigned to pod (In millicore, minimum 1)
+  --minCpu <minCpu>                                Minimum CPU to be assigned to pod (In millicore, minimum 1)
+  --maxMemory <maxMemory>                          Maximum memory to be assigned to pod (In megabyte)
+  --minMemory <minMemory>                          Minimum memory to be assigned to pod (In megabyte)
+  --minScale <minScale>                            Minimum number of pods (Uses resource inputs to configure HPA)
+  --maxScale <maxScale>                            Maximum number of pods (Uses resource inputs to configure HPA)
+  --targetCpu <targetCpu>                          Target average CPU usage percentage across pods for scaling
+  --idleTimeout <idleTimeout>                      The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling
+  --concurrency <concurrency>                      Maximum number of pods specialized concurrently to serve requests
+  --functionTimeout <functionTimeout>              Maximum time for a request to wait for the response from the function
+  --specializationTimeout <specializationTimeout>  Timeout for executor to wait for function pod creation
+  -h, --help                                       display help for command
+
 --- Subcommand: project:list ---
 Usage: gcli project:list [options]
 
@@ -245,6 +377,14 @@ Options:
   -spec, --spec <spec>
   -r, --region <region>                Default region is eu-central 'DEFAULT' |
                                        'EU_BALKANS' | 'EU_CENTRAL'
+  -cid, --clusterId <clusterId>        Private cluster this environment should
+                                       run on (see cluster:list); omit for the
+                                       shared cluster. Immutable after
+                                       creation.
+  -cn, --clusterName <clusterName>     Same as --clusterId but by the cluster's
+                                       human-readable name; --clusterId wins if
+                                       both are given. Can also be set as
+                                       `clusterName` in env.yaml.
   -h, --help                           display help for command
 
 --- Subcommand: environment:update ---
@@ -265,6 +405,14 @@ Options:
   -spec, --spec <spec>
   -r, --region <region>                Default region is eu-central 'DEFAULT' |
                                        'EU_BALKANS' | 'EU_CENTRAL'
+  -cid, --clusterId <clusterId>        Disambiguates which environment to
+                                       update when --name matches more than one
+                                       across different clusters (clusterId
+                                       itself is immutable and never changed by
+                                       this command).
+  -cn, --clusterName <clusterName>     Same as --clusterId but by the cluster's
+                                       human-readable name; --clusterId wins if
+                                       both are given
   -h, --help                           display help for command
 
 --- Subcommand: environment:delete ---
@@ -277,7 +425,13 @@ Options:
   -n, --name <name>
   -f, --force
   -spec, --spec <spec>
-  -h, --help               display help for command
+  -cid, --clusterId <clusterId>     Disambiguates which environment to delete
+                                    when --name matches more than one across
+                                    different clusters
+  -cn, --clusterName <clusterName>  Same as --clusterId but by the cluster's
+                                    human-readable name; --clusterId wins if
+                                    both are given
+  -h, --help                        display help for command
 
 --- Subcommand: environment:get ---
 Usage: gcli environment:get [options]
@@ -287,7 +441,13 @@ Get environment for project
 Options:
   -p, --project <project>
   -n, --name <name>
-  -h, --help               display help for command
+  -cid, --clusterId <clusterId>     Disambiguates which environment to fetch
+                                    when --name matches more than one across
+                                    different clusters
+  -cn, --clusterName <clusterName>  Same as --clusterId but by the cluster's
+                                    human-readable name; --clusterId wins if
+                                    both are given
+  -h, --help                        display help for command
 
 --- Subcommand: mcp:start ---
 Usage: gcli mcp:start [options]
@@ -310,5 +470,207 @@ Options:
   -p, --platform <char>         Platform  (default: "node")
   -t, --target <char>           Target  (default: "node14.4")
   -o, --outfile <char>          Outfile name
+  -i, --ignore <ignore...>      Ignore folders from triggering restarts
   -e, --external <external...>  External libraries
   -h, --help                    display help for command
+
+--- Subcommand: cron:create ---
+Usage: gcli cron:create [options]
+
+Create cron
+
+Options:
+  -p, --project <project>
+  -l, --lambdaName <lambdaName>
+  -t, --triggerName <triggerName>
+  -c, --cron <cron>
+  -h, --help                       display help for command
+
+--- Subcommand: cron:delete ---
+Usage: gcli cron:delete [options]
+
+Delete cron
+
+Options:
+  -p, --project <project>
+  -l, --lambdaName <lambdaName>
+  -h, --help                     display help for command
+
+--- Subcommand: cron:list ---
+Usage: gcli cron:list [options]
+
+List of all cron jobs for project
+
+Options:
+  -p, --project <project>
+  -h, --help               display help for command
+
+--- Subcommand: cluster:create ---
+Usage: gcli cluster:create [options]
+
+Provision a private Talos cluster for a project (runs in the background - takes several minutes; use --wait to block)
+
+Options:
+  -p, --project <project>
+  -spec, --spec <spec>
+  -n, --name <name>
+  --imageId <imageId>        hcloud Talos snapshot id
+  --serverType <serverType>
+  -l, --location <location>
+  --workers <workers>        Worker count (ignored when --singleNode)
+  --singleNode               Control plane carries the workload too
+  --wait                     Block until the cluster is ready (or errors)
+  -h, --help                 display help for command
+
+--- Subcommand: cluster:list ---
+Usage: gcli cluster:list [options]
+
+List every private cluster this project has (it may have several - dev/stage/prod, ...)
+
+Options:
+  -p, --project <project>
+  -h, --help               display help for command
+
+--- Subcommand: cluster:teardown ---
+Usage: gcli cluster:teardown [options]
+
+Tear down one of a project's clusters (runs in the background - use --wait to block)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>  Cluster id (see cluster:list)
+  --wait                   Block until the cluster is gone (or errors)
+  -h, --help               display help for command
+
+--- Subcommand: cluster:kubeconfig ---
+Usage: gcli cluster:kubeconfig [options]
+
+Print (or save) a cluster's raw kubeconfig YAML - only available once it's 'ready'
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>  Cluster id (see cluster:list)
+  -o, --output <output>    Write to this file instead of stdout
+  -h, --help               display help for command
+
+--- Subcommand: rabbitmq:create ---
+Usage: gcli rabbitmq:create [options]
+
+Provision a RabbitMQ broker for a project (a project may have several)
+
+Options:
+  -p, --project <project>
+  -spec, --spec <spec>
+  -n, --name <name>
+  -d, --description <description>
+  -u, --user <user>
+  --password <password>
+  -r, --region <region>            'DEFAULT' | 'EU_BALKANS' | 'EU_CENTRAL'
+  -c, --cluster <cluster>          Which private cluster to provision this
+                                   broker on; omit for the shared cluster
+  -h, --help                       display help for command
+
+--- Subcommand: rabbitmq:list ---
+Usage: gcli rabbitmq:list [options]
+
+List every RabbitMQ broker for a project
+
+Options:
+  -p, --project <project>
+  -h, --help               display help for command
+
+--- Subcommand: rabbitmq:delete ---
+Usage: gcli rabbitmq:delete [options]
+
+Delete a RabbitMQ broker
+
+Options:
+  -p, --project <project>
+  --id <id>                Broker id (see rabbitmq:list)
+  -h, --help               display help for command
+
+--- Subcommand: plugin:list ---
+Usage: gcli plugin:list [options]
+
+List every plugin available in the marketplace catalog
+
+Options:
+  -h, --help  display help for command
+
+--- Subcommand: plugin:installed ---
+Usage: gcli plugin:installed [options]
+
+List plugins installed for a project (may include the same plugin on several clusters)
+
+Options:
+  -p, --project <project>
+  -h, --help               display help for command
+
+--- Subcommand: plugin:install ---
+Usage: gcli plugin:install [options]
+
+Install a marketplace plugin for a project
+
+Options:
+  -p, --project <project>
+  -spec, --spec <spec>
+  -n, --name <name>        Plugin name, e.g. redis-plugin
+  -c, --cluster <cluster>  Which private cluster to install into; omit for the
+                           shared cluster
+  -h, --help               display help for command
+
+--- Subcommand: plugin:uninstall ---
+Usage: gcli plugin:uninstall [options]
+
+Uninstall a plugin from a project (--cluster picks which installation, if it's on several)
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Plugin name
+  -c, --cluster <cluster>
+  -h, --help               display help for command
+
+--- Subcommand: runner:start ---
+Usage: gcli 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)
+
+Options:
+  -n, --name <name>    Runner name shown in the chat model picker (default:
+                       hostname)
+  -t, --token <token>  Runner token from Profile -> Local AI runners (instead
+                       of `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
+  -h, --help           display help for command
+
+--- Subcommand: runner:list ---
+Usage: gcli runner:list [options]
+
+List your local AI runners and the models they serve
+
+Options:
+  -h, --help  display help for command
+
+--- Subcommand: runner:models ---
+Usage: gcli runner:models [options]
+
+Choose which of a runner's models appear in the chat model picker (no flags: list them)
+
+Options:
+  --id <id>        Runner id (default: the runner saved on this machine)
+  --show <models>  Comma-separated models to show (hides the rest)
+  --all            Show every model again
+  --none           Hide all models of this runner from the chat
+  -h, --help       display help for command
+
+--- Subcommand: runner:delete ---
+Usage: gcli runner:delete [options]
+
+Delete a local AI runner and revoke its token
+
+Options:
+  --id <id>   Runner id (default: the runner saved on this machine)
+  -h, --help  display help for command

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)
+- [Local AI Models (Ollama runner)](#local-ai-models-ollama-runner)
 - [Build System](#build-system)
 - [Command Reference](#command-reference)
 
@@ -714,6 +715,45 @@ To use this with Claude Desktop or other MCP-compatible tools, add the following
 }
 ```
 
+## Local AI Models (Ollama runner)
+
+Use models running on your own machine in the Lambforge chat - including
+agent mode, spawned workers and MCP tools - exactly like the hosted models.
+`gcli runner:start` connects your local [Ollama](https://ollama.com) to
+Lambforge over an **outbound** WebSocket: it works behind NAT, nothing is
+port-forwarded, and Ollama is never exposed to the internet. The platform
+can only send chat completions to it (`POST /v1/chat/completions`).
+
+```bash
+# 1. Ollama with a model, and a context window big enough for agent mode
+ollama pull qwen3:32b
+OLLAMA_CONTEXT_LENGTH=32768 ollama serve
+
+# 2. Logged-in gcli registers this machine as a runner and connects
+gcli login
+gcli runner:start                      # --name my-gpu-box (default: hostname)
+```
+
+Your models now appear in the chat model picker with a **Local** badge
+(greyed out as **Offline** when the runner isn't running). The runner keeps
+running until Ctrl+C and reconnects on its own.
+
+| Command | Description |
+|---|---|
+| `gcli runner:start` | Connect this machine. First run registers a runner and saves it to `~/.graphql-server/runner.json`. Options: `--name`, `--token <runner token>` (headless machines without `gcli login` - create the token in Profile -> Local AI runners), `--ollama <url>` (default `$OLLAMA_HOST` or `http://127.0.0.1:11434`), `--wsUrl` (override the derived endpoint), `--reset` (forget the saved runner, register a new one) |
+| `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) |
+
+Notes:
+
+- Models are only offered if Ollama reports them as chat-capable; a model
+  without the `tools` capability is used without platform tools.
+- Local models don't count against your plan's AI token quota.
+- Requires Node.js >= 22.
+- Use Profile -> Local AI runners in the web app to see runners, choose
+  models with checkboxes, and create tokens.
+
 ## Build System & Local Development
 
 `gcli` includes a high-performance bundler powered by **esbuild**.

package/docs/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog (archive)
+
+Compacted changelog fragments, newest first. **Never edit this file by
+hand** - new entries go in `docs/changelog.d/` (`node scripts/changelog.mjs new`);
+only `node scripts/changelog.mjs compact` writes here. See
+`docs/changelog.d/README.md`.
+
+---

package/docs/changelog.d/2026-10-11-local-ai-runners-gcli-runner-commands-bridge-ollama-to-the-chat.md

@@ -0,0 +1,25 @@
+## 2026-10-11 - local-ai-runners: gcli runner commands bridge a local Ollama to the chat
+
+**Feature:** local-ai-runners · **Type:** feat
+
+- `gcli runner:start` registers the machine with the `gcli login` session
+  (or uses `--token`), saves `~/.graphql-server/runner.json` (0600) and keeps
+  an outbound subscriptions-transport-ws connection (`RunnerConnection`):
+  `subscribeToRunnerRequests`, `runnerHeartbeat` every 30s (models from
+  Ollama `/api/tags` + `/api/show`, non-chat models dropped),
+  `runnerRespond` with `FrameSender` (seq, 50ms batches, chunks merged to
+  32KB), `ping` while Ollama queues, cancel -> abort, reconnect 1s -> 30s,
+  refused token -> exit 1 with a `--reset` hint.
+- `runner:list`, `runner:delete`; `GraphqlClienAPI` runner calls.
+- Only `POST /v1/chat/completions` is proxied (`ALLOWED_REQUESTS`).
+- Endpoint derived from the login URL (dev :9004 -> ws :9000).
+- Backend half: graphql-server `local-runner` module; UI in gql-fission.
+- **Test:** `npx jest test/runner.spec.ts --coverage=false` (fake server
+  socket + fake streaming Ollama: auth, heartbeat models, ordered streaming
+  with split UTF-8, allow-list, cancel, ping, refused token, URL rules).
+- **Debug:** runner log `->` / `<-` / `x` lines, `Heartbeat failed`,
+  `Cannot reach Ollama`, `Disconnected ... reconnecting`; backend side in
+  `graphql-server/docs/features/local-ai-runners.md#how-to-debug`.
+- **Verification:** gcli suite green; `tsc` + eslint clean; live: runner
+  registered against the dev gateway, connected, 31 chat models reported,
+  reconnect reused the saved runner, chat answered by `qwen3.8:27b`.

package/docs/changelog.d/2026-10-11-local-ai-runners-gcli-runner-models-chooses-the-models-shown-in-chat.md

@@ -0,0 +1,12 @@
+## 2026-10-11 - local-ai-runners: gcli runner:models chooses the models shown in chat
+
+**Feature:** local-ai-runners · **Type:** feat
+
+- `gcli runner:models [--id] [--show a,b | --all | --none]` -> 
+  `setLocalRunnerModels`; no flag lists models with a `shown` column. Warns
+  about names the runner doesn't report (kept anyway).
+- **Test:** `npx jest test/runner.spec.ts --coverage=false`
+  (`parseSelection` flag mapping and conflicts).
+- **Debug:** "Runner ... not found" = wrong `--id` or not your runner; an
+  error naming `setLocalRunnerModels` = backend older than this feature.
+- **Verification:** gcli suite 27/27; `tsc` + eslint clean.

package/docs/changelog.d/2026-10-11-local-ai-runners-runner-reports-each-model-s-loaded-context-window.md

@@ -0,0 +1,22 @@
+## 2026-10-11 - local-ai-runners: runner reports each model's loaded context window
+
+**Feature:** local-ai-runners · **Type:** fix
+
+- Heartbeat models now carry `runtimeContextLength` from Ollama `/api/ps`
+  (the window a loaded model really runs with, e.g. 32,768 for qwen3.8:27b
+  whose max is 262,144). The backend fits every request to it - fixes
+  `500 no user query found in messages` in long chats, caused by Ollama
+  silently truncating oversized prompts (backend half: graphql-server
+  `fix(local-ai-runners): fit requests to the model's real context window`).
+- Models `/api/show` answers 404/410 for (a retired `glm-5.1:cloud` was
+  still listed by `/api/tags`) are no longer offered, and the answer is
+  cached instead of re-asked every heartbeat.
+- **Test:** `npx jest test/runner.spec.ts --coverage=false` (fake Ollama
+  answers `/api/ps` with a loaded model at 65536 and 410 for a retired
+  cloud model; the heartbeat must carry the window and omit that model).
+- **Debug:** `ollama ps` shows the live window the runner reports;
+  `db["local-runners"]` -> `models[].runtimeContextLength` on the backend.
+  An unloaded model reports nothing - the backend keeps its last value.
+- **Verification:** gcli 27/27, tsc + eslint clean; live: runner reported
+  30 models (retired cloud model gone) and the dev backend stored
+  qwen3.8:27b runtimeContextLength 32768.