copilotkit 4.22.0 → 4.23.0

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 (92) hide show
  1. package/README.md +390 -17
  2. package/cli-build-info.json +8 -8
  3. package/index.js +52224 -34474
  4. package/onboarding/index.json +83 -9
  5. package/onboarding/prompts/authenticate/start.md +44 -34
  6. package/onboarding/prompts/conversion/plan.md +3 -3
  7. package/onboarding/prompts/credentials/finalize-plan.md +12 -7
  8. package/onboarding/prompts/credentials/plan.md +23 -23
  9. package/onboarding/prompts/credentials/settle-credentials.md +10 -7
  10. package/onboarding/prompts/credentials/write-plan.md +17 -7
  11. package/onboarding/prompts/deployment/choose-local.md +46 -0
  12. package/onboarding/prompts/deployment/local-evaluation.md +71 -0
  13. package/onboarding/prompts/fallback/best-effort.md +8 -8
  14. package/onboarding/prompts/feature/a2ui/implement.md +6 -6
  15. package/onboarding/prompts/feature/a2ui/plan.md +72 -0
  16. package/onboarding/prompts/feature/a2ui/proof.md +5 -5
  17. package/onboarding/prompts/feature/a2ui/start.md +11 -32
  18. package/onboarding/prompts/feature/channels/implement.md +23 -16
  19. package/onboarding/prompts/feature/channels/plan.md +85 -0
  20. package/onboarding/prompts/feature/channels/proof.md +5 -5
  21. package/onboarding/prompts/feature/channels/start.md +14 -41
  22. package/onboarding/prompts/feature/chat-suggestions/implement.md +6 -6
  23. package/onboarding/prompts/feature/chat-suggestions/plan.md +71 -0
  24. package/onboarding/prompts/feature/chat-suggestions/proof.md +5 -5
  25. package/onboarding/prompts/feature/chat-suggestions/start.md +11 -30
  26. package/onboarding/prompts/feature/complete.md +2 -2
  27. package/onboarding/prompts/feature/learning/implement.md +13 -13
  28. package/onboarding/prompts/feature/learning/plan.md +82 -0
  29. package/onboarding/prompts/feature/learning/proof.md +6 -6
  30. package/onboarding/prompts/feature/learning/start.md +11 -40
  31. package/onboarding/prompts/feature/open-generative-ui/implement.md +6 -6
  32. package/onboarding/prompts/feature/open-generative-ui/plan.md +70 -0
  33. package/onboarding/prompts/feature/open-generative-ui/proof.md +5 -5
  34. package/onboarding/prompts/feature/open-generative-ui/start.md +11 -30
  35. package/onboarding/prompts/feature/realtime-sync/implement.md +7 -7
  36. package/onboarding/prompts/feature/realtime-sync/plan.md +75 -0
  37. package/onboarding/prompts/feature/realtime-sync/proof.md +5 -5
  38. package/onboarding/prompts/feature/realtime-sync/start.md +10 -33
  39. package/onboarding/prompts/feature/rich-threads/implement.md +8 -8
  40. package/onboarding/prompts/feature/rich-threads/plan.md +77 -0
  41. package/onboarding/prompts/feature/rich-threads/proof.md +5 -5
  42. package/onboarding/prompts/feature/rich-threads/start.md +10 -35
  43. package/onboarding/prompts/feature/stop.md +3 -3
  44. package/onboarding/prompts/feature/voice/implement.md +6 -6
  45. package/onboarding/prompts/feature/voice/plan.md +74 -0
  46. package/onboarding/prompts/feature/voice/proof.md +5 -5
  47. package/onboarding/prompts/feature/voice/start.md +11 -29
  48. package/onboarding/prompts/framework/ag2.md +2 -2
  49. package/onboarding/prompts/framework/agno.md +2 -2
  50. package/onboarding/prompts/framework/built-in.md +2 -2
  51. package/onboarding/prompts/framework/claude-sdk-python.md +2 -2
  52. package/onboarding/prompts/framework/claude-sdk-typescript.md +2 -2
  53. package/onboarding/prompts/framework/crewai-flows.md +2 -2
  54. package/onboarding/prompts/framework/custom-ag-ui.md +5 -2
  55. package/onboarding/prompts/framework/deep-agents.md +2 -2
  56. package/onboarding/prompts/framework/google-adk.md +2 -2
  57. package/onboarding/prompts/framework/langgraph-fastapi.md +2 -2
  58. package/onboarding/prompts/framework/langgraph-python.md +2 -2
  59. package/onboarding/prompts/framework/langgraph-typescript.md +2 -2
  60. package/onboarding/prompts/framework/llamaindex.md +2 -2
  61. package/onboarding/prompts/framework/mastra.md +2 -2
  62. package/onboarding/prompts/framework/ms-agent-dotnet.md +3 -3
  63. package/onboarding/prompts/framework/ms-agent-harness-dotnet.md +3 -3
  64. package/onboarding/prompts/framework/ms-agent-python.md +2 -2
  65. package/onboarding/prompts/framework/pydantic-ai.md +2 -2
  66. package/onboarding/prompts/framework/strands-python.md +2 -2
  67. package/onboarding/prompts/framework/strands-typescript.md +2 -2
  68. package/onboarding/prompts/frontend/angular.md +3 -3
  69. package/onboarding/prompts/frontend/nextjs.md +3 -3
  70. package/onboarding/prompts/frontend/plan.md +7 -7
  71. package/onboarding/prompts/frontend/react-native.md +2 -2
  72. package/onboarding/prompts/frontend/react-spa.md +2 -2
  73. package/onboarding/prompts/frontend/vue.md +2 -2
  74. package/onboarding/prompts/implementation/build-and-validate.md +14 -13
  75. package/onboarding/prompts/proof/complete.md +3 -3
  76. package/onboarding/prompts/proof/oss-baseline.md +5 -5
  77. package/onboarding/prompts/proof/round-trip.md +16 -11
  78. package/onboarding/prompts/research/gather.md +9 -8
  79. package/onboarding/prompts/research/merge.md +6 -3
  80. package/onboarding/prompts/research/preflight.md +2 -2
  81. package/onboarding/prompts/research/route.md +22 -14
  82. package/onboarding/prompts/starter/clone.md +5 -5
  83. package/onboarding/prompts/stopped/run-failed.md +2 -2
  84. package/onboarding/prompts/subagent/create-plan.md +9 -2
  85. package/onboarding/prompts/subagent/implement-and-validate.md +34 -2
  86. package/onboarding/prompts/subagent/inspect-repository.md +1 -1
  87. package/onboarding/prompts/subagent/prove-oss-baseline.md +1 -1
  88. package/onboarding/prompts/subagent/prove-round-trip.md +39 -21
  89. package/onboarding/prompts/unsupported/no-validated-path.md +2 -2
  90. package/package.json +4 -1
  91. package/release/release-tool.js +167 -18
  92. package/services/local-auth-worker.js +21465 -0
