The stores.toml reference

~/.loom/stores.toml is the one file that tells Loom which stores you can reach and which one to use by default; this page lists every key it understands.

On Windows the file is %USERPROFILE%\.loom\stores.toml. loom setup and loom login write it for you, so most people never edit it by hand.

What the file looks like#

After a hosted sign-up the file looks like this (values shortened):

default = "coding"

[coding]
endpoint = "tcp://loomcloud.ai:7443"
store = "<org>_coding"
namespace_scheme = "loom-8"
server_key = "<server public key>"
store_key = "<your store credential>"
description = "<what this store holds>"
web_origin = "https://loomcloud.ai"

[kanban]
endpoint = "tcp://loomcloud.ai:7443"
store = "<org>_kanban"
namespace_scheme = "loom-8"
server_key = "<server public key>"
store_key = "<your store credential>"
description = "Kanban store for multi-agent coordination."
web_origin = "https://loomcloud.ai"

There are three kinds of top-level entry:

default, a string naming the store section to use when nothing more specific applies. It is mandatory: without it loom list_stores fails with an error that says it must set top-level default = "<store>", and if it names a section that does not exist the error reads loom store '<name>' not in <path to stores.toml>. Available stores: ....
Store sections, one [name] table per store.
[workspace] tables, which map your projects to stores (see Choosing a store per workspace).

Store section keys#

These are the keys Loom reads from a store section. Unknown keys are ignored.

Key	Required	Meaning
`endpoint`	yes	Where to connect, for example `tcp://loomcloud.ai:7443`. A section without it is not a store.
`store`	yes	The store's name on the server. `user` is a deprecated alias; if both are present, `store` wins. A section with only `endpoint` is still listed by `loom list_stores`, but cannot be used until `store` (or `user`) is set.
`server_key`	yes for hosted	The server's public connection key. Not secret.
`store_key`	yes for hosted	Your credential for this store. Secret. Its presence switches the client to gateway mode.
`namespace_scheme`	written by setup	Namespace layout of the store, for example `loom-8`. Leave as written.
`description`	no	One line saying what the store holds. `loom list_stores` shows it so an agent can pick the right store.
`fastembed_model`	no	Embedding model name. Only the default store's value is read for client-side tuning.
`curve_public_key`	direct connections only	Your own public connection key, for a server you connect to directly without the gateway.
`curve_secret_key`	direct connections only	Your own secret connection key. Also readable from the `LOOM_CURVE_SECRET_KEY` environment variable (see Environment variables).
`socks_proxy`	no	A SOCKS proxy to connect through.
`web_origin`	written by setup	The web server that issued this store. Store-management commands talk to this origin: `unlock_store`, `set_store_domain` and `drop_store` for the section they act on, and `create_store` when this is the section it authenticates with (`auth_store`, default the first section). `loom setup` with no `--base` also uses it when this is the only store section in the file (and, when that section has a `store_key`, skips the sign-in). A section with no `web_origin` is treated as `https://loomcloud.ai`. A value that is not a valid server address is refused with `stores.toml section '<name>' has an invalid web_origin`.

The default store#

The top-level default key names the section Loom uses when you do not name a store. Setup adds default only if the file has none, and it never changes an existing one.

Inside a session, loading a store with set_default true changes the default for that session only. It never rewrites stores.toml. From the command line:

loom load_store --params '{"name":"<store>","set_default":true}'
loom current_default_store

current_default_store returns {"session_default": ..., "is_override": false}. Each loom command line is its own session, so run as two separate commands the second one still reports the default from stores.toml; the override shows in the session_default field of the load_store result and lasts only inside a long-lived agent session. With no default configured it does not fail, it reports the placeholder name default.

Choosing a store per workspace#

A workspace is a product or team grouping that can span several repositories. Your coding agent reads the repository's loom-scope: line to learn the workspace name, then looks up which store holds that workspace's memory:

[workspace]
loom-coding = "coding"

[workspace.atlas]
loom-coding = "atlas-memory"

Lookup order for the coding skill:

[workspace.<name>] with the key loom-coding, for this repository's workspace.
The bare [workspace] table's loom-coding.
If neither exists, the agent asks you which store to use and writes the answer back.

The same pattern holds for other roles: loom-kanban names the store the Kanban skill uses for the board. See Set up a Kanban board.

Merging. Setup and login merge new sections by name. They never rebind an existing section to a different store; they refuse and say so, and that includes an incoming section with no store line when the existing one is bound to a store. If the server lists two sections with the same name, the first (oldest) is kept and the other is skipped with a warning on stderr: Warning: store <handle> was not configured locally: its section name [<name>] is already used by another of your stores and it needs a distinct alias.
Existing credentials. loom setup leaves the file alone when it already holds a section with a store_key for the server setup resolved (v0.674 or later): it skips the sign-in, so nothing is merged. A section counts for the server in its web_origin, or for https://loomcloud.ai when it has none. loom login always signs in and merges.
Backfill. Older sections without web_origin get one added.
Atomic writes. The file is replaced in one step, so an interrupted run does not leave half a file.
Logout. loom logout removes one section from this machine. It is local only; see Manage stores. It finds the section by its parsed name, so a quoted, spaced or commented header such as [ "kanban" ] or [kanban] # board is removed too (v0.674 or later; earlier releases matched only the exact text [kanban]).
Drop. loom drop_store destroys the store on the server and removes the section.

Editing by hand#

Hand edits are safe if you follow these rules:

Make a backup first: cp ~/.loom/stores.toml ~/.loom/stores.toml.bak.
Keep valid TOML. A malformed file makes Loom print a warning (repeated several times per command) and treat the file as empty: loom list_stores then fails with the same must set top-level default error (exit status 2), and no store or default is usable until you fix the file.
Do not copy another person's file. Credentials are per user.
Re-check with loom list_stores after editing.

Check which stores Loom sees:

loom list_stores

The result lists default, available, loaded, session_default, and a descriptions map taken from each section's description. available always begins with a built-in default placeholder entry that is not a section in your file; the stores you configured follow it. The top-level default value in the result is that placeholder too: your configured default appears as session_default.