q-ring 101 - move a vault (qring teleport)

Guia

What it does

qring teleport pack reads the secrets you choose and writes one encrypted bundle to stdout. With a passphrase, the key is derived with PBKDF2-HMAC-SHA512 and the bundle is sealed with AES-256-GCM. On the other machine, qring teleport unpack asks for the same passphrase, decrypts the bundle, and imports the secrets into that machine's keychain. Nothing is decrypted in between.

Try it

# On the old machine: pack two keys (prompts for a passphrase)
qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt

# Move bundle.txt any way you like, then on the new machine:
cat bundle.txt | qring teleport unpack --dry-run   # preview, nothing saved
cat bundle.txt | qring teleport unpack --project

Recent releases add recipient bundles, so nobody has to share a passphrase at all. Each teammate runs qring teleport keygen once and shares the qring1... string it prints, and you address the pack with --to. The private half of that identity stays in their OS keyring.

Why it matters

Setting up a new machine is where secrets leak most casually: pasted into a chat, emailed to yourself, copied over in a plaintext file that never gets deleted. A teleport bundle is ciphertext, so the channel you send it over no longer matters much. Only someone with the passphrase, or the recipient identity, can open it, and the values land straight in the receiving keychain instead of a file.

Gotchas and good to know

• Send the passphrase over a different channel than the bundle. A bundle and its passphrase in the same message is a plaintext file with extra steps.
• Pick a long passphrase. The key derivation slows down guessing, but a short passphrase is still a short passphrase.
• Choose the scope on unpack: --project or --global. unpack asks before overwriting an existing key unless you pass --yes.
• Delete the bundle file once it is unpacked. It stays decryptable for anyone who later learns the passphrase.
• Over MCP, teleport_pack skips approval-protected keys that have no valid approval, so an agent cannot use a bundle to sidestep the approval gate.
• Teleport is the intended way to move secrets between machines. q-ring has no sync service or shared team vault, by design.

Go deeper

• CLI reference
• Getting Started
• Threat model: out of scope