---
id: settings/a-user-s-settings-should-export-and-import-as
title: "A user's settings should export and import as a plain file"
theme: settings
status: open
created: 2026-08-22
date_source: stated
order: 1
---

**A user's settings should export and import as a plain file** — and possibly be read and written from
one instead of from the database at all. Wanted 2026-08-22. Two goals, both stated by the owner: carry a
configuration onto another instance without redoing it by hand, and let an **agent** work on it, which a
file allows and a jsonb column does not.

**Explicitly NOT the screen workspace layouts.** Those are per-machine furniture; they are not what
travels.

**It is closer than it looks, because the data is already a document.** `user_settings` is one row per
user holding a single `settings` jsonb, and `server_config` is key/value jsonb — no per-setting columns
to serialise, and nothing to invent a format for. What needs deciding is what is *in* the export, and the
neighbours are the reason it needs deciding at all:

- `dashboards` and the `ws-layout-*` keys — the layouts, excluded by the owner.
- `user_state` — a second jsonb beside settings, but state rather than preference. Almost certainly out.
- `dock_configs` — a preference, and portable. Probably in.
- `user_integrations` / `server_integrations` — **the hard one, below.**

**Credentials are the part that cannot be waved through.** Integration rows hold tokens, encrypted at
rest by `crypto.ts` under a per-purpose key that lives in this install's secret store. So an export has
exactly three options, and each is a real decision: carry ciphertext (which will not decrypt anywhere
else, making the import silently useless), carry plaintext (a settings file with live tokens in it, on
disk and probably in git), or **carry the shape and leave the secret to be re-entered** — which is the
only one that is both portable and safe, and it should be the default.

If it goes as far as "read and write from a file instead of the database", note what the database is
giving today that a file is not: one writer, atomic updates, and a per-user row that cannot be confused
with another's. None of those are hard to keep, but a file per user in a known directory has to say how
it handles two writers — and this platform now runs several agents in one checkout, so that is not
hypothetical.