Activate a machine
Activation links the machine to your account, like Claude Code or a smart TV: the machine shows a code, you approve it from a device where you are already signed in. No password is typed on the machine, and the machine never receives the key of your vault.
Before you start
- The Studio plan (or its trial) is active on the account.
- Two-factor authentication (TOTP) or a passkey is turned on in Security: approving a machine always requires a second factor. Without either, the approval is refused with a message asking you to turn one on.
- A device where the vault is open: the Konsolity app (Mac, Windows, Linux, iPhone, iPad, Android) or the web console
app.konsolity.com.
Start the activation
On the machine, with the account that will use the CLI (for a service, the same account as the service):
konsolity login --name build-01
| Option | Role |
|---|---|
--name <name> |
Name shown in the machine list (default: the host name). |
--scopes <list> |
Requested scope, among hosts, snippets, sessions, mcp, separated by commas. |
--read-only |
Requests read-only access (lists and status, no command). |
The requested scope is only a proposal: you set it when you approve. The command shows:
Activating this machine on https://api.konsolity.com
1. Open this address on a device signed in to your account:
https://app.konsolity.com/cli/activate?code=WDJB-MJHT
or in the Konsolity app: Settings › CLI machines › Activate a machine
2. Enter this code: WDJB-MJHT
3. Check that the fingerprint shown is: 7K3Q-9XAD
Waiting for approval...
When the terminal allows it, a QR code of the full link is shown too, handy to approve from a phone. The code stays valid for 15 minutes; the machine waits and does nothing else.
Compare the fingerprint
The fingerprint (7K3Q-9XAD in the example) is computed from the public key the machine just generated. The approval screen computes it again itself from that key, without trusting the server, and shows it with the name, the system, the architecture, the host name and the IP address of the machine.
Only approve if you just ran konsolity login on this machine yourself, and if the fingerprint is the same. A request you do not recognize is refused in one click.
Approve in the app
In Konsolity: Settings › CLI machines › Activate a machine, then enter the code. The vault must be open.
Approve in the browser
Open https://app.konsolity.com/cli/activate (or the full link shown by the machine), sign in, then enter the code. The page asks for your master password to open the vault in the browser: it never leaves the page and is never sent to the server.
Choose the scope and the expiry
Before approving, you choose:
- the scope:
hosts,snippets,sessions,mcp, read-only or full; - the hosts and snippets the machine can use (default: no host);
- the command rules (for full access);
- the expiry of the machine.
Default: hosts and snippets, read-only, no host. The details are in Scope and rules.
| Expiry | Typical use |
|---|---|
| 1 day | One-off intervention |
| 7 days | Short assignment, test server |
| 30 days | Ongoing project |
| 90 days (default) | Administration server |
| 1 year | Long-lived machine, renewed every year |
| Never | Keep for machines you watch closely |
Confirm with the second factor
The Approve button asks for your TOTP code or your passkey (Face ID, Touch ID, Windows Hello, security key). The server checks the second factor in the same request as the approval: a stolen code or a session left open is not enough.
What happens on approval
- Your device draws a random machine key and seals it for the public key of the machine (X25519 exchange). The server only carries an opaque blob it cannot open.
- It copies, encrypted with this machine key, only the hosts, identities, SSH keys, pinned host keys and snippets the scope allows, along with the rules. The rest of the vault does not leave your devices (see Scope and rules).
- The machine receives its token (once), opens the machine key, checks that it decrypts its rules, then stores token and key in its protected storage (see Service and storage).
- You receive an email, an app notification and, if you linked it, a Telegram message "New CLI machine".
The command then shows the name of the machine and the email of the account. Check the status at any time:
konsolity status
One machine per fingerprint
Each machine has a machine fingerprint, computed from the system identifier (/etc/machine-id on Linux, IOPlatformUUID on macOS, MachineGuid on Windows). A new activation on the same machine replaces the previous one: the old entry is revoked automatically. So there are never two active tokens for the same computer.
This fingerprint is sent on every call. A token copied to another computer is refused, and the event raises an alert.
setup-token: CI and containers
A CI runner or a container is often recreated every time: its machine identifier changes, and nothing can be stored durably. For these cases, create a long-lived token:
konsolity setup-token --name ci-deploy
The flow is the same (code, fingerprint, approval with a second factor, scope). At the end, the command shows once a token that starts with ksetup_, and writes nothing to disk:
Long-lived token (shown once):
ksetup_3q2Xk...
Store it in your CI secret manager, then provide it through KONSOLITY_TOKEN.
Store it in your CI secret manager, then provide it to the command through the KONSOLITY_TOKEN environment variable:
KONSOLITY_TOKEN="$KONSOLITY_TOKEN" konsolity run web-01 -- systemctl status nginx
A long-lived token:
- is not bound to the machine fingerprint (it serves on ephemeral machines): protect it like a password;
- must expire, at most 1 year after its creation;
- has no automatic rotation;
- shows in the list as Long-lived token, with the same scope, the same log and the same revocation as a machine.
If it gets stuck
- Code expired: run
konsolity loginagain, a new code is created. - Second factor required: turn on two-factor authentication or a passkey in Security, then start again.
- Subscription required: approval needs the Studio plan (or its trial).
- Refused: the machine stops without saving anything.
- Machine already activated:
konsolity logout, thenkonsolity login.