Operating encrypted spaces
Anyone in the company who is not a guest can make a space encrypted when they create it (the Encrypted switch in the New space window). Its content is then encrypted in the database, in the files volume and in the search index, and its key lives only in memory. After every restart of the server the space is locked until one of the space’s admins enters their unlock password. An encrypted space is always without AI. What it protects, and what it does not, is in encrypted spaces: a copy of the data or a server taken away switched off, not a running server.
This page is what the operator needs to know. Nobody who runs the server can read an encrypted space or unlock it without a password, and nobody can recover one whose passwords and recovery code are all lost.
People make one in the app: New space → the Encrypted switch, which asks for their unlock password and a downloaded recovery code before Create (#976). Each person can create five encrypted spaces in 15 minutes, and at most one password check per person runs at a time, so one account cannot keep the others’ spaces locked.
What runs
Section titled “What runs”| Part | Role |
|---|---|
keyring service |
Holds one random boot key in RAM, never on disk. Runs read-only, as a non-root user, with no capabilities and core dumps off. Exactly one per deployment. |
Internal network keyring |
Joins only api, worker and keyring, and never leaves the host. |
FLUX_KEYRING_TOKEN |
Authenticates api and worker to the keyring. Generated by ./flux. It opens nothing by itself. |
FLUX_KEY_PIN_SECRET |
Pins every unlock password and key version, so key rows planted in the database are refused. Generated by ./flux. Never change it. |
| Memory limits | api, worker and keyring may not swap (memory limit equal to memory plus swap). |
All of these come with ./flux up, which generates the token and the pin secret once when it creates
docker/.env. Left empty, Flux starts healthy
but no encrypted space can be created or unlocked. FLUX_KEYRING=off turns the feature off: every
encrypted space stays locked and none can be created. The variables are in the
configuration reference.
Restarts lock encrypted spaces
Section titled “Restarts lock encrypted spaces”| What restarts | Encrypted spaces |
|---|---|
The keyring, the whole stack (./flux down then ./flux up, ./flux upgrade, docker compose restart) or the host |
Locked. The boot key is gone. |
Only api or worker, including the stop and start around ./flux backup |
Stay unlocked. The process asks the keyring again. |
After a planned restart, tell the admins of encrypted spaces: each space waits until one of them unlocks it in the app. The company’s owners and admins cannot, unless they are also admins of that space. Plain spaces are not affected. Schedule upgrades and host reboots with this in mind.
Swap and memory
Section titled “Swap and memory”If the kernel could write a process’s memory to a swap device, a stolen powered-off server could
hold the key. So Flux enforces it: the keyring refuses to start, and api and worker never
open a key, unless one of these holds.
- The container’s own swap is forbidden by its cgroup. The shipped Compose files do this with the memory limits, wherever the kernel accounts swap.
- The host has no swap devices, or only
zram. - You set
FLUX_SWAP_ACKNOWLEDGED=encrypted-swap, declaring that every swap device is encrypted with a key that is not stored on the disk. Flux cannot detect this; set it only when it is true.
When none holds, the keyring logs Flux keyring refuses to start: this server can write memory to disk…, the API logs Encrypted workspaces stay locked here… at start, and unlocking answers
“This server can write memory to disk. Its operator needs to turn off swap or confirm it is
encrypted.” The check runs again every 5 seconds and drops every key if it starts failing.
Hibernation, suspend-to-disk and VM memory snapshots are not covered by any of this.
Search inside an unlocked encrypted space runs from an index in the API’s memory, bounded to a
quarter of the API container’s memory (64–512 MiB). A space too large for it answers that search is
unavailable. The bounds are override-only settings;
raise FLUX_API_MEMORY before raising them.
Backups, restores and exports
Section titled “Backups, restores and exports”./flux backupcopies the database and the files volume as they are, so encrypted content stays encrypted, together withdocker/.env. The archive’s settings file holdsFLUX_KEY_PIN_SECRETandFLUX_KEYRING_TOKEN; the token opens nothing without the running keyring.- Keep
FLUX_KEY_PIN_SECRETwith the settings file, not only with the database. A database restored under a different pin secret refuses every encrypted space as tampered. ./flux restoreleaves every encrypted space locked. It opens with any of the space’s admins’ unlock password as it was when the backup was taken, or the recovery code valid then../flux exportrefuses an encrypted space, because it would write plaintext to the server’s disk. A space’s admin exports it from the app instead.- A space that says its keys were changed outside Flux can be repaired from a backup; see backup and restore.
Checks
Section titled “Checks”From the checkout, the keyring’s own lines (its health polls of /v1/boot filtered out) say
Flux keyring ready, that it is idle without a token, or why it refuses to start; warnings of the
API are JSON lines with "level":40:
cd /srv/fluxdc() { docker compose --env-file docker/.env -p "$(sed -n 's/^FLUX_PROJECT=//p' docker/.env)" -f docker/compose.source.yaml "$@"; }dc ps keyringdc logs --no-log-prefix keyring | grep -v ' /v1/boot 'dc logs --no-log-prefix api | grep '"level":40'/api/v1/health does not report the keyring or swap state; read these after each start.