package/README.md CHANGED
@@ -250,9 +250,9 @@ copilotkit login --json
250
250
  ```
251
251
 
252
252
  The command prints JSON lines for the sign-in URL, an instruction for the
253
- machine reader, and the final result. Every JSON login URL carries the
254
- `agent_onboarding` display hint because JSON mode is the machine-readable login
255
- contract.
253
+ machine reader, and the final result. It signs in with a device code, so the
254
+ browser can run on any machine. See
255
+ [Signing in when the browser is on another machine](#signing-in-when-the-browser-is-on-another-machine).
256
256
 
257
257
  The command opens the page in the default browser itself when a browser can be
258
258
  reached. It does not try on CI, over SSH, in a container, on Linux with no
@@ -263,21 +263,16 @@ URL for manual sign-in. Either way, it keeps reading the same process until its
263
263
  terminal event. A failed sign-in prints one final failure object and exits
264
264
  nonzero.
265
265
 
266
- After the CLI exchanges the browser token and saves its credentials, the
267
- agent-onboarding callback page tries to close the tab. If the browser blocks
268
- closing, the page keeps a visible success message so the user can close it
269
- manually. Exchange or credential-save failures keep a visible error page open.
270
-
271
266
  The bundled onboarding prompt gives one short explanation before it opens the
272
267
  page: sign-in lets the coding agent create a project and API key, and the user
273
268
  can remove the key later to disconnect the workspace.
274
269
 
275
270
  ### Signing in when the browser is on another machine
276
271
 
277
- The flow above sends the browser back to a loopback server on the CLI's own
278
- machine. That fails over SSH, in a VM, or in a container, because the browser
279
- runs somewhere else. From 4.14.0, the CLI uses a device authorization grant
280
- (RFC 8628) instead:
272
+ Plain `copilotkit login` sends the browser back to a loopback server on the
273
+ CLI's own machine. That fails over SSH, in a VM, or in a container, because the
274
+ browser runs somewhere else. `login --device` and `login --json` use a device
275
+ authorization grant (RFC 8628) instead:
281
276
 
282
277
  ```bash
283
278
  copilotkit login --device # at a terminal
@@ -299,8 +294,7 @@ codes in a row expire with nobody approving them, `login --json` refuses to
299
294
  request another. It writes a `failed` record with `reason: repeated_expiry` and
300
295
  exits non-zero. Run `copilotkit login --json --force` when someone is ready to
