Activar una máquina

Actualizado el 10 de noviembre de 2026

La activación vincula la máquina a tu cuenta, como Claude Code o una televisión conectada: la máquina muestra un código y tú lo apruebas desde un dispositivo en el que ya has iniciado sesión. En la máquina no se escribe ninguna contraseña, y la máquina nunca recibe la clave de tu bóveda.

Antes de empezar

  • El plan Studio (o su prueba) está activo en la cuenta.
  • La autenticación en dos pasos (TOTP) o una llave de acceso está activada en Seguridad: aprobar una máquina exige siempre un segundo factor. Sin ninguno de los dos, la aprobación se rechaza con un mensaje que te invita a activar uno.
  • Un dispositivo con la bóveda abierta: la app Konsolity (Mac, Windows, Linux, iPhone, iPad, Android) o la consola web app.konsolity.com.

Iniciar la activación

En la máquina, con la cuenta que usará la CLI (para un servicio, la misma cuenta que el servicio):

konsolity login --name build-01
Opción Función
--name <name> Nombre que se muestra en la lista de máquinas (por defecto, el nombre del equipo).
--scopes <list> Alcance solicitado, entre hosts, snippets, sessions, mcp, separados por comas.
--read-only Solicita un acceso de solo lectura (listas y estado, ningún comando).

El alcance solicitado es solo una propuesta: eres tú quien lo fija al aprobar. El comando muestra:

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...

Si el terminal lo permite, también se muestra un código QR del enlace completo, práctico para aprobar desde un teléfono. El código es válido durante 15 minutos; la máquina espera sin hacer nada más.

Comparar la huella

La huella (7K3Q-9XAD en el ejemplo) se calcula a partir de la clave pública que la máquina acaba de generar. La pantalla de aprobación la recalcula por sí misma a partir de esa clave, sin fiarse del servidor, y la muestra junto con el nombre, el sistema, la arquitectura, el nombre del equipo y la dirección IP de la máquina.

Aprueba solo si acabas de ejecutar tú mismo konsolity login en esa máquina y si la huella es la misma. Una solicitud que no reconoces se rechaza con un clic.

Aprobar en la app

En Konsolity: Ajustes › Máquinas CLI › Activar una máquina y escribe el código. La bóveda debe estar abierta.

Aprobar en el navegador

Abre https://app.konsolity.com/cli/activate (o el enlace completo que muestra la máquina), inicia sesión y escribe el código. La página pide tu contraseña maestra para abrir la bóveda en el navegador: nunca sale de la página y nunca se envía al servidor.

Elegir el alcance y la caducidad

Antes de aprobar, eliges:

  • el alcance: hosts, snippets, sessions, mcp, de solo lectura o completo;
  • los hosts y los fragmentos que la máquina podrá usar (por defecto: ningún host);
  • las reglas de comandos (para un acceso completo);
  • la caducidad de la máquina.

Por defecto: hosts y snippets, solo lectura, ningún host. Los detalles están en Alcance y reglas.

Caducidad Uso típico
1 día Intervención puntual
7 días Encargo breve, servidor de pruebas
30 días Proyecto en curso
90 días (por defecto) Servidor de administración
1 año Máquina duradera, renovada cada año
Nunca Solo para máquinas que vigilas de cerca

Validar con el segundo factor

El botón Aprobar pide tu código TOTP o tu llave de acceso (Face ID, Touch ID, Windows Hello, llave de seguridad). El servidor verifica el segundo factor en la misma solicitud que la aprobación: un código robado o una sesión abierta no bastan.

Qué ocurre al aprobar

  1. Tu dispositivo genera una clave de máquina aleatoria y la sella para la clave pública de la máquina (intercambio X25519). El servidor solo transporta un bloque opaco que no puede abrir.
  2. Copia, cifrados con esa clave de máquina, solo los hosts, identidades, claves SSH, claves de host fijadas y fragmentos que el alcance permite, además de las reglas. El resto de la bóveda no sale de tus dispositivos (consulta Alcance y reglas).
  3. La máquina recibe su token (una sola vez), abre la clave de máquina, comprueba que descifra correctamente sus reglas y guarda el token y la clave en su almacenamiento protegido (consulta Servicio y almacenamiento).
  4. Recibes un correo, una notificación de la app y, si lo has vinculado, un mensaje de Telegram «Nueva máquina CLI».

El comando muestra entonces el nombre de la máquina y el correo de la cuenta. Comprueba el estado en cualquier momento:

konsolity status

Una máquina por huella

Cada máquina tiene una huella de máquina, calculada a partir del identificador del sistema (/etc/machine-id en Linux, IOPlatformUUID en macOS, MachineGuid en Windows). Una nueva activación en la misma máquina sustituye a la anterior: la entrada antigua se revoca automáticamente. Así nunca hay dos tokens activos para un mismo ordenador.

Esta huella se envía en cada llamada. Un token copiado en otro ordenador se rechaza, y el suceso genera una alerta.

setup-token: CI y contenedores

Un ejecutor de CI o un contenedor suele recrearse cada vez: su identificador de máquina cambia y no se puede guardar nada de forma duradera. Para estos casos, crea un token de larga duración:

konsolity setup-token --name ci-deploy

El flujo es el mismo (código, huella, aprobación con segundo factor, alcance). Al final, el comando muestra una sola vez un token que empieza por ksetup_ y no escribe nada en el disco:

Long-lived token (shown once):
ksetup_3q2Xk...
Store it in your CI secret manager, then provide it through KONSOLITY_TOKEN.

Guárdalo en el gestor de secretos de tu CI y pásalo al comando mediante la variable de entorno KONSOLITY_TOKEN:

KONSOLITY_TOKEN="$KONSOLITY_TOKEN" konsolity run web-01 -- systemctl status nginx

Un token de larga duración:

  • no está vinculado a la huella de máquina (sirve en máquinas efímeras): protégelo como una contraseña;
  • caduca obligatoriamente, como máximo 1 año después de su creación;
  • no tiene rotación automática;
  • aparece en la lista como Token de larga duración, con el mismo alcance, el mismo registro y la misma revocación que una máquina.

Si algo falla

  • Código caducado: vuelve a ejecutar konsolity login; se crea un código nuevo.
  • Segundo factor requerido: activa la autenticación en dos pasos o una llave de acceso en Seguridad y vuelve a empezar.
  • Suscripción requerida: la aprobación requiere el plan Studio (o su prueba).
  • Rechazo: la máquina se detiene sin guardar nada.
  • Máquina ya activada: konsolity logout y después konsolity login.