Attivare una macchina
L'attivazione collega la macchina al tuo account, come Claude Code o una smart TV: la macchina mostra un codice, tu lo approvi da un dispositivo su cui hai già effettuato l'accesso. Nessuna password viene digitata sulla macchina, e la macchina non riceve mai la chiave della tua cassaforte.
Prima di iniziare
- Il piano Studio (o la sua prova) è attivo sull'account.
- L'autenticazione a due fattori (TOTP) o una passkey è attiva in Sicurezza: approvare una macchina richiede sempre un secondo fattore. Senza nessuno dei due, l'approvazione viene rifiutata con un messaggio che ti chiede di attivarne uno.
- Un dispositivo con la cassaforte aperta: l'app Konsolity (Mac, Windows, Linux, iPhone, iPad, Android) o la console web
app.konsolity.com.
Avviare l'attivazione
Sulla macchina, con l'account che userà la CLI (per un servizio, lo stesso account del servizio):
konsolity login --name build-01
| Opzione | Ruolo |
|---|---|
--name <name> |
Nome mostrato nell'elenco delle macchine (predefinito: il nome host). |
--scopes <list> |
Ambito richiesto, tra hosts, snippets, sessions, mcp, separati da virgole. |
--read-only |
Richiede un accesso in sola lettura (elenchi e stato, nessun comando). |
L'ambito richiesto è solo una proposta: sei tu a stabilirlo quando approvi. Il comando mostra:
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...
Quando il terminale lo consente, viene mostrato anche un codice QR del link completo, comodo per approvare da un telefono. Il codice resta valido per 15 minuti; nel frattempo la macchina attende e non fa nient'altro.
Confrontare l'impronta
L'impronta (7K3Q-9XAD nell'esempio) è calcolata dalla chiave pubblica che la macchina ha appena generato. La schermata di approvazione la ricalcola da sé a partire da quella chiave, senza fidarsi del server, e la mostra insieme al nome, al sistema, all'architettura, al nome host e all'indirizzo IP della macchina.
Approva solo se hai appena eseguito tu stesso konsolity login su questa macchina e se l'impronta è la stessa. Una richiesta che non riconosci si rifiuta con un clic.
Approvare nell'app
In Konsolity: Impostazioni › Macchine CLI › Attiva una macchina, poi inserisci il codice. La cassaforte deve essere aperta.
Approvare nel browser
Apri https://app.konsolity.com/cli/activate (o il link completo mostrato dalla macchina), accedi, poi inserisci il codice. La pagina chiede la tua password principale per aprire la cassaforte nel browser: non lascia mai la pagina e non viene mai inviata al server.
Scegliere l'ambito e la scadenza
Prima di approvare, scegli:
- l'ambito:
hosts,snippets,sessions,mcp, sola lettura o accesso completo; - gli host e gli snippet che la macchina può usare (predefinito: nessun host);
- le regole dei comandi (per l'accesso completo);
- la scadenza della macchina.
Predefinito: hosts e snippets, sola lettura, nessun host. I dettagli sono in Ambito e regole.
| Scadenza | Uso tipico |
|---|---|
| 1 giorno | Intervento occasionale |
| 7 giorni | Incarico breve, server di test |
| 30 giorni | Progetto in corso |
| 90 giorni (predefinito) | Server di amministrazione |
| 1 anno | Macchina di lunga durata, rinnovata ogni anno |
| Mai | Da riservare alle macchine che sorvegli da vicino |
Confermare con il secondo fattore
Il pulsante Approva chiede il tuo codice TOTP o la tua passkey (Face ID, Touch ID, Windows Hello, chiave di sicurezza). Il server verifica il secondo fattore nella stessa richiesta dell'approvazione: un codice rubato o una sessione rimasta aperta non bastano.
Cosa succede all'approvazione
- Il tuo dispositivo genera una chiave della macchina casuale e la sigilla per la chiave pubblica della macchina (scambio X25519). Il server trasporta solo un blob opaco che non può aprire.
- Copia, cifrati con questa chiave della macchina, solo gli host, le identità, le chiavi SSH, le chiavi host fissate e gli snippet consentiti dall'ambito, insieme alle regole. Il resto della cassaforte non lascia i tuoi dispositivi (vedi Ambito e regole).
- La macchina riceve il suo token (una sola volta), apre la chiave della macchina, verifica di riuscire a decifrare le sue regole, poi conserva token e chiave nel suo archivio protetto (vedi Servizio e archiviazione).
- Ricevi un'e-mail, una notifica nell'app e, se l'hai collegato, un messaggio Telegram «Nuova macchina CLI».
Il comando mostra poi il nome della macchina e l'e-mail dell'account. Controlla lo stato in qualsiasi momento:
konsolity status
Una macchina per impronta
Ogni macchina ha un'impronta della macchina, calcolata dall'identificativo del sistema (/etc/machine-id su Linux, IOPlatformUUID su macOS, MachineGuid su Windows). Una nuova attivazione sulla stessa macchina sostituisce la precedente: la vecchia voce viene revocata automaticamente. Non ci sono quindi mai due token attivi per lo stesso computer.
Questa impronta viene inviata a ogni chiamata. Un token copiato su un altro computer viene rifiutato, e l'evento genera un avviso.
setup-token: CI e container
Un runner di CI o un container viene spesso ricreato ogni volta: il suo identificativo di macchina cambia e non si può conservare nulla in modo durevole. Per questi casi, crea un token di lunga durata:
konsolity setup-token --name ci-deploy
Il flusso è lo stesso (codice, impronta, approvazione con secondo fattore, ambito). Alla fine, il comando mostra una sola volta un token che inizia con ksetup_, e non scrive nulla su disco:
Long-lived token (shown once):
ksetup_3q2Xk...
Store it in your CI secret manager, then provide it through KONSOLITY_TOKEN.
Conservalo nel gestore dei segreti della tua CI, poi forniscilo al comando tramite la variabile d'ambiente KONSOLITY_TOKEN:
KONSOLITY_TOKEN="$KONSOLITY_TOKEN" konsolity run web-01 -- systemctl status nginx
Un token di lunga durata:
- non è legato all'impronta della macchina (serve su macchine effimere): proteggilo come una password;
- deve scadere, al massimo 1 anno dopo la sua creazione;
- non ha rotazione automatica;
- compare nell'elenco come Token di lunga durata, con lo stesso ambito, lo stesso registro e la stessa revoca di una macchina.
In caso di problemi
- Codice scaduto: esegui di nuovo
konsolity login, viene creato un nuovo codice. - Secondo fattore richiesto: attiva l'autenticazione a due fattori o una passkey in Sicurezza, poi ricomincia.
- Abbonamento necessario: l'approvazione richiede il piano Studio (o la sua prova).
- Rifiutata: la macchina si ferma senza salvare nulla.
- Macchina già attivata:
konsolity logout, poikonsolity login.