301
296
  approve. Any sign-in that succeeds resets the count, and the count lapses after
302
- a day. If the Ops service has no device routes, `login --json` falls back to the
303
- loopback flow.
297
+ a day.
304
298
 
305
299
  Approve a code only if your own terminal or coding agent showed it to you. If
306
300
  someone sent you a code, deny the request: approving it signs their CLI in as
@@ -320,6 +314,13 @@ Run `onboard start` in the project folder, or in an empty folder for a new app.
320
314
  - A folder with its own Git repository is one project, even when its parts sit
321
315
  in subfolders such as `frontend/` and `backend/`.
322
316
 
317
+ `onboard start` is meant for a coding agent. If stdout is a terminal and the CLI
318
+ detects no coding agent, it prints the agent prompt as usual and then a short
319
+ note for a person. The note tells them to open their coding agent in the
320
+ folder and paste the prompt that they copied. It also gives a line to paste
321
+ that continues the same run. An agent that the CLI does not detect reads the
322
+ full prompt above the note, so the note does not block it.
323
+
323
324
  ## Feature onboarding for existing apps
324
325
 
325
326
  Use the optional `--intent` flag when an existing CopilotKit app needs one
@@ -362,7 +363,9 @@ as `unreportable`. It records the coding agent the environment shows as
362
363
  `detected_coding_agent`, and sets `coding_agent_mismatch` when that agent differs
363
364
  from the declared one. `cli.onboarding.started` also carries
364
365
  `detected_coding_agent`, because a run that stops before `onboard identify` sends
365
- no identify event. Channel setup stage events include
366
+ no identify event. It also carries `audience`: `detected-agent` when the
367
+ environment shows an agent, `human-terminal` for a terminal with no detected
368
+ agent, and `non-tty` otherwise. Channel setup stage events include
366
369
  the existing `onboarding_run_id` when the command runs inside an onboarding run;
367
370
  standalone commands omit it. These events use the CLI's existing telemetry consent gate.
368
371
 
@@ -1055,6 +1058,23 @@ in `web/.env.local`, which is the file the app loads. Two such packages below, o
1055
1058
  none, adds nothing to the search, because a credential resolved from the wrong
1056
1059
  half is worse than one reported as absent.
1057
1060
 
1061
+ `project select` records the directory it wrote the key into as
1062
+ `"apiKeyDirectory"` in `.copilotkit/project.json`, relative to that file.
1063
+ `verify` (and `onboard proof-check`, which runs it) also reads the key from
1064
+ that directory. This is how a run from the root finds the key when the frontend
1065
+ and the runtime are sibling packages. Only the key is read from there, and only
1066
+ when no other directory in the search supplies one. A recorded directory outside
1067
+ the project is ignored, and the report says so. If another directory supplies a
1068
+ different key, `verify` uses that key and adds a warning that names both files.
1069
+ When no key is found, the report names every directory it read and every app
1070
+ package it did not read.
1071
+
1072
+ The record also settles **The app can load the project API key** when the root
1073
+ holds more than one app. The check is made for the package that depends on
1074
+ `@copilotkit/runtime`, because its process reads the key. A key recorded in the
1075
+ frontend while a sibling package hosts the runtime fails this check. It never
1076
+ passes.
1077
+
1058
1078
  Being found is not the same as being loadable. A framework's env loader does not
1059
1079
  walk up — Next.js, Vite, Nuxt and Astro all read env files from the application's
1060
1080
  own directory — so a key at the repository root is invisible to an app in a
@@ -1339,9 +1359,13 @@ Ask the vendor about one key before the build:
1339
1359
 
1340
1360
  ```bash
1341
1361
  copilotkit onboard model-key --key OPENAI_API_KEY
1342
- copilotkit onboard model-key --key ANTHROPIC_API_KEY --env-file agent/.env --json
1362
+ copilotkit onboard model-key --key ANTHROPIC_API_KEY --env-path agent/.env --json
1343
1363
  ```
1344
1364
 
1365
+ The flag is `--env-path`, not `--env-file`. Node 20 and 22 read `--env-file`
1366
+ anywhere on the command line, and they exit with code 9 on a missing file before
1367
+ the CLI starts.
1368
+
1345
1369
  The command reads the key from the env file (`.env` by default) and sends one
1346
1370
  request with a one-token answer to that vendor. The call costs a fraction of a
