Data and Storage¶
rettui keeps its data in ~/.local/share/rettui/:
identity: the private key behind your address, in the format every Reticulum program uses (Python's raw 64-byte key). Lose it and the address is gone for good, so keep a copy:bin the Status tab saves one where you choose, readable only by you. Whoever has it can pose as you and read what's sent to you, so keep copies private.Bbacks up everything else with it (see Backups below). To keep the address you have in Sideband, NomadNet, MeshChat or another rettui,iin the Status tab (or the getting-started guide) uses that program's identity file from the next start; the one it replaces is kept beside it asidentity.previous-<date>. Everything that takes its address from the identity changes with it: a node or propagation node you host, and who you are to RRC hubs (the question before switching says which apply). Don't run one identity in two programs at once: messages to it would be split between them. The web UI can't read or change the identity (the login link would otherwise give away the key). Stop the web UI first (two copies of rettui on one data folder overwrite each other's files), then use the terminal UI, or copy the file overidentity(for Docker,./data/identity, with the container stopped).settings.json: display name, announce behaviour, home page, propagation node, sync interval,messages_keptandmessage_storage_mb(see Message history below),cache_hours(24 by default), node and propagation node hosting, what incoming messages must bring (stamp cost, size),wrap_linesand the Reticulum config directory. Edit it in the Status tab of either UI (or by hand). Changes apply straight away, except the Reticulum config and "announce at start", which are used the next time rettui starts.store.json.gz: conversations, contacts (your names for people, notes, who you trust or blocked), saved pages, RRC hubs, nodes you identify to, the emoji you used lately, and where people have been (their trails on the map), as gzip-compressed JSON (read it withzcat store.json.gz | jq). Earlier versions kept it as plainstore.json, about five times larger. The first launch after upgrading converts it, checks that the new file reads back the same, and only then removes the old one. Changes are saved every 10 seconds on a background thread, so a large store doesn't pause the UI, and once more when rettui exits. If it can't be read when rettui starts, rettui starts without your messages and moves the file aside asstore-unreadable-<time>.json.gz, rather than saving over it, and the log says so.- Reticulum's own storage (in the Reticulum config folder): from rsReticulum 1.5, the destinations known, their ratchets and the announces cached are SQLite files, the ones Python Reticulum 1.6 uses. The first start imports the old files. This is one-way: an older rettui starts with no known destinations and hears them again as they announce.
rettui.db: the LXMF peers, NomadNet nodes and propagation nodes heard, and the public keys they announced, so you can reach peers that are offline now. It's an SQLite database (open it withsqlite3 rettui.db), with the filesrettui.db-walandrettui.db-shmbeside it while rettui runs. Announces arrive several a second on a busy network, so only what changed is written: the peers once a minute (every 5 minutes when no browser has the web UI open, as on a phone with its screen off), the keys about once a minute, and both when rettui exits. A peer not heard from in 30 days is forgotten with its key, unless you have a conversation with it, it's a contact, a saved page or hub is on it, or it's your propagation node.
Versions before 2.0 kept these in peers.json.gz and
known_identities.json, rewriting them whole every few seconds, which on
a phone cost far more battery and storage. The first launch of 2.0 moves
them into rettui.db, renames them peers.json.gz.migrated and
known_identities.json.migrated, and says so on the Status tab. Versions
before 2.0 can't read rettui.db: if you go back to one, it hears peers
and their keys again as they announce. A rettui.db made by a newer
version of rettui isn't opened at all, so it isn't damaged; the Status tab
says so, and peers heard meanwhile aren't kept.
- archive/: older messages (see Message history below), one file per
month, such as archive/2026-09.jsonl.gz: one message per line, with the
conversation it's from. Read it with zcat archive/*.jsonl.gz | jq.
- tickets.json: stamp tickets you gave
trusted contacts and ones they gave you. Only you can read it.
- games.json: your games with contacts, as LRGP keeps them (the
board, whose turn it is, the moves). Saved as moves are made.
- reticulum-history/: earlier versions of the Reticulum config, as rettui
saved them (History), the newest 50 of
each config file: one .config file each, listed in index.json. Not in
backups: the config they're of is this computer's.
- interface-profiles.json: interface profiles,
named sets of interfaces on and off to switch between. Shared by every
identity, and not in backups, as the history isn't.
- rrc-hub/ and rrc-hub-identity: the RRC hub hosted
here, once it has started: rsRRCD's
config.yaml, its registered rooms (rooms.yaml), and the hub's own
identity.
- ratchets/: your address's ratchets, one file per address, named as
Python LXMF names them. As in Sideband, NomadNet and MeshChat, your
announces carry the newest of a set of keys (a new one at most every
half hour, as you announce), and senders who heard it encrypt to it: a
message can't be read later with your identity's key alone (forward
secrecy). The last 512 are kept, for messages still on their way, such
as ones waiting on a propagation node. Deleting the folder makes new
ones, but messages sent to the old keys can't be read any more. It
needn't be backed up.
- cache/: cached NomadNet pages and images
- rrc/: RRC chat history, one file per hub (the newest messages of each room and whisper conversation, 500 unless "Chat messages kept", rrc_messages_kept, says otherwise)
- rettui.log: logging, as detailed as Log level says (Status, log_level: error, warn by default, info, debug or trace; it changes at once). RETTUI_LOG=debug, set when rettui starts, decides instead
- downloads/: received attachments (one folder per sender) and NomadNet files (those go in NomadNet files folder, Browsing settings, nomad_files_dir, instead, if you set one: a USB drive or your Documents folder, say; set in the terminal UI or settings.json, not the web UI)
- received/: files sent to you with rncp, unless Received files folder (rncp_dir) says another
- repos/: copies of rngit repositories, by
node, group and name; deleting one is harmless (copy it again)
- uploads/: files attached to messages sent from the web UI, and the
smaller copies of pictures sent (see
Messaging)
- update-check.json: what the last update check
found, and when
- map-tiles/: pictures for the web UI's map,
kept a month (200 MB at most); deleting it is harmless
- node/: your node's pages/ (with pictures added in the editor in pages/images/) and files/
- propagation/: messages your propagation node
keeps for others, one file each, encrypted for their recipients
- web_token: the web UI's login secret (delete it to log every browser out)
- web-tls/: rettui's own HTTPS certificates, with --https (see
Web UI): its certificate authority (ca.pem, and its key
ca.key) and the certificate it signed for this computer (cert.pem,
cert.key). Delete the folder for a new authority, which devices then
install again.
- web_push_key: the web UI's key for background notifications (Web Push),
and web_push.json: the browsers that turned them on. Deleting the key
makes browsers subscribe again the next time they open rettui.
- identities/: the other identities kept here, a
folder each, and active, which says which is in use.
Several identities¶
rettui can keep several identities and use one at a time, as Columba and MeshChat can. Each is an LXMF address of its own, with its own name, conversations, contacts, games, settings and ratchets, so switching is being someone else: a work address and a personal one, say, or one for a group.
I in the Status tab lists them (the web UI: 👤 Identities, beside the
display name), the one in use marked:
- New (
n, + New identity): a new key and address, with the name it announces. It starts with the settings of the one in use, but nothing hosted (node, propagation node, hub), shared (location) or drawn (icon) of it; the keys of others heard so far come along, so it can write to them at once. - From a file (
i, terminal only): keep the identity in a file from Sideband, NomadNet, MeshChat or another rettui as another one, rather than in place of the one in use (iin the Status tab does that). - Switch (
Enter, Switch): everything is saved, then rettui starts over as that identity: its settings, conversations and network (it announces as it). The web UI comes back at the same address, with the same login, and loads again by itself. rettui starts as the identity used last. - Rename (
r), QR code (c) of itslxma://link, to be added as a contact, and copy that link (y). - Delete (
x, terminal only): an identity, with its key, conversations and contacts, once its name is typed. Not the first (it's the data directory's own) nor the one in use. Back it up first (switch to it,b) if its address may be wanted again.
The first identity is kept where it always was, in the data directory
itself; each one added is a folder in identities/ (named by the start of
its LXMF address) laid out as the data directory is, with its own
identity, settings.json, store.json.gz and the rest. What isn't about
who you are is the data directory's, whichever identity is in use: the
log, the web UI's login, certificates and browsers, the update check, the
page cache, map pictures and the Reticulum config's history. A
backup is of the identity in use.
The web UI can't bring an identity in from a file, copy one or delete one:
its login would otherwise give the keys away. rettui identity export FILE
and rettui identity import FILE --name NAME do the first two from the
command line, and the Android app has a screen of its own for them.
Backups¶
A backup is one .tar.gz file holding what's yours to keep:
settings.json, the store (conversations, contacts, saved pages, RRC
hubs), rettui.db (peers and their keys, copied whole even while rettui
is saving to it), the archive/ of older messages, tickets.json, your games (games.json), RRC history (rrc/), your node's
pages and files (node/), your hub's settings and rooms (rrc-hub/) and,
unless left out, the identity (and the hub's, rrc-hub-identity). Caches,
the log, ratchets, copies of repositories (repos/), the propagation node's messages and the web UI's login,
certificates and push keys aren't kept: rettui makes them again.
Attachments (downloads/, uploads/) are left out unless asked for.
- Terminal UI:
Bin the Status tab asks where to save it (your home folder,rettui-backup-<date>.tar.gz, to begin with), then for a passphrase to seal it with (typed twice, shown as dots;Enterfor none), with your identity, once what's waiting to be saved is written. The log says when it's done. - Web UI: Download a backup (Status, Backup), with a passphrase if
you type one. It never has the identity (the login link would otherwise
give away the key): back that up in the terminal UI, or with
rettui backup. In the Android app, Identity and backups saves one with the identity, and can make them on a schedule. - Command line:
rettui backup [FILE](by defaultrettui-backup-<date>.tar.gzhere);--with-filesadds attachments,--without-identityleaves the identity out. In a terminal it asks for a passphrase (Enterfor none);--passphraseneeds one,--no-passphrasedoesn't ask, andRETTUI_BACKUP_PASSPHRASEgives one without asking, for scripts. It reads what's saved, so with rettui running it's what was saved last (every 10 seconds).
A backup with the identity is as private as the identity itself: the file is made readable only by you, and whoever has it can pose as you and read what's sent to you. rettui never writes over a file that's there already.
Sealed with a passphrase¶
A backup sealed with a passphrase can't be read, or restored, without it: a copy that lands somewhere it shouldn't (a cloud folder, a lost USB stick) gives nothing away. Don't lose the passphrase: nothing gets the backup back without it. Use a few words rather than a short PIN: a backup can be guessed at on another computer, as fast as it can go, with nothing to stop it after a few tries.
The passphrase is stretched with Argon2id (64 MB, 3 passes, a fresh salt each time), which makes each guess slow, into a key pair. The backup is encrypted to its public half with X25519 and AES-256-GCM, in 64 KB chunks that can't be changed, reordered or cut short unnoticed. A short passphrase, or a PIN, gets a warning. Sealed Backups says how it all works, and what it protects against.
rettui unseal FILE OUT opens a sealed backup without restoring it (and
without rettui running): the plain backup to OUT, or with
--identity FILE only the identity, to use in Sideband, NomadNet or
another rettui. tools/unseal_backup.py in rettui's repository does the
same with Python, without rettui at all. See
Sealed Backups.
rettui backup-key turns a passphrase into a backup key
(rettui-backup-key-1:…), the public half: rettui backup --key KEY seals
a backup with it, without the passphrase, so a script (or the Android app's
scheduled backups) can make sealed backups knowing only the key, which
can't open them. Restoring one still takes the passphrase.
To restore, stop rettui, then rettui restore FILE (the desktop app restores from its window, and stops and starts rettui itself) (with --data-dir DIR
for another data directory). A sealed backup asks for its passphrase (or
takes RETTUI_BACKUP_PASSPHRASE). Into a data directory that's empty, or new,
it just unpacks. One that has an identity or messages already is left
alone, unless --force: then what the backup replaces is first moved into
a before-restore-<time>/ folder there. A restored backup without an
identity gets a new one on the next start, with new addresses: restore
yours too (i in the Status tab, or copy it over identity) to keep
them. Restoring takes only rettui's own files from the backup, and never
writes outside the data directory.
A backup can come from anyone, so a restore leaves out the settings that
decide which programs run on this computer, and says which: the voice
recorder and print commands, page scripts, rncp, another Reticulum config
or node folder, and the like (the ones the web UI may not change either).
They keep what the data directory had, or their defaults. A backup you made
yourself can bring them back as written with
rettui restore FILE --keep-terminal-settings; the web UI, the desktop app
and the Android app can't. A settings file in a backup that rettui can't
read is left out, and rettui starts with its defaults.
Message history¶
- Messages kept (
messages_kept, 1000 by default): each conversation keeps and shows its newest this many messages. Older ones move toarchive/rather than being deleted, so the store rettui loads and saves stays small.0keeps every message in the store. The first launch after upgrading archives what's over it, and says so in the log. - Reading the archive: a conversation's archived messages open from
the conversation, only to read (they can't be replied to or deleted one
by one). In the TUI, press
Hin Messages: they open over the tab, the newest at the bottom;↑↓,PgUp/PgDnand the mouse wheel scroll, andHomegoes to the oldest. In the web UI, scroll to the top of the conversation and press Show N archived messages: they go in above, with their files and pictures. Searching looks through the messages kept, not the archive. - Message storage (
message_storage_mb, no limit by default): the most disk, in megabytes, that the store and the archive may use together. Past it, the oldest months of the archive are deleted, oldest first. If the messages kept alone take more, the log says so: lower Messages kept. Attachments (downloads/,uploads/) aren't counted. - Received files limit (
downloads_quota_mb, 2000 by default): the most disk, in megabytes, thatdownloads/may use. A file that came with a message and would take it over isn't saved: the message is kept, and the log and a notice say which file wasn't. Nothing is deleted to make room. 0 is no limit. Each received file counts for at least 4 KB, so a flood of tiny files can't fill the folder either. - People who aren't contacts: rettui keeps at most 500 of their conversations and 32 MB of their messages, and a message may carry at most 32 of their reactions. Past that, their oldest conversations are deleted, and rettui says so (in the footer, or as a notice in the web UI), once for each clean-up. Contacts are never cleaned up. Tickets other people give you are kept for 26 days at most, and for 4,096 senders at most.
- Both settings apply straight away, from the Status tab of either UI.