Attivare una macchina

Aggiornato il 10 novembre 2026

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

  1. 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.
  2. 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).
  3. 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).
  4. 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, poi konsolity login.