1347
1371
  cent. It knows `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `GOOGLE_API_KEY`.
@@ -1391,7 +1415,22 @@ copilotkit onboard credentials --model-key OPENAI_API_KEY --json
1391
1415
 
1392
1416
  It asks the vendor about each key, as `onboard model-key` does. When every key
1393
1417
  settles, it protects the credential paths for the run's audit. A missing or
1394
- refused key is a `needs-developer` answer.
1418
+ refused key is a `needs-developer` answer. For a missing `OPENAI_API_KEY`,
1419
+ `ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY`, `question.ask` also names the vendor
1420
+ page that creates a key and the vendor account that pays for the model calls.
1421
+
1422
+ When the agent runs as its own service, that service reads its own env file.
1423
+ Name that file with `--copy-to`:
1424
+
1425
+ ```bash
1426
+ copilotkit onboard credentials --model-key OPENAI_API_KEY \
1427
+ --copy-to ../agent/.env --json
1428
+ ```
1429
+
1430
+ The step copies each key into that `.env` file and protects it with the other
1431
+ credential paths. `copiedKeys` gives the outcome for each copy. A file that
1432
+ already holds another real value keeps it. The step stops when git does not
1433
+ ignore the file, because the key would then be committed.
1395
1434
 
1396
1435
  It needs a bound run and exits zero for every answer. A `stopped` answer files
1397
1436
  the stop report itself. It never prints a key.
@@ -1596,3 +1635,337 @@ A failed install leaves the configured app in place: run `npm install`, then `np
1596
1635
  The starter listens on localhost and uses one local developer identity. Before deployment, add verified user authentication, request limits, and durable Managed Agents session mappings. Intelligence thread storage does not replace that adapter mapping.
1597
1636
 
1598
1637
  Release ordering: merge the CopilotKit starter before releasing this command. The shared starter catalog includes `examples/integrations/claude-managed-agents`, so the release source gate rejects a template revision that omits it. The command uses the build-pinned CopilotKit revision, like the existing starters.
