kbox documentation

Getting started

Create an account with a username, an account password (used to sign in), and a master password. The master password deterministically derives your encryption keys and is never stored or sent — memorise it. A random user keypair is also generated; an encrypted copy is kept on the server so a new device can recover it from your master password.

Sign in, then add your first record with New.

Storing secrets

Records come in four types — Password (username / password / URL / notes), API key (key / URL / notes), SSH key (see below), and Note. Pick a type in the New dialog and the fields adapt. The title and URL are stored in plaintext (for listing/search); everything sensitive is encrypted client-side before saving.

On the vault grid you can copy a username/password straight from a card, open the site, or click View / Edit to see and change a record.

Folders

Use the left sidebar to organise records into folders (and nested sub-folders). Create one with the + in the Library header, choosing a parent. Click a folder to filter the grid to it, or drag a card onto a folder to move it. My Vault shows everything.

Sharing

With another user

From a record's ⋯ menu choose Share…, search for a user, and add them. The record's key is wrapped to that person cryptographically — they see it under Shared with me, and you under Shared by me (both grouped by person). Revoke any time.

Public links

In the Share dialog you can also generate a public link. The data is re-encrypted with a one-off key that lives only in the link (after the #), never on the server. Choose how it expires: one view, a number of views, or a time window. Optionally add a password the recipient must enter (combined with the link key via Argon2id).

Quick share

The Quick share button shares a one-off username / password / note as a link without saving anything to your vault — only a temporary, encrypted link record is created.

CLI

The kbox CLI talks to the same API and decrypts locally. Download a static Linux binary:

chmod +x kbox-linux-amd64 && sudo mv kbox-linux-amd64 /usr/local/bin/kbox

kbox register --server https://kbox.smartlabsys.com   # or: kbox login
kbox list
kbox view github

On a fresh machine, kbox login recovers your key from the master password. Tokens expire and the CLI renews them automatically using your key — no password needed for day-to-day use.

SSH setup

kbox can hold your SSH keys and connection details and feed them to ssh, git and rsync — the private keys are decrypted only in memory, never written to disk.

1. Store an SSH key in the vault

Add a record of type SSH key. Fields:

• Host alias — the name you'll use (ssh <alias>); auto-filled from the title.
• HostName, User, Port — the connection target.
• Private key — paste the unencrypted OpenSSH private key.
• Additional options — any ssh-config directive, e.g. LocalForward 35434 localhost:5432, ServerAliveInterval 60.

2a. One-off connect

Loads the key into your running ssh-agent for a few minutes, connects, then removes it:

kbox ssh db-tunnel            # connect
kbox ssh db-tunnel -- -v      # pass extra flags to ssh
kbox ssh db-tunnel --ttl 60   # key stays in the agent for 60s

2b. Always-on agent (recommended)

kbox agent runs a persistent ssh-agent that serves all your SSH keys from memory, and generates a RAM-backed ssh config (Host blocks with IdentityAgent / IdentitiesOnly / a public IdentityFile) so the connection details come from the vault too.

kbox setup wires everything up for you — it installs a systemd user service and adds one Include line to ~/.ssh/config:

kbox setup
systemctl --user enable --now kbox-agent

ssh db-tunnel        # alias from the vault, key from the agent, no password
git pull             # uses it too

That Include line looks like:

# added by `kbox setup` to ~/.ssh/config
Include /run/user/1000/kbox/conf.d/*.conf

How it coexists with ~/.ssh/config

kbox never rewrites your config — it only adds that one Include line and manages its own files. Your hand-written hosts keep working exactly as before. Because the generated files live in $XDG_RUNTIME_DIR (RAM) and the Include uses a glob, when the agent is not running the files vanish, the glob matches nothing, and ssh simply falls back to your normal config. IdentityAgent also scopes kbox keys to kbox hosts, so your default agent stays in charge of everything else.

Updates & ordering

The agent re-reads the vault periodically (--refresh, default 5 min), so keys you add/remove appear without a restart. Each ssh invocation just needs the agent running at that moment for kbox hosts; enabling the user service means it's always up at login, so you never think about it. Encrypted (passphrase) keys are skipped by the daemon — use kbox ssh for those, or store keys unencrypted.

Check what's loaded:

SSH_AUTH_SOCK=$XDG_RUNTIME_DIR/kbox-agent.sock ssh-add -l