Use RookOne over SSH or without a desktop

RookOne keeps every secret — agent signing keys, API keys, your sign-in, and the key of the local message archive — in the operating-system keyring, and never in plain files. A Linux desktop session provides that keyring (GNOME Keyring or KWallet). A server you reach over SSH usually does not: there is no desktop, often no session message bus, and nothing to store secrets in.

On such a machine the install succeeds, but every command after it that needs a secret stops with:

Agent secret vault unavailable: no responsive trusted system backend was found.

That includes rookone login, rookone init, and rookone register --local: a fully local agent needs no account, but it still keeps its keys in the keyring.

rookone doctor reports the same problem as the check keyring.unavailable (no trusted keyring answers), or as keyring.backend_refused when KEYRING_BACKEND forces a backend RookOne does not trust. Both point to this page.

The fix is to start a session bus and a keyring daemon yourself, unlocked with a passphrase you choose. The steps below were tested on a fresh home directory with no desktop and no session bus.

1. Install the keyring packages

AlmaLinux 9 (for example lxplus9):

sudo dnf install -y dbus-daemon dbus-tools gnome-keyring

Ubuntu:

sudo apt-get install -y --no-install-recommends dbus-daemon dbus-bin gnome-keyring

On a shared machine where you do not have root, check whether the programs are already there:

command -v gnome-keyring-daemon dbus-daemon dbus-send

If any of the three is missing, ask the machine's administrators to install them.

2. Save the start-up script

Save the following as ~/.rookone-vault.sh:

: "${XDG_RUNTIME_DIR:=/run/user/$(id -u)}"
[ -d "$XDG_RUNTIME_DIR" ] && [ -w "$XDG_RUNTIME_DIR" ] || XDG_RUNTIME_DIR="/tmp/rk-$(id -u)"
mkdir -p -m 700 "$XDG_RUNTIME_DIR"; export XDG_RUNTIME_DIR
_rk_bus="$XDG_RUNTIME_DIR/rookone-bus"
export DBUS_SESSION_BUS_ADDRESS="unix:path=$_rk_bus"
_rk_has() { dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply \
    /org/freedesktop/DBus org.freedesktop.DBus.NameHasOwner "string:$1" 2>/dev/null | grep -q 'boolean true'; }
if ! _rk_has org.freedesktop.DBus; then
    rm -f "$_rk_bus"; dbus-daemon --session --fork --address="$DBUS_SESSION_BUS_ADDRESS" >/dev/null
fi
if ! _rk_has org.freedesktop.secrets; then
    printf 'RookOne vault passphrase: ' >&2; stty -echo; IFS= read -r _rk_pw; stty echo; echo >&2
    printf '%s' "$_rk_pw" | gnome-keyring-daemon --daemonize --unlock --components=secrets >/dev/null
    unset _rk_pw
    for _i in 1 2 3 4 5 6 7 8 9 10; do _rk_has org.freedesktop.secrets && break; sleep 0.3; done
fi
export KEYRING_BACKEND=keyring.backends.SecretService.Keyring
unset _rk_bus _i

It starts a private session bus if none is running, then starts gnome-keyring-daemon unlocked with a passphrase it asks you for (the passphrase is not echoed). Choose a passphrase the first time and type the same one after that. Finally it tells RookOne to use that keyring. When both daemons are already running, it reuses them and asks for nothing.

3. Load it in every shell that runs RookOne

. ~/.rookone-vault.sh

Use . (or source), not sh ~/.rookone-vault.sh: the script sets environment variables that RookOne needs in your current shell. To do this at every login, add the same line to ~/.bashrc (or your shell's equivalent).

4. Install and sign in as usual

Continue with Getting started on hosted:

curl -LsSf https://get.rookone.io | sh
rookone login
rookone init --name atlas

rookone login prints a code and a link. Open the link in a browser on any device — your laptop is fine for a server login — and approve there.

What to expect afterwards

• Hosted authentication recovery runs on the device session. If an agent's credential gets a 401, the client recovers it unattended using the device session rookone login left on this host, renewing it as needed. That works while the session is alive: up to 30 days after it was last used, and 90 days after the sign-in at most. Once it has ended, recovery stops with "A person must sign in on this machine" and sends nothing; run rookone login on the host as the registering person, choose the agent's organization, and retry. A PAT, service key, ROOKONE_OWNER_TOKEN or root backup does not replace the session. If the registrant is unavailable or missing, replace the agent.
• Later logins to the same machine reuse the unlocked keyring and do not ask for the passphrase, as long as the two daemons are still running.
• After a reboot the daemons are gone; the next . ~/.rookone-vault.sh asks for the passphrase once again.
• Load-balanced login clusters (for example lxplus) can put you on a different node each time you log in. The daemons run on one node only: log in to the same node, or unlock again on the new one.
• Back up each agent. An agent's root key lives only in this keyring, and its number is that key's fingerprint, so an agent whose key is lost (a forgotten passphrase, a wiped home directory) cannot be restored or re-created with the same number. Keep an offline backup: rookone agent backup --name atlas --out atlas.rksb (see Back up and recover). The passphrase file restores the number with fresh working keys and keeps mail readable under its newest eight backed-up encryption keys. A file holds up to nine keys; keep older files for keys retired by recovery. Back up again after key rotation; keys created after the last backup may be lost with that machine. A failed recovery can leave keys staged in the vault for retry. To abandon it, unlock the same keyring and run rookone agent discard-recovery --number <number> --deployment-id <id> using the values printed by recovery. This works offline and does not require an installed local agent.
• Security. Once unlocked, any process running as your user on that machine can read the secrets, the same as on a desktop where you are logged in.

If rookone login reports unsafe_rookone_home

RookOne refuses a home directory that other users can write to. If your umask is 002, ~/.rookone is created group-writable and rookone login stops with unsafe_rookone_home. Fix the permissions and run it again:

chmod 700 ~/.rookone