1638
+
1639
+ ## Local evaluation candidate setup
1640
+
1641
+ This preview accepts macOS with Docker Desktop and Linux with rootful Docker Engine.
1642
+ The CLI checks daemon identity and refuses unknown engines, rootless Docker, Podman,
1643
+ non-Desktop macOS engines, Windows, and Docker Desktop on Linux. The Windows init picker
1644
+ does not offer local evaluation. Native Linux still requires runtime acceptance before
1645
+ publication. Linux sign-in requires a Docker gateway on a host IPv4 interface. On restart,
1646
+ the CLI checks the auth port on both loopback and that gateway before Docker changes.
1647
+ If another process holds either address, stop that process and retry.
1648
+ Linux Docker builds may omit platform branding; the CLI still requires an Engine component,
1649
+ rootful mode, and a host gateway. A failed Docker query reports `docker_unavailable` with
1650
+ start/retry guidance, rather than claiming the engine is unsupported.
1651
+
1652
+ For local evaluation testing, start with the
1653
+ [local evaluation tester guide](../../docs/runbooks/local-evaluation-testing.md).
1654
+
1655
+ `local setup` selects the latest stable published chart automatically. It does
1656
+ require `self-hosted.local-evaluation` for a new stack. Existing records remain manageable
1657
+ when the flag is off. A candidate file overrides release selection. The CLI downloads
1658
+ its private Helm tool, checks chart support, and pins the chart checksum and runtime
1659
+ image digests. Saved stacks resume with their saved release.
1660
+
1661
+ The September 28 check found that release 0.13.8 lacks the local evaluation profile.
1662
+ Automatic setup reports `release_unavailable` before license issuance or cluster creation for this release.
1663
+ This is a release packaging blocker, not a request for user configuration.
1664
+ The Ops service still controls evaluation license issuance separately.
1665
+
1666
+ For a local or prerelease CLI build, the release operator can set `CLI_LOCAL_CHART_VERSION`
1667
+ to an exact published candidate version. The built CLI then uses that version for plain
1668
+ `local setup`. It rejects mismatched chart metadata and retains the chart checksum and image checks.
1669
+ The build rejects version ranges, build metadata, and pins in production distribution builds.
1670
+ An unset pin retains stable release selection. This build input does not enable Ops issuance
1671
+ or prove fresh-install acceptance.
1672
+
1673
+ Use `--candidate /path/to/candidate.json` only to override release selection during
1674
+ development or release testing. Full fresh-install acceptance remains incomplete.
1675
+
1676
+ Use Docker with at least 4 CPUs, 12 GiB RAM, and 40 GiB free storage available
1677
+ for each stack. The CLI measures Docker resources after existing workloads.
1678
+ The CLI downloads private, checksum-verified Helm and k3d tools.
1679
+
1680
+ 1. Sign in with `copilotkit login`.
1681
+ 2. Open the app directory.
1682
+ 3. Run `copilotkit local setup --defer-model`.
1683
+ 4. Run `copilotkit local connect` to review the app connection changes.
1684
+ 5. After approval, run `copilotkit local connect --approve-connection`.
1685
+
1686
+ The local organization uses the ID and name from your verified evaluation license.
1687
+ It represents the organization selected during CLI sign-in, with a separate local database.
1688
+ Setup does not copy hosted projects or data. Renewal cannot change the stack's organization.
1689
+ If a license does not match the local database, App API and the Learning scheduler refuse
1690
+ startup and retain saved data. Older test stacks with a generic organization ID need an
1691
+ explicit data migration; setup will not reassign their existing projects.
1692
+
1693
+ For a new app, full init uses the same installer and connects the new scaffold:
1694
+
1695
+ ```bash
1696
+ copilotkit init -n local-app -f langgraph-js --local --defer-model --no-install
1697
+ ```
1698
+
1699
+ For an existing app, run full init from its directory:
1700
+
1701
+ ```bash
1702
+ copilotkit init --local --existing
1703
+ ```
1704
+
1705
+ At a terminal, init asks the same questions as `local setup`: the guided model prompt
1706
+ (provider, key, model, or configure later), then whether to add sample data. It installs
1707
+ the latest release, completes sign-in when needed, and asks before replacing the app
1708
+ connection. `--candidate` overrides the release for testing only. Installed-stack recovery
1709
+ uses saved inputs without requiring an Ops session.
1710
+
1711
+ For an unattended existing-app setup, supply inputs and approve the connection separately:
1712
+
1713
+ ```bash
1714
+ copilotkit init --local --existing --json --defer-model
1715
+ copilotkit init --local --existing --approve-connection --json
1716
+ ```
1717
+
1718
+ The first command prepares the stack and requests connection approval. The second
1719
+ uses the saved release and connects the app. It saves the prior settings before
1720
+ replacement. Hosted data stays in the hosted service; the local project starts empty.
1721
+
1722
+ Add `--json` to new-app local init for one versioned result without terminal prompts.
1723
+ Missing inputs return exit code 2 together with a resume command. Failures return
1724
+ exit code 1 and recovery guidance. If a new app already exists after interruption,
1725
+ enter its directory and resume with `init --local --existing --json`.
1726
+
1727
+ Interactive init offers the deployment choice before authentication. Agent-driven
1728
+ onboarding offers the same choice and calls the local commands directly. It does
1729
+ not invoke full init. Both paths still need validation against published artifacts.
1730
+
1731
+ The manifest must identify the published chart, its checksum, image digests,
1732
+ and tool downloads for the current platform. `--defer-model` leaves Learning
1733
+ model configuration incomplete. To provide your model settings instead, use
1734
+ `--model-config /path/to/private-model.json`:
1735
+
1736
+ ```json
1737
+ {
1738
+ "model": "openai/your-model",
1739
+ "provider": "openai",
1740
+ "apiKey": "your-model-key"
1741
+ }
1742
+ ```
1743
+
1744
+ Keep that file outside source control. An optional `baseUrl` selects the model
1745
+ endpoint. The stack does not include a model or provider credentials.
1746
+
1747
+ Interactive init offers app model reuse, a separate Learning model, or deferral.
1748
+ For reuse, put the app's model and credentials in the private JSON file.
1749
+ The CLI does not read or guess credentials from app source files.
1750
+ Both file choices use the same validation as `--model-config`.
1751
+ Without `baseUrl`, use an OpenAI or Anthropic model with its API key.
1752
+ Custom endpoints must support the OpenAI-compatible API; their API key is optional.
1753
+ Configuration belongs to the installation, including all apps that share that stack.
1754
+ Saving configuration does not prove model access. A real Learning run provides that proof.
1755
+
1756
+ For a model on the Docker host, use a configuration such as:
1757
+
1758
+ ```json
1759
+ {
1760
+ "model": "local/your-model",
1761
+ "provider": "compatible",
1762
+ "baseUrl": "http://localhost:11434/v1"
1763
+ }
1764
+ ```
1765
+
1766
+ The CLI replaces loopback addresses and `host.docker.internal` with
1767
+ `host.k3d.internal` in the Kubernetes Secret.
1768
+ [k3d supplies this host DNS record](https://k3d.io/v5.8.3/usage/k3s/).
1769
+ Bind the model server to an interface reachable from Docker and allow that port through the host firewall.
1770
+ A server bound only to loopback cannot accept traffic through the Docker bridge.
1771
+ With a remote Docker engine, the model must be reachable from that engine's host.
1772
+ The CLI does not start the model server or prove endpoint access during setup.
1773
+
1774
+ Run `copilotkit local setup` from the app directory for guided model configuration.
1775
+ Choose OpenAI, Anthropic, or an OpenAI-compatible endpoint, then supply an API key in
1776
+ the masked prompt. Compatible endpoints ask for their base URL first and may omit the key.
1777
+ The CLI sends the key only to that provider's model list (`/v1/models`, or `<base URL>/models`)
1778
+ and shows the models it can use that Learning supports. Learning resolves OpenAI and Anthropic
1779
+ models through the catalog pinned with its runtime, so newer models a provider lists are hidden
1780
+ until that catalog is upgraded; the CLI refuses them from prompts and `--model-config` files alike.
1781
+ OpenAI-compatible endpoints accept any model ID. Type to filter, use the arrow keys or Tab to pick
1782
+ one, or enter an unlisted supported ID. A rejected key returns to key entry. If the list cannot be
1783
+ loaded, the prompt shows the supported models instead. Listing models does not prove that a
1784
+ Learning run works.
1785
+ Esc or Ctrl+C cancels before setup changes the stack. `--defer-model` skips this flow.
1786
+
1787
+ For scripts, use `copilotkit local setup --model-config /path/to/private-model.json`
1788
+ or `--defer-model`. Fresh setup without a terminal, including `--json`, requires
1789
+ one of these flags. Existing unattended setup without model flags keeps saved settings.
1790
+
1791
+ After deferral, either method configures Learning. This replaces the saved model configuration.
1792
+ On a running, ready stack it updates the model secret and restarts only the Learning agent;
1793
+ the dashboard stays up and images, databases, and migrations are not reapplied. A stopped,
1794
+ failed, or unfinished stack gets the full installation instead.
1795
+ It keeps the saved release, license, ports, and stack credentials.
1796
+ If installation fails, run `copilotkit local setup --json` to retry with the saved model configuration.
1797
+ To remove model configuration, run `copilotkit local setup --defer-model`.
1798
+
1799
+ Setup saves its release, ports, credentials, and recovery inputs before
1800
+ installation. After an interrupted install, run `copilotkit local setup --json` from
1801
+ the same app directory to reuse all saved inputs without another prompt or another
1802
+ license. A different candidate requires an explicit update.
1803
+
1804
+ Use `copilotkit local list` to find saved stacks, including stacks whose app
1805
+ folders are missing. Use `local status`, `local start`, or `local stop` with
1806
+ `--stack <id>` to select one. Stop preserves data. Logout does not remove stacks.
1807
+
1808
+ Run `local credentials` to show the generated dashboard login. This command does
1809
+ not contact Ops or Docker. Keep its output private.
1810
+
1811
+ ### First start and later restarts
1812
+
1813
+ Run these commands from the app directory. First start does not require an existing evaluation:
1814
+
1815
+ ```sh
1816
+ copilotkit login
1817
+ copilotkit local start --defer-model
1818
+ ```
1819
+
1820
+ On first start, the CLI selects and verifies a release, obtains the temporary evaluation
1821
+ license, installs its private tools, and creates the stack. First installation needs network
1822
+ access. `--defer-model` lets you test sign-in before you configure Learning.
1823
+ Use `--model-config /path/to/private-model.json` instead to configure Learning during setup.
1824
+
1825
+ For later starts, run the same `local start --defer-model` command. It retains the saved
1826
+ release, license, model configuration, credentials, ports, and data. Normal start and stop
1827
+ use Docker directly; they do not require Helm or k3d downloads or an Ops session.
1828
+ Start waits for App API, the dashboard, and the realtime gateway before returning.
1829
+ An interrupted installation resumes through the installer using its saved inputs.
1830
+ An explicit unknown `--stack` ID fails without creating replacement storage.
1831
+
1832
+ Interactive setup shows the CLI kite spinner, the current phase, and elapsed setup time.
1833
+ Repeated image operations share one status line. Piped output uses plain phase lines;
1834
+ `--json` emits only its result envelope. A failed setup names the phase that stopped.
1835
+
1836
+ The caller never needs to run k3d. Use `local setup` to change an existing
1837
+ installation's Learning settings. After startup, follow the CLI sign-in steps below when
1838
+ the stack is ready.
1839
+
1840
+ ### Sample threads and Learning container
1841
+
1842
+ A fresh interactive `local setup` asks whether to add sample data after the model prompt.
1843
+ Every later interactive `local setup` asks again once the stack is ready, while it has no samples.
1844
+ Rerunning setup with the same model choice on a running stack changes nothing and restarts nothing.
1845
+ Yes imports 16 sample conversations (support, sales, and coding agents) through the thread
1846
+ import API and binds them to a separate Learning container, `samples` ("Sample conversations"),
1847
+ so your app's own threads never mix with them. The conversations contain recurring mistakes and
1848
+ user corrections for Learning to find. Setup does not start a Learning run; start one from
1849
+ Learning in the dashboard once a model is configured.
1850
+
1851
+ `--samples` or `--no-samples` answers the question without a prompt. JSON and non-interactive
1852
+ setup add samples only with `--samples`. To add them later, or to retry, run
1853
+ `copilotkit local samples` from the app folder (or `--stack <id>`). Stable sample IDs make a
1854
+ repeat import add no duplicates. If the license does not include Learning, the threads are
1855
+ still imported and the CLI reports why the container was not created. A seeding failure never
1856
+ fails setup.
1857
+
1858
+ ### Background CLI sign-in
1859
+
1860
+ New local evaluations use the background CLI provider as their only dashboard sign-in method.
1861
+ Node.js 22 or newer and macOS or Linux are required.
1862
+ Setup and `local start` start the background provider. `local stop` stops it.
1863
+ When setup finishes in an interactive terminal, it opens the same one-use sign-in as
1864
+ `local login`. No code approval is needed. JSON and non-interactive
1865
+ runs never open a browser; they name the `local login` command instead.
1866
+ `local status` reports both stack readiness and provider health.
1867
+
1868
+ Run `copilotkit local login` from your app folder. It opens the browser and the dashboard
1869
+ signs you in without a code or a click. Dashboards released before this change still show
1870
+ **Sign In**; choose it. Outside the app folder, add `--stack <id>`.
1871
+ The command starts the provider if needed; the stack itself must already be running.
1872
+ It needs no hosted session or network access beyond the local stack.
1873
+
1874
+ For sign-in started directly in the browser, or if the CLI cannot open a browser:
1875
+
1876
+ 1. Open the dashboard URL and select **Sign In**.
1877
+ 2. Run `copilotkit local auth pending --stack <id>`.
1878
+ 3. Match the terminal code with the browser code.
1879
+ 4. Run `copilotkit local auth approve CODE --stack <id>` or `deny CODE`.
1880
+
1881
+ `local credentials` prints the login command, approval fallback, and dashboard URL. It prints no password.
1882
+ The provider continues after the terminal closes. Requests expire after two minutes.
1883
+ Terminal login links expire after two minutes and work once. The CLI does not print them.
1884
+ After upgrading an already-running provider, stop and start it with `local auth stop`
1885
+ and `local auth start` before using `local login`. Neither command removes stack data.
1886
+ Only approve a request you initiated. Local processes with access to your private
1887
+ CLI files can also approve requests; shell access is part of the trust boundary.
1888
+
1889
+ After a provider crash, run `copilotkit local auth start --stack <id>`.
1890
+ After a host restart, run `copilotkit local start --stack <id>`.
1891
+ Both reuse the saved identity and signing key without an Ops session or internet access.
1892
+ An interrupted browser request must start again. Recovery does not restore Keycloak.
1893
+ The CLI does not install an OS login service.
1894
+
1895
+ The installer writes auth settings into Helm values. Updates retain those settings.
1896
+ Browser traffic binds to loopback. On native Linux, the provider also binds the
1897
+ verified Docker gateway when it is a host interface. Docker Desktop on macOS uses
1898
+ `host.docker.internal`. Approval uses a private Unix socket, not an HTTP endpoint.
1899
+ The OIDC client uses an exact callback URL, PKCE, and signed ID tokens.
1900
+ App API still enforces organization, project, and license access.
1901
+
1902
+ ### Operate the local stack
1903
+
1904
+ Run Learning and Channels commands from an app connected to the local stack.
1905
+ They use that stack's saved project and private service credential, without an Ops session.
1906
+ Local Learning reads and configuration calls need no internet connection.
1907
+ Learning runs still need the configured model. Slack and Teams still need internet
1908
+ access and a public HTTPS address that you supply. A real mention and useful reply
1909
+ remain required for Channels proof.
1910
+
1911
+ Local commands use the existing CLI telemetry consent settings. Local diagnostic
1912
+ logs record step names, elapsed time, and exit status. They exclude command inputs,
1913
+ subprocess output, model credentials, and license tokens.
1914
+
1915
+ Run `copilotkit local renew --stack <id>` to request a license for the current
1916
+ organization plan. Renewal requires internet access and CopilotKit sign-in.
1917
+ Non-Enterprise licenses last 30 days. Enterprise licenses follow the recorded paid-term
1918
+ end date, or last 30 days when no end date exists. Free organizations qualify without
1919
+ payment. Paid organizations must pass the current account-standing checks. The CLI saves
1920
+ the new token before applying it. If the stack is stopped, `local start` applies
1921
+ the saved renewal. Renewal preserves data and does not restart accepted Learning
1922
+ jobs. If application fails, rerun `local renew` to apply the saved token.
1923
+
1924
+ Demo licenses require a CLI-managed k3d node inside Docker. During installation,
1925
+ the CLI checks the Docker node and writes evidence for the signed organization.
1926
+ App API and the Learning scheduler check that evidence before startup. Missing or
1927
+ mismatched evidence stops those services with a recovery message; it does not delete data.
1928
+ The check does not grant a customer-managed hosting entitlement.
1929
+
1930
+ Run `copilotkit local update` from the app folder (or add `--stack <id>`) to move the stack
1931
+ to the latest release; it says so when the stack already runs it. `--candidate
1932
+ /path/to/release.json` chooses a specific release for testing. The CLI preserves the completed release
1933
+ and saves the attempted release before database changes. It stops producers and
1934
+ requires active jobs to finish before migrations. It never resets storage or
1935
+ rolls back a database automatically.
1936
+
1937
+ After interruption, run `copilotkit local status --stack <id>` to inspect the
1938
+ saved update state. Run `copilotkit local update --stack <id>` to resume the
1939
+ recorded candidate. If migration completion is unknown, `local start` reports
1940
+ that recovery command without starting application services. If migrations
1941
+ completed, `local start` finishes the recorded update and checks readiness.
1942
+
1943
+ Candidates must declare compatibility with the saved schema. Published charts carry
1944
+ that declaration in `local-evaluation-release.json`; charts packaged before it existed
1945
+ declare none, so update refuses them. A candidate that
1946
+ requires Kubernetes replacement cannot use this update path. Candidate and
1947
+ update acceptance tests against published artifacts are still required.
1948
+
1949
+ For an existing app, connection requires `--approve-connection`. The local project
1950
+ starts empty; hosted data is not copied. `local cancel` restores the prior settings
1951
+ that still match this setup's writes. It reports conflict names and keeps later
1952
+ edits and stack data. Connection refuses to write an API key into a tracked `.env`.
1953
+
1954
+ A copied app requires `--share-stack` to share its original stack. Deletion
1955
+ lists every associated app path. Before deleting, `local delete` gives every connected app its earlier
1956
+ connection settings back, as `local cancel` does; settings it cannot restore (a missing
1957
+ folder or later edits) are kept privately under `local-evaluation-recovery/`.
1958
+ At a terminal, `copilotkit local delete` asks before it
1959
+ deletes anything; "No, keep it" is the default. Scripts and `--json` confirm shared data
1960
+ loss with `copilotkit local delete --stack <id> --confirm-delete <id>`. Every local command
1961
+ that uses the stack (`setup`, `start`, `stop`, `delete`, `update`, `status`,
1962
+ `renew`, `login`, and `auth start`) checks Docker before it prompts, asks for
1963
+ confirmation, or downloads anything. It stops with a Docker message when Docker
1964
+ is not running or the engine is not supported. The CLI does not start Docker.
1965
+ If Docker has no cluster for the stack, delete removes only the saved stack
1966
+ settings and app references.
1967
+
1968
+ `--json` returns versioned command results. Setup reports missing candidate and
1969
+ model-choice inputs together before authentication. Cold installation,
1970
+ offline operation, and platform acceptance are not yet validated for a
1971
+ published candidate.
@@ -2,20 +2,20 @@
2
2
  "schemaVersion": 1,
3
3
  "package": {
4
4
  "name": "copilotkit",
5
- "version": "4.22.0"
5
+ "version": "4.23.0"
6
6
  },
7
7
  "intelligence": {
8
- "commit": "eb758b6e228f004116a17404e40de14754423fc8"
8
+ "commit": "9fc4219b274ac05ae24f540bce5c3a338939740d"
9
9
  },
10
10
  "copilotKit": {
11
- "submittedInput": "4b51d880eab2",
12
- "commit": "4b51d880eab2617e3196285ddcf0e4ff7b34a237"
11
+ "submittedInput": "f835ce816112541654ded07162c2cc8ddf4f3f2c",
12
+ "commit": "f835ce816112541654ded07162c2cc8ddf4f3f2c"
13
13
  },
14
14
  "channel": "production",
15
- "triggeringActor": "BenTaylorDev",
15
+ "triggeringActor": "tylerslaton",
16
16
  "workflow": {
17
- "runId": "36810989756",
18
- "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36810989756"
17
+ "runId": "36949776521",
18
+ "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36949776521"
19
19
  },
20
20
  "validationResult": "passed",
21
21
  "ag2": {
@@ -24,5 +24,5 @@
24
24
  "revision": "main",
25
25
  "pinned": false
26
26
  },
27
- "builtAt": "2026-10-01T03:34:23Z"
27
+ "builtAt": "2026-10-02T01:13:44Z"
28
28
  }