Skip to content

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: b in 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. B backs up everything else with it (see Backups below). To keep the address you have in Sideband, NomadNet, MeshChat or another rettui, i in 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 as identity.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 over identity (for Docker, ./data/identity, with the container stopped).
  • settings.json: display name, announce behaviour, home page, propagation node, sync interval, messages_kept and message_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_lines and 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 with zcat store.json.gz | jq). Earlier versions kept it as plain store.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 as store-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 with sqlite3 rettui.db), with the files rettui.db-wal and rettui.db-shm beside 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 (i in 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 its lxma:// 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: B in 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; Enter for 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 default rettui-backup-<date>.tar.gz here); --with-files adds attachments, --without-identity leaves the identity out. In a terminal it asks for a passphrase (Enter for none); --passphrase needs one, --no-passphrase doesn't ask, and RETTUI_BACKUP_PASSPHRASE gives 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 to archive/ rather than being deleted, so the store rettui loads and saves stays small. 0 keeps 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 H in Messages: they open over the tab, the newest at the bottom; ↑↓, PgUp/PgDn and the mouse wheel scroll, and Home goes 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, that downloads/ 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.