Repository navigation
Expand file tree
/
Copy pathloom.example.yaml
More file actions
6011 lines (4563 loc) · 273 KB
/
Copy pathloom.example.yaml
File metadata and controls
6011 lines (4563 loc) · 273 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# yaml-language-server: $schema=schemas/loom-settings.schema.json
#
# Loom settings file: every setting, at its default. Generated from
# server/settings/catalog.py by
# `python scripts/codegen/settings_example.py`; do not edit this copy.
#
# Each key is a setting's LOOM_<NAME> environment variable in lowercase: set any line
# here as LOOM_<NAME> in the environment or in .env, which win over this file. A
# deployment that mounts a config file can instead copy this file (for example to
# loom.yaml), point LOOM_SETTINGS_FILE at it, and uncomment the lines it changes;
# every other setting keeps its default.
#
# A setting marked `live` also changes while Loom runs, deployment-wide and without a
# restart: `loom settings set <name> <value>` or the dashboard's Deployment settings
# page. One marked `restart` is read when a process starts.
#
# Features switch on and off with the settings ending in `_enabled`: search this file
# for "_enabled:". Secrets (passwords, keys, tokens) are not here: they go in the
# environment, .env or a secrets manager (docs/reference/configuration.md lists the
# settings that are secrets, docs/reference/environment.md the provider API keys).
#
# A secret, a key given twice, an unsupported version, or a value of the wrong type
# or outside its bounds stops the server at startup, naming the key. A name no
# setting has is logged and ignored.
version: 1
settings:
# ===== ClickHouse connection, query shaping and vector storage =====
# Host name of the ClickHouse server Loom stores everything in. [restart]
# ch_host: "localhost"
# ClickHouse HTTP port; 8443 (the Cloud HTTPS port) turns TLS on when `ch_secure` is
# unset. [restart]
# ch_port: 8123
# User name the server connects to ClickHouse as. [restart]
# ch_user: "loom"
# The database Loom's schema lives in: every table, view and the migrations ledger,
# and the connection's default database. Statements are written against `loom` and
# name this database where they reach ClickHouse (server/core/ch_names.py); KeeperMap
# paths move with it. Set it before the first migration: while a schema is in `loom`,
# a server pointed at a name that does not exist, or holds tables but no Loom ledger,
# refuses to start (create it empty to start a second schema). A letter or `_`, then
# letters, digits, `_` and `-`; never `default`, `system`, `information_schema`, or a
# table or alias name the schema uses. Read once at startup. [restart]
# ch_database: "loom"
# The database the telemetry Loom derives from its own tables lives in (`sli_minute`),
# outside the schema so a reader can be granted it alone. A schema outside `loom`
# names its own: two schemas never share one. [restart]
# ch_telemetry_database: "loom_telemetry"
# The cluster `clusterAllReplicas` reads to find a stopped Loom process's queries on
# every node (`default` on ClickHouse Cloud). A server without it answers for itself;
# '' reads only the connected server. [restart]
# ch_cluster: "default"
# Connect over HTTPS. Unset infers TLS from the port (8443 on, anything else off).
# [restart]
# ch_secure: null
# Additional trusted writer HTTP origins for analyst setup policy observations. Uses
# the configured service credentials; missing or duplicate writers refuse. [restart]
# ch_analysis_observer_urls: []
# Append `sql:<shape12> <first 200 chars>` of each statement to its `log_comment`
# ("<op> <request_id>"), so query_log rows group by shape. A statement that carries a
# secret, or one run as the analyst, gets its shape alone. Off by default: readers
# that split log_comment on spaces gain tokens. [restart]
# ch_log_comment_statement_digest: false
# A file path: append one JSON line (`digest`, `sql`) per executed statement, to
# collect the shapes an acceptance run executes for the analyzer corpus. '' = off;
# never set it in production. [restart]
# ch_capture_statements: ""
# HTTP connection pool size: request concurrency plus 3 x the batched-insert bound
# (inserts a second x wait / 1000; docs/architecture/clickhouse.md#batched-inserts).
# [restart]
# ch_pool_maxsize: 64
# Keeper holders a fenced writer acquires or releases at once (1–256), capped by a
# bounded HTTP connection pool. [restart]
# ch_write_fence_concurrency: 16
# Memory rows per ClickHouse namespace-restore insert (1–1000). Smaller batches leave
# more lease budget for slow Keeper calls. [restart]
# ch_restore_batch_rows: 1000
# Seconds an idle pooled connection is kept. Must stay BELOW the Cloud load balancer's
# idle cutoff (8 s) so loom closes first: a peer-closed pooled TLS connection is never
# reaped under uvloop (`LOOM_UVICORN_LOOP=uvloop`). [restart]
# ch_keepalive_timeout: 5.0
# A point lookup that MISSES right after a write (get after set, verify, update_by_id,
# delete) re-reads once with select_sequential_consistency=1. Costs only on a miss; a
# no-op on single-node MergeTree. [restart]
# ch_read_your_writes: true
# memory.search on a namespace this process wrote within this many seconds reads with
# select_sequential_consistency from the start. 0 = off (the empty-pool retry remains
# the backstop). [restart]
# ch_read_your_writes_window_s: 20.0
# Deadline, seconds, for read statements, applied as `max_execution_time` and as a
# client-side bound that frees the pool slot. 0 = no general read bound. Enforced-cell
# SCIM decisions still have a complete 30-second ceiling, reduced by a smaller
# positive value. [restart]
# ch_timeout_read_s: 30.0
# Deadline, seconds, for INSERT and UPDATE statements; 0 = no bound. [restart]
# ch_timeout_write_s: 60.0
# Deadline, seconds, for DDL statements (CREATE, ALTER, DROP); 0 = no bound. [restart]
# ch_timeout_ddl_s: 300.0
# Batch the inserts written on every request into shared parts; false commits them,
# and the waited async inserts keep their bounds
# (docs/architecture/clickhouse.md#batched-inserts). [live]
# ch_batched_inserts: true
# Shortest wait, ms, of a batched or waited async insert: what a lone insert waits
# when writes are sparse; capped at ch_batched_insert_wait_max_ms (or the background
# bound). [live]
# ch_batched_insert_wait_min_ms: 10
# Longest wait, ms, of a batched or waited async insert a request waits on; it holds a
# pooled connection meanwhile. [live]
# ch_batched_insert_wait_max_ms: 50
# Longest wait, ms, of the usage-event flusher's ticks and shutdown drain and the
# write-mark timer's flush, which no request waits on. [live]
# ch_batched_insert_background_wait_max_ms: 200
# Max wait, ms, for a pool slot before failing fast with 503 OVERLOADED. 0 = no slot
# gate. [restart]
# ch_pool_wait_ms: 500
# Fresh connections a statement tries after a replica-bound error (a replica that lost
# its Keeper session, a replica's read-only table). Behind a load balancer one
# reconnect can land on the replica that just failed, so a single retry is not enough.
# [restart]
# ch_replica_bound_retries: 2
# --- caller-shaped read ceilings ---
# Ceilings for the reads a caller shapes (code.grep, code.search with a pattern or
# globs, memory.aggregate, memory.record.query). A ceiling only lowers the statement's
# own value, so no request can widen it; 0 = none. The shipped loom_reader profile
# (nlp_user_settings.xml) caps these three at their defaults, with a floor no
# statement can go under (time: 0.05 s, code.grep's statement floor), so none can be
# set to 0 even in the SQL. Raising a setting above its cap needs the profile raised
# too; a 0 sends no ceiling, so the profile's cap applies (code.grep's deadline is
# then clamped to ch_timeout_read_s, which the profile's cap matches).
# Seconds one caller-shaped read may run (the read class default); 0 = no ceiling, so
# the loom_reader profile's cap applies. [restart]
# ch_caller_shaped_max_execution_s: 30.0
# Bytes of memory one caller-shaped read may use; 0 = no ceiling, so the loom_reader
# profile's cap applies. [restart]
# ch_caller_shaped_max_memory_bytes: 4000000000
# Rows one caller-shaped read may scan; past it the read fails (422), never a partial
# answer. 0 = no ceiling, so the loom_reader profile's cap applies. [restart]
# ch_caller_shaped_max_rows_to_read: 500000000
# ClickHouse user the caller-shaped reads run as, with `ch_password`; the shipped
# config defines `loom_reader` (SELECT only). Empty = `ch_user`. [restart]
# ch_reader_user: ""
# --- analysis statements (insights.query) ---
# Caps and pacing for insights.query. The statement caps are pinned as a MAX in the
# loom_analyst user's caps profile so no statement can raise them; a boot whose
# ClickHouse user has access management writes that profile when one changed.
# Seconds one insights.query statement may run. [restart]
# ch_analysis_max_execution_s: 10.0
# Rows one statement may scan; past it the statement fails (422), never a partial
# answer. [restart]
# ch_analysis_max_rows_to_read: 200000000
# Bytes of memory one statement may use. [restart]
# ch_analysis_max_memory_bytes: 2000000000
# Rows one statement returns at most; a longer result comes back cut, marked
# truncated. [restart]
# ch_analysis_max_result_rows: 500
# Bytes of result one statement may return; past it the statement fails (422).
# [restart]
# ch_analysis_max_result_bytes: 4000000
# Statements the analyst user runs at once across every org and replica. [restart]
# ch_analysis_max_concurrent: 8
# Threads one statement may use (pinned as a MAX, so a statement cannot take the
# host). [restart]
# ch_analysis_max_threads: 4
# Statements one org runs at once on one replica; past it a call answers RATE_LIMITED.
# [restart]
# ch_analysis_max_concurrent_per_org: 2
# Seconds between two probes of the analyst user in each web process; a problem an
# admin fixes, or a repair a write makes, shows within one interval. [live]
# ch_analysis_probe_interval_s: 60.0
# --- traffic classes ---
# JSON map {traffic class: ClickHouse settings} applied by
# `server.core.ch.statement_settings` to every read (an explicit per-call setting
# wins). `priority`: 1 served first, larger waits, 0 opts out; `max_threads` caps CPU
# per statement. Neither changes the rows returned. `background` (workers, operator
# CLIs) bypasses the filesystem cache on a miss so a backfill scan does not evict
# interactive data. [restart]
# ch_settings_by_traffic_class: '{"production": {"priority": 1}, "interactive": {"priority": 2}, "bench": {"priority": 10, "max_threads": 4}, "background": {"priority": 5, "max_threads": 3, "read_from_filesystem_cache_if_exists_otherwise_bypass_cache": 1}}'
# --- migrations ---
# Apply pending migrations at boot. Set False for any server started from a branch
# against a shared service, or it applies unmerged migrations. [restart]
# boot_migrate: true
# Seconds after which the boot migration lease's holder, once it stops renewing, is
# replaced. [restart]
# boot_migrate_lease_ttl_s: 300
# Seconds a contender waits for the holder before boot fails (exit 1, the container
# restarts); also how long a booting process waits for the provider configuration lock
# (a sibling's rebuild step may hold it). [restart]
# boot_migrate_lease_wait_s: 900.0
# Seconds a migration file waits for the mutations it started (MATERIALIZE, UPDATE, a
# column type change) to finish on every replica; past it the file fails unrecorded.
# [restart]
# migrate_mutation_wait_s: 600
# --- vector search ---
# Send `vector_search_use_quantized_codes = 1` on vector-ranked reads whose column has
# a `Quantized(...)` codec and whose table has no patch parts: a codes-first scan plus
# full-precision rescore. A replica that rejects the setting (code 115) drops the
# fragment and retries. [restart]
# vector_search_quantized_codes: true
# Over-fetch for the codes-first read: stage 1 keeps LIMIT × this by code distance,
# stage 2 rescores. Only read when the codes setting is sent. [restart]
# vector_search_quantized_fetch_multiplier: 3.0
# Seconds between re-reads of which vector columns are coded and which coded tables
# carry patch parts. A write that embeds reads again on its own when the reading is
# older than a few seconds (codes_state.FRESH_READING_S). [restart]
# vector_codes_state_probe_seconds: 60
# --- timeouts, budgets and caches ---
# Seconds the schema status (applied against shipped migrations) is cached for the
# health probe. [live]
# schema_status_ttl_s: 60.0
# ===== Models: which model does each job =====
# --- defaults ---
# The deployment's LLM: memory extraction, rerank and every job whose own model
# setting (the other *_model settings) is left "". Empty takes the resolved provider's
# default model (gpt-6-luna / claude-haiku-4-5 / qwen2.5:3b / fake-echo-1). [restart]
# llm_model: ""
# The assistant agent's model, which Loom writes into the agent definition at boot. ""
# = the definition's own (integrations/librechat/agent.yaml), not llm_model. [restart]
# assistant_model: ""
# The LibreChat endpoint the agent runs on: "" = the definition's (anthropic), "local"
# = LibreChat's local endpoint (a model server the operator runs; needs
# assistant_model). [restart]
# assistant_provider: ""
# Model to answer with when a client's provider is still unavailable after its retries
# (429 / 5xx / transport / timeout) or rejected the request (400 / 413 / 422). Counted
# in `loom.llm.fallback`. 401 / 403 / 404 are configuration and never fall back. "" =
# fail the op. [restart]
# llm_fallback_model: ""
# Embeddings for memories, queries and code chunks. fake-ngram-3072 needs no network
# or key; production uses text-embedding-3-* (OPENAI_API_KEY). Change it together with
# `embedding_dim`; a new embedding space needs a full re-embed. [restart]
# embedding_model: "fake-ngram-3072"
# Where `local` models live (relative: under the working directory), one directory per
# alias and revision; a missing file is fetched there. The image sets it by env.
# [restart]
# local_embedding_model_dir: "var/models"
# --- memory ---
# memory.ask synthesis (the strong tier when the cascade is on). [restart]
# memory_ask_synth_model: ""
# memory.ask cheap tier. "" = off: every ask uses memory_ask_synth_model. When set,
# server/memory/domain/synth_policy.py routes easy asks cheap and hard ones strong; an
# empty, uncited or hedging cheap answer escalates to strong once. route_tier /
# route_reason / synth_model on the output record the choice. [restart]
# memory_ask_synth_model_cheap: ""
# memory.ask mid tier. "" = none. With a model set, strong-routed asks whose reason is
# in memory_ask_synth_mid_routes go mid; an empty, uncited or hedging mid answer
# escalates to strong once. [restart]
# memory_ask_mid_model: ""
# The durability check on a coding capture: one batched call per capture per listed
# model (CSV) judges each fact durable or not and folds same-claim paraphrases and
# replaced states. A fact is dropped only when every model says drop; folds come from
# the first. Fails open. "" turns it off. [restart]
# memory_extract_verify_models: "claude-opus-5-5"
# The conflict resolver's judge (memory_conflict_resolver_enabled). Its confidence
# thresholds were set on this model; a cheaper one is only safe for clears. [restart]
# conflict_resolver_model: "gpt-6.1-sol"
# Model of the profile fold, which consolidates an identity's memories into its
# profile; "" = `llm_model`. [restart]
# profile_consolidation_model: ""
# Model of the structured profile builder, which fills a user's profile in the
# namespace's schema; "" = `llm_model`. [restart]
# structured_profile_model: ""
# Reflection distillation: the outcome labeller and the contrast writer. [restart]
# reflection_distill_model: ""
# The code-link `revise` judge: does a memory's claim still hold for its code's new
# text. [restart]
# code_link_revise_model: ""
# Session briefs; without its provider's key the deployment's LLM writes them.
# [restart]
# session_brief_llm_model: "gpt-6-luna"
# --- code ---
# code.ask synthesis. Answers are memoized fleet-wide, so a stronger model costs once
# per unique question. [restart]
# code_ask_llm_model: ""
# code.search HyDE: writes a hypothetical indexed passage whose embedding runs a
# second vector list (see code_search_hyde_*). "" = off. [restart]
# code_search_hyde_model: ""
# code.search concept expansion: maps a prose, unconstrained question to likely code
# identifiers — via this model, or `cards` / `cards:<n>` (symbols of the n nearest
# file cards) — fused as a capped lexical list. "" = off. [restart]
# code_search_concept_expand_model: ""
# code.bisect_candidates' one-call rerank of the fused top 20. [restart]
# code_bisect_llm_rerank_model: "gpt-6-luna"
# File and module summary cards. [restart]
# code_summary_model: ""
# --- tracker ---
# tracker.duplicate_check's rerank call. [restart]
# tracker_dupcheck_rerank_model: "gpt-6-luna"
# tracker.duplicate_check's judge call. [restart]
# tracker_dupcheck_judge_model: ""
# --- observability ---
# The sampled retrieval judge (retrieval_judge_sample_rate). Deliberately a different
# model from the ones answering: a same-model judge measures agreement, not quality.
# [restart]
# retrieval_judge_model: "gpt-6.1-sol"
# ===== Embedding and LLM providers =====
# Vector width the embedder is asked for and the schema is sized from; the width
# probed from the embedder at boot wins when they differ. Change it together with
# `embedding_model`. Unset with a `local:*` model, it is that model's own width: leave
# it unset for a local model. [restart]
# embedding_dim: 3072
# "" = infer from `embedding_model` (fake-ngram-* → fake, text-embedding-* → openai,
# gemini* → gemini, local/local:* → local CPU embedder); or pin "openai", "gemini",
# "bedrock" (Cohere Embed v4), "local", "fake". Switching providers changes the
# embedding space: a full re-embed is required. [restart]
# embedding_provider: ""
# API root for an explicitly selected OpenAI-compatible embedding service, e.g.
# https://provider.example/v1. Empty is invalid for compatible providers. [restart]
# embedding_base_url: ""
# Send the optional dimensions request parameter to a compatible endpoint. False uses
# its native output width; responses must still match embedding_dim. [restart]
# embedding_send_dimensions: false
# Attempts an embedding call makes on a retryable failure. [live]
# embedding_retry_attempts: 3
# Longest backoff, in seconds, between two attempts of an embedding call. [live]
# embedding_retry_max_wait_s: 10.0
# OpenAI's API root, for chat and embeddings: point it at an OpenAI-compatible
# inference gateway in front of OpenAI (its /v1 root). [restart]
# openai_base_url: "https://api.openai.com/v1"
# Anthropic's API root (the Messages API is <root>/v1/messages): point it at a gateway
# in front of Anthropic. Off the default, the key also goes as a bearer, the scheme
# gateways take. [restart]
# anthropic_base_url: "https://api.anthropic.com"
# Region for native Bedrock model requests; empty uses the AWS SDK's region chain. AWS
# credentials use the SDK's role, profile or environment credential chain. [restart]
# bedrock_region: ""
# LOOM_LLM_PROVIDER=local's chat-completions root, called with no key (Ollama's
# <host>:11434/v1, llama.cpp's server <host>:8080/v1). [restart]
# local_llm_base_url: "http://localhost:11434/v1"
# Model calls with no provider key: exchange an identity token (RFC 8693) at this
# token endpoint of the gateway, and send the answer as the bearer
# (server/llm/gateway.py). The gateway must trust the token's issuer. "" = the
# provider keys. [restart]
# inference_token_url: ""
# The workload's OIDC token, as a file its platform rotates (a projected
# service-account token on Kubernetes). With inference_token_url, this or
# inference_token_audience. [restart]
# inference_workload_token_file: ""
# How inference_workload_token_file reaches the gateway: "exchange" (RFC 8693, at
# inference_token_url) or "bearer" (the file itself, read again at most every minute
# and after a 401; requires the gateway). [restart]
# inference_workload_token_mode: "exchange"
# With inference_token_url and no workload token: the audience of the identity token
# Loom signs (issuer <https public_base_url>/v1, newest RS256 key); never
# jwt_audience. [restart]
# inference_token_audience: ""
# The scope sent with the inference gateway token exchange; "" sends none. [restart]
# inference_token_scope: ""
# Seconds one token exchange with the inference gateway may take. [restart]
# inference_token_exchange_timeout_s: 10.0
# Seconds a provider check (the dashboard's Models & keys validate and save) waits for
# its probe call before it reports `timeout`. [live]
# provider_check_timeout_s: 30.0
# True: model calls and memory content go only to inference_gateway_hosts; on whenever
# a workload token is sent (inference_token_url, or the bearer mode). [restart]
# inference_gateway_required: false
# Comma-separated hostnames (exact, any case) of the gateway; required, and the only
# hosts sent to, while the gateway is required. [restart]
# inference_gateway_hosts: ""
# Header naming the customer (the org) on every model call, for a gateway that meters
# by it; set, a call naming no customer is refused (server/llm/customer.py). [restart]
# inference_customer_header: ""
# Header naming the feature that made the call (hyde, memory.search, worker.embedding,
# ...), with inference_customer_header only; "" sends none. [restart]
# inference_feature_header: ""
# The customer named on calls made for the deployment itself (startup probe, the
# recalibration worker's fixed pairs, provider checks), which belong to no org.
# [restart]
# inference_system_customer: "loom"
# True (a cell serving several customers): refuse to start without
# inference_customer_header, so no model call goes out unattributed. [restart]
# inference_customer_required: false
# How the customer header names an org, as the gateway knows it: `{org}` is the org
# id, around it letters, digits and . _ ~ : @ - only ("{org}" = the id as is).
# [restart]
# inference_customer_format: "{org}"
# JSON object from Loom's feature names (hyde, memory.search, worker.embedding, ...)
# to the gateway's (letters, digits, . _ ~ : @ -); "*" for any other; "" = Loom's.
# [restart]
# inference_feature_map_json: ""
# JSON object {header: template} every model call carries, naming whom it is for:
# {org} {namespace} {subject} {user_id}, {agent} (of a workload trust's agent token),
# {tenant} (that trust's inference_tenant_claim) and {email} (a person's). A header
# whose template renders empty is not sent, and those naming {agent} or {tenant} go
# together or not at all; set, a call naming no org is refused. "" sends none
# (server/llm/identity.py). [restart]
# inference_identity_headers_json: ""
# The workload trust claim {tenant} names: the value the trust requires of it,
# exactly. [restart]
# inference_tenant_claim: "tenant_id"
# JSON object of the gateway answers that hold one identity, not the provider:
# {"refused": [...], "wait": [...]}, each entry {"status": <int>} and at least one of
# the error body's exact "code", "type" or "message". A refused identity's job work
# waits inference_refusal_cooldown_seconds, a waiting one the answer's Retry-After.
# The default: an agent over its budget (by code, and by type and message where the
# Anthropic-shaped answer carries no code), denied, or named incompletely or
# malformed; too many of its requests in progress waits. Never list an answer the
# gateway also gives for its own failure (a credential it cannot fetch, no default
# agent): health would stop seeing it. Read only with identity headers set
# (server/llm/gateway.py). [restart]
# inference_identity_refusals_json: '{"refused": [{"status": 429, "code": "budget_exceeded"}, {"status": 429, "type": "rate_limit_error", "message": "budget exceeded"}, {"status": 403, "code": "agent_denied"}, {"status": 400, "code": "identity_incomplete"}, {"status": 400, "code": "identity_malformed"}], "wait": [{"status": 429, "code": "agent_request_limit"}]}'
# Seconds a background job leaves the work of an identity the gateway refused (an
# answer listed under "refused") before it calls for it again; 0 calls again at once.
# [restart]
# inference_refusal_cooldown_seconds: 600.0
# Seconds between each process's reads of the orgs whose model calls are switched off
# (loom.org_model_calls) and of the operators' extraction policies
# (loom.extraction_policies); a change reaches every process within it. [restart]
# model_calls_policy_refresh_seconds: 10.0
# Seconds a process trusts its copy of the org model-call switch, and of the
# extraction policies, when it cannot read it again; past it, every model call for an
# org is refused and no extraction runs (fail closed). 15 to 300. [restart]
# model_calls_policy_max_stale_seconds: 60.0
# Days a switched-off org's queued requests (the extraction queue) wait, from when the
# org was switched off, before they are dropped, each with a memory_drops record. 1 to
# 29: the queue's own 30-day TTL would otherwise remove them first, with no record.
# [restart]
# model_calls_off_max_wait_days: 7
# Waiting requests of a switched-off org one extraction-queue pass drops; the rest go
# on the next pass. [restart]
# model_calls_off_drop_per_pass: 500
# Shared query-embedding cache in loom.embedding_cache behind the per-process LRU,
# rows keyed (model, sha1(org, model, version salt, normalised text)); a call outside
# a request skips both tiers. Only single-text (query) embeds up to
# `embedding_cache_shared_max_chars` (0 = no cap) use it. Off = process cache only.
# [restart]
# embedding_cache_shared: true
# Longest query text, characters, that uses the shared cache; 0 = no cap. [restart]
# embedding_cache_shared_max_chars: 2000
# Entries the per-process query-embedding LRU holds; 0 = cache nothing. [restart]
# embedding_cache_size: 10000
# Seconds one per-process LRU entry lives. [restart]
# embedding_cache_ttl_s: 3600.0
# Derive the similarity gates from this embedder's cosine distribution at boot
# (server/memory/app/embedder_calibration.py). False pins the scalar defaults (tuned
# for text-embedding-3-small) — re-bench after an embedder change. Fake embedders and
# probe failures always use the scalars. [restart]
# adaptive_thresholds: true
# Seconds between each replica's re-read of the shared calibration
# (loom.embedder_calibration), so every replica serves the same gates. [restart]
# calibration_refresh_seconds: 60.0
# "openai" | "anthropic" | "bedrock" | "local" (LOOM_LOCAL_LLM_BASE_URL, no key) |
# "fake"; "" = infer from LOOM_LLM_MODEL's name (gpt*/o1*/o3*/o4*/chatgpt* → openai,
# claude* → anthropic, fake* → fake), else from the key present (OPENAI_API_KEY, then
# ANTHROPIC_API_KEY), else fake. Resolved once at load; an explicit value is never
# overridden. Bedrock requires llm_model and the SDK credential chain. Run `make
# bench-quick` before making anthropic a default. [restart]
# llm_provider: ""
# A fake or key-less provider is a `warn` in /v1/health `problems`; true (production)
# makes it an `error` and `status: degraded`, which preflight and monitors catch.
# Never changes the HTTP code (503 is ClickHouse-only). [restart]
# require_real_providers: false
# Reasoning effort sent to OpenAI models. "" = the lowest the model accepts (learned
# from its refusals, see server/llm/traits.py); set to pin one value for every call.
# [restart]
# llm_openai_reasoning_effort: ""
# Thinking effort sent to Claude models as `output_config.effort`: "low" | "medium" |
# "high"; "" = send none (the model's own default). A model that does not take it
# refuses it once and is not sent it again. [restart]
# llm_anthropic_effort: ""
# Most output tokens a call adds over the caller's cap for a model's hidden reasoning.
# The reserve per model is learned from the reasoning tokens its replies report (twice
# the most it has spent) and capped here. [restart]
# llm_hidden_reasoning_reserve_max: 16384
# Seconds an LLM call waits for its reply before the client retries. Generous for
# hosted models, where only a hung connection reaches it; a model server on a CPU can
# need longer (the local preset sets 900). Calls that must be fast set their own,
# shorter deadline (HyDE, search budgets). [restart]
# llm_request_timeout_s: 300.0
# Attempts an LLM call makes on a retryable failure (a 429, a 5xx, a dropped
# connection) before the fallback model takes over. [live]
# llm_retry_attempts: 4
# Longest backoff, in seconds, between two attempts of an LLM call. [live]
# llm_retry_max_wait_s: 20.0
# JSON {call: tokens} over LLM_MAX_TOKENS (in server/settings/catalog.py): the most
# tokens one kind of LLM call may write, keyed by its `llm_stage`. A count below 1 is
# refused; a call this build lacks is logged and ignored. '' = the table as declared.
# [live]
# llm_max_tokens_overrides: ""
# JSON {class: {"llm_cache": bool, "strong": bool, "mid": bool}}: `llm_cache`
# overrides the class's cache default (a per-request pin wins); `strong`/`mid` false
# bars the cascade from that tier. Unlisted = every tier eligible. [restart]
# llm_policy_by_traffic_class: '{"bench": {"llm_cache": true}}'
# Skip the rerank when the vector top hit's cosine is ≥ this (strong matches rank
# reliably; the rerank costs ~500 ms). Fallback when the adaptive gate has no probe.
# [restart]
# llm_rerank_skip_above: 0.62
# Recovery worker: retries failed embeds and reconciles orphan scope='shared' rows
# (the write path embeds inline). [restart]
# embedding_worker_enabled: true
# Seconds between recovery worker passes while there is work. [restart]
# embedding_worker_interval_seconds: 5
# Sleep after an idle embedding recovery pass (nothing to embed);
# `embedding_worker_interval_seconds` resumes once a pass writes a row. [restart]
# embedding_worker_idle_interval_seconds: 30
# Seconds between orphan reconciliation's full memory × embedding anti-joins; other
# passes check only memories of the last `embedding_worker_orphan_recent_seconds`. 0 =
# full join every pass. [restart]
# embedding_worker_orphan_full_scan_seconds: 1800
# Age window, seconds, of the memories a non-full orphan pass checks. [restart]
# embedding_worker_orphan_recent_seconds: 900
# The table the LLM response cache reads and writes; an isolated server whose boot
# migrations are off points this at its own scratch mirror. [restart]
# llm_response_cache_table: "loom.llm_response_cache"
# ===== Authentication, tokens and identity providers =====
# Comma-separated login handles and emails promoted to platform_admin (org-wide
# visibility). A handle matches a password account's subject; an email matches only an
# IdP-verified (OIDC) email, never the unverified self-signup address. Empty = no
# platform admins. [restart]
# platform_admins: ""
# True: every operation requires a valid bearer JWT. False (laptop demos only):
# missing tokens are not rejected and the SPA synthesizes a local identity.
# identity_provider=single-user forces auth off regardless. [restart]
# auth_required: true
# The one namespace auth-off mode serves (SPA identity, dashboard bootstrap, MCP/SDK
# caller defaults). Ignored when auth is required; `personal-*` and a mirror's name
# (`acl-` and 24 hex digits) are reserved and rejected. [restart]
# default_namespace: "local"
# MCP one-click connect: dynamic client registration and /oauth/authorize on top of
# the sign-in routes (device grant, token, revoke) every auth-on deployment serves.
# Opt-in: anyone can register a client. [restart]
# oauth_enabled: false
# Public base URL used in OAuth discovery and redirects; empty derives it from each
# request. Required when `oauth_login_provider` is "oidc" (the IdP callback URL is
# built from it). [restart]
# oauth_issuer: ""
# How people sign in (dashboard, `loom login`, MCP connect): "password" (Loom's own
# form) or "oidc" (the external IdP; loom maps the verified email to an account and
# still mints its own token). "oidc" closes password sign-in and self-signup, and
# requires `oauth_issuer` and the three oidc_* values. [restart]
# oauth_login_provider: "password"
# Lifetime of an OAuth access token, in seconds; at most a day, which bounds access
# after the IdP deactivates someone (only a refresh asks it). [restart]
# oauth_access_token_ttl_seconds: 3600
# Seconds a password set-up link stays valid, at most a week (it sets a password
# once). [restart]
# password_link_ttl_seconds: 86400
# Seconds between passes of the always-on sweep that drops sign-in state
# (loom.oauth_signin_state keys) past its credential's expiry. [restart]
# oauth_signin_state_sweep_interval_seconds: 300
# External IdP issuer URL; its `/.well-known/openid-configuration` must name the same
# issuer. [restart]
# oidc_issuer: ""
# Client id registered at the IdP; also the audience each id_token must carry.
# [restart]
# oidc_client_id: ""
# Origin used for server-side sign-in calls to the issuer, preserving its Host header.
# Empty uses the issuer directly; browser redirects and bot-trust key fetches are
# unchanged. [restart]
# oidc_backchannel_base_url: ""
# JIT provisioning: a first OIDC sign-in with no account creates a personal namespace
# in oidc_jit_org instead of being rejected. Off = fail closed. oidc_jit_email_domains
# (comma-separated) restricts it; empty admits any verified email the IdP
# authenticates. [restart]
# oidc_jit_provision: false
# Org that JIT-provisioned accounts are created in; required when `oidc_jit_provision`
# is on. [restart]
# oidc_jit_org: ""
# Comma-separated email domains JIT provisioning admits; empty admits any verified
# email. [restart]
# oidc_jit_email_domains: ""
# Seconds one call to an identity provider may take: OIDC discovery, the token and
# revocation endpoints, its signing keys, a machine issuer's discovery, and an
# end-user issuer's JWKS fetch. [live]
# identity_provider_timeout_s: 10.0
# Seconds between re-reads of loom.signing_keys in every process (at least 1); `loom
# signing-key rotate` waits out two of the slowest process's. [restart]
# jwt_keyring_refresh_seconds: 30.0
# This cell's name (1 to 32 of a-z, 0-9, '-') behind a router, "" = not a cell; set,
# the process serves only while its cell's rows accept it
# (docs/architecture/cells.md). [restart]
# cell: ""
# The port of the probe listener, which answers the deployment id and the values under
# `loom cell prepare`'s nonce keys (docs/architecture/cells.md); 0 = off. [restart]
# cell_probe_port: 0
# The router's base URL a cell calls to place a new org, and the `loom cell` commands'
# default router; "" = none: in `enforced`, a new org answers 503. With LOOM_CELL set,
# a value other than an http(s) URL with a host, a port at most 65535 and no '?' or
# '#' refuses the boot. [restart]
# cell_router_url: ""
# Seconds a whole call to the router may take: a placement call, after which the
# request answers 503, and a cell's state read, which is also the margin past its read
# period before that read's answer counts as late. [restart]
# cell_router_timeout_s: 5.0
# Seconds (at least 1) between reads of the cell state rows once the first read landed
# (every second until then), in every process that reads them under the Postgres
# authority, and before an org read as not held is read again; also the most a first
# cell's server process waits between reads of the router's state route (with
# LOOM_INSTANCE_HEARTBEAT_SECONDS) and the window of a process that reads it on
# demand. LOOM_JWT_REVOCATION_MAX_STALE_SECONDS must be at least three times this.
# [restart]
# tenancy_mode_cache_s: 5.0
# Placement calls one cell may make in a minute, counted by each router replica.
# [restart]
# router_placements_per_minute: 60
# Seconds (at least 1) a router replica keeps the cells' credential hashes, a placed
# org's lookup answer and the first cell's state-route answer before reading again; a
# new credential or host works within this. A cell's processes carry the router's
# value: 401s from the state route last this long before the heartbeat's `router`
# turns false. [restart]
# router_directory_cache_s: 5.0
# Org lookups one client address may make in a minute, counted by each router replica
# (`GET /cells/lookup`). [restart]
# router_lookups_per_minute: 60
# The deployment's shared host (`loom.example.com`) the router serves by rules 2 to 4,
# beside the first cell's own host and aliases; "" = no cell registers (registration
# tells the first cell by this host), and once one has, only its own host and aliases.
# [restart]
# router_shared_host: ""
# Where the router forwards the shared host until a first cell registers, which copies
# it into its row; "" = 503 there and no first cell registers. [restart]
# router_upstream_url: ""
# The probe listener address of the deployment behind the shared host, at which the
# first cell's registration is checked; "" = no first cell can be registered.
# [restart]
# router_upstream_probe_url: ""
# SHA-256 (64 lowercase hex) of the router's operator credential, which `loom cell
# limit`, `loom cell credential` and `loom cell prepare` call its operator API with;
# "" = that API refuses. [restart]
# router_operator_sha256: ""
# The `iss` Loom stamps on every token it mints; a verified token carries it or one of
# `jwt_trusted_issuers`. [restart]
# jwt_issuer: "loom"
# The `aud` claim stamped on minted tokens and required on every verified token.
# [restart]
# jwt_audience: "loom-platform"
# Extra accepted `iss` values, for a gateway minting Loom-shaped JWTs with a key in
# `jwt_public_keys_json`. Loom's own tokens (iss = jwt_issuer) pass. [restart]
# jwt_trusted_issuers: ""
# Clock-skew tolerance on iat/exp, seconds; small enough to give replay no useful
# post-exp window. [restart]
# jwt_leeway_seconds: 30
# Seconds the `loom.revoked_tokens` snapshot is cached; verify checks both jti and sub
# against it, so a revocation takes effect on other processes within this TTL (at once
# on the one that wrote it). [restart]
# jwt_revocation_cache_ttl_seconds: 30.0
# Oldest revocation snapshot a process still trusts, seconds. Past it (refreshes keep
# failing) every bearer is refused with a retryable 503. A subject's cached grants are
# trusted as long when a re-read fails. [restart]
# jwt_revocation_max_stale_seconds: 600.0
# Seconds a subject's grant rows are cached for the namespace gate, which caps a
# token's claim at the grant it holds there. The backstop: a grant change reaches
# other processes through the per-org grant watermark (acl_watermark_poll_seconds),
# and this bounds one whose watermark row was never written. SCIM and bot final
# decisions use this TTL from read start. A complete enforced-cell SCIM check has a
# separate 30-second ceiling, so its cross-process observation bound is the larger of
# this TTL and that check's budget; a smaller positive read timeout reduces the
# latter. [restart]
# grant_cache_ttl_seconds: 10.0
# Seconds between each process's reads of the per-org grant watermark
# (loom.acl_versions): a revoke on one replica is enforced on every other within about
# this long. [restart]
# acl_watermark_poll_seconds: 1.0
# Oldest grant watermark a process still trusts, seconds. Past it (polls keep failing)
# cached grants are not served and every request reads its own. [restart]
# acl_watermark_max_stale_seconds: 10.0
# Sign-ins, sign-ups and workload-token exchanges one process counts at once (each
# costs ClickHouse statements, a sign-in a password hash); past it a caller waits up
# to a second, then gets 429 (an exchange 503), so a burst cannot take the shared
# connection pool. [restart]
# auth_attempts_concurrency: 8
# Workload-token exchanges (RFC 8693) one trust may make in 10 minutes,
# deployment-wide; past it /oauth/token answers 429 until older ones age out.
# [restart]
# workload_exchanges_per_trust: 50000
# Workload-token exchanges one agent of a trust (a token with an agent claim) may make
# in 10 minutes, so one agent's loop cannot spend the trust's. A trust without agents
# has only `workload_exchanges_per_trust`. [restart]
# workload_exchanges_per_agent: 300
# Browser self-signup: "off" (endpoint 404s) or "open" (/v1/auth/self-signup mints
# JWTs scoped to the requested namespace). A non-loopback bind refuses "open" unless
# identity_provider is "trust-network", allow_insecure is set, or oauth_login_provider
# is "oidc" (which closes sign-up). [restart]
# self_signup: "off"
# Default org for self-signed tokens. [restart]
# self_signup_org: "dev"
# How callers authenticate: "single-user" (no auth, one anonymous identity),
# "trust-network" (self-signup, first claim wins) or "gateway" (an upstream proxy
# mints short-lived Loom JWTs with the shared HS256 secret; Loom only validates).
# Empty = inferred from auth_required and self_signup at boot. [restart]
# identity_provider: ""
# When set, a dashboard page load redirects (302) here instead of serving the SPA
# (Loom behind an aggregator). Deployment-specific; never hardcode. [restart]
# dashboard_redirect_url: ""
# Comma-separated subjects allowed to send `X-Loom-On-Behalf-Of` (a trusted aggregator
# passing each end-user's identity under one service token). Empty disables the
# header. [restart]
# trusted_callers: ""
# The services that sign a short-lived token per end user (a chat app in front of
# Loom): JSON (or base64 JSON) {issuer: {"orgs": [...], "jwks_url": "https://…",
# "keys": {kid: RS256 public PEM}}}. `orgs` lists the orgs its tokens may name (exact
# names, or `prefix*`); its keys come from `jwks_url` (fetched every
# `jwt_end_user_jwks_refresh_seconds`) and/or `keys`. A key here verifies only its own
# issuer's tokens, and only as an end user (`sub: user:<id>`, one listed `org`, an
# optional `agent: agent:<id>`), never any other token. Empty: no end-user tokens. A
# non-loopback bind refuses an inline RSA key under 2048 bits (a key fetched from
# `jwks_url` is not checked). [restart]
# jwt_end_user_issuers_json: ""
# The longest an end-user token may live, from its `iat` to its `exp`. [restart]
# jwt_end_user_max_ttl_seconds: 300
# Seconds between fetches of each end-user issuer's `jwks_url`; a key it rotates in is
# honoured from the next fetch. [restart]
# jwt_end_user_jwks_refresh_seconds: 300.0
# Kill switch for restricted namespaces. True: served to a principal whose token names
# the namespace AND who holds a live direct grant. False: every read is refused while
# ingest continues. [restart]
# restricted_serve: true
# Wait for the `namespace.restricted_access` audit row of each admitted restricted
# read before answering; false writes it beside the answer, lost if the process dies
# first. [restart]
# restricted_audit_inline: true
# Comma-separated origin list. "*" allows all (acceptable when auth_required=True).
# Empty disables CORS entirely. [restart]
# cors_origins: ""
# Request-body cap, bytes, enforced by ASGI middleware before any parser (413
# PAYLOAD_TOO_LARGE); uvicorn has no limit of its own. 0 disables. [restart]
# max_request_bytes: 33554432
# Strict-Transport-Security max-age, seconds; browsers ignore it over plain HTTP. 0
# sends no header. [restart]
# hsts_max_age_seconds: 31536000
# History policy over the agent trace: "off" reads/writes nothing; "shadow" records
# verdicts in loom.policy_decisions without blocking; "enforce" denies (403
# POLICY_FORBIDDEN) and records them too. In enforce, writes fail closed on evaluation
# errors; reads never do. [restart]
# policy_mode: "off"
# Cap on any rule's look-back window, in seconds. [restart]
# policy_max_window_seconds: 86400
# Per-(org, namespace) rule cache TTL, seconds; other replicas see a rule change
# within it. [restart]
# policy_cache_ttl_seconds: 30
# --- timeouts, budgets and caches ---
# Seconds a machine issuer's discovery document (its JWKS URL) is cached. [live]
# auth_machine_discovery_ttl_s: 3600
# Seconds the identity provider's OpenID configuration is cached. [live]
# auth_oidc_discovery_ttl_s: 3600.0
# ===== The assistant: LibreChat run headless beside Loom, and the agent Loom seeds in it =====
# LibreChat's internal address (http://librechat:3080), reachable only from Loom. "" =
# no assistant: no service setup at boot, and the panel's chat is off; its starters
# still read. [restart]
# assistant_librechat_url: ""
# Email of the LibreChat service user that owns the agent, read once, when the first
# boot writes loom.assistant_service; LibreChat sends it no mail. [restart]
# assistant_service_email: "loom-assistant@loom.invalid"
# Seconds before a failed assistant setup is tried again; each next failure doubles
# the wait, up to 16 times as long (docs/architecture/assistant.md#deployment).
# [restart]
# assistant_setup_retry_s: 60.0
# Seconds one assistant answer may run, and how long its delegated token lives.
# [restart]
# assistant_answer_ttl_s: 600
# The share of a namespace's daily model cost cap the assistant may spend, so
# questions cannot spend what extraction and the conflict resolver need. [restart]
# assistant_budget_share: 0.5
# Answers one web process runs at once per namespace (a replica runs its web workers'
# count times this); bounds how far answers that each passed the cap check can
# overshoot it. [restart]
# assistant_concurrent_answers: 2
# USD charged for an answer cut before LibreChat reported its usage (a disconnect, a
# timeout) or on a model with no price; 0 charges nothing. [restart]
# assistant_answer_ceiling_usd: 0.1
# ===== The code plane: ingest, indexes, search, ask, review =====
# --- switch, test gate and code.ask ---
# Master kill switch, checked at the top of every code.* handler but the retirement
# (code.repo.remove), which only deletes. [restart]
# code_intel_enabled: true
# code.test_gate run recipes (LOOM_CODE_TEST_GATE_RUN_TEMPLATES): JSON list of
# {"pattern": <regex over the repo-relative test path>, "run": <template>}, tried
# before the built-ins. Templates may use {path} {dir} {stem} {name} {parent}. A path
# no recipe matches is reported run_unknown, never guessed. [restart]
# code_test_gate_run_templates: ""
# Retrieval context (tokens) code.ask hands to synthesis when the caller passes no
# token_budget. [restart]
# code_ask_token_budget: 4000
# The code.ask answer cache's hit cosine. 0 = the per-embedding-model table in
# code/app/answers_entry.py; a value in (0, 1] pins one threshold for every model.
# [restart]
# code_ask_cache_threshold: 0.0
# A cached code.ask answer older than this many days is a miss (checked and tombstoned
# at read time; no table TTL). 0 = no bound. [restart]
# code_ask_cache_max_age_days: 14
# Seconds an abstain stays cached for its exact normalised question under the index
# head it abstained at. 0 = off. [restart]
# code_ask_negative_cache_ttl_s: 3600