Skip to content

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.

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.

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.

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.

  1. 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.
  2. The host has no swap devices, or only zram.
  3. 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.

  • ./flux backup copies the database and the files volume as they are, so encrypted content stays encrypted, together with docker/.env. The archive’s settings file holds FLUX_KEY_PIN_SECRET and FLUX_KEYRING_TOKEN; the token opens nothing without the running keyring.
  • Keep FLUX_KEY_PIN_SECRET with the settings file, not only with the database. A database restored under a different pin secret refuses every encrypted space as tampered.
  • ./flux restore leaves 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 export refuses 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.

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:

Terminal window
cd /srv/flux
dc() { docker compose --env-file docker/.env -p "$(sed -n 's/^FLUX_PROJECT=//p' docker/.env)" -f docker/compose.source.yaml "$@"; }
dc ps keyring
dc 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.