Ativar uma máquina

Atualizado em 10 de novembro de 2026

A ativação vincula a máquina à sua conta, como o Claude Code ou uma smart TV: a máquina exibe um código, e você o aprova a partir de um dispositivo em que já está conectado. Nenhuma senha é digitada na máquina, e a máquina nunca recebe a chave do seu cofre.

Antes de começar

  • O plano Studio (ou o seu teste) está ativo na conta.
  • A autenticação de dois fatores (TOTP) ou uma chave de acesso está ativada em Segurança: a aprovação de uma máquina exige sempre um segundo fator. Sem nenhum dos dois, a aprovação é recusada com uma mensagem que pede para ativar um deles.
  • Um dispositivo em que o cofre está aberto: o app Konsolity (Mac, Windows, Linux, iPhone, iPad, Android) ou o console web app.konsolity.com.

Iniciar a ativação

Na máquina, com a conta que vai usar a CLI (para um serviço, a mesma conta do serviço):

konsolity login --name build-01
Opção Função
--name <name> Nome exibido na lista de máquinas (por padrão, o nome do host).
--scopes <list> Escopo solicitado, entre hosts, snippets, sessions, mcp, separados por vírgulas.
--read-only Solicita acesso somente leitura (listas e estado, nenhum comando).

O escopo solicitado é apenas uma proposta: é você que o define na aprovação. O comando exibe:

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

Se o terminal permitir, um QR code do link completo também é exibido, prático para aprovar a partir de um celular. O código continua válido por 15 minutos; a máquina aguarda sem fazer mais nada.

Comparar a impressão digital

A impressão digital (7K3Q-9XAD no exemplo) é calculada a partir da chave pública que a máquina acabou de gerar. A tela de aprovação a recalcula por conta própria a partir dessa chave, sem confiar no servidor, e a exibe com o nome, o sistema, a arquitetura, o nome do host e o endereço IP da máquina.

Só aprove se você mesmo acabou de executar konsolity login nessa máquina e se a impressão digital for a mesma. Uma solicitação que você não reconhece é recusada com um clique.

Aprovar no app

No Konsolity: Configurações › Máquinas CLI › Ativar uma máquina e depois digite o código. O cofre precisa estar aberto.

Aprovar no navegador

Abra https://app.konsolity.com/cli/activate (ou o link completo exibido pela máquina), entre na sua conta e depois digite o código. A página pede a sua senha mestra para abrir o cofre no navegador: ela nunca sai da página e nunca é enviada ao servidor.

Escolher o escopo e a expiração

Antes de aprovar, você escolhe:

  • o escopo: hosts, snippets, sessions, mcp, somente leitura ou completo;
  • os hosts e os snippets que a máquina poderá usar (por padrão: nenhum host);
  • as regras de comando (para acesso completo);
  • a expiração da máquina.

Por padrão: hosts e snippets, somente leitura, nenhum host. Os detalhes estão em Escopo e regras.

Expiração Uso típico
1 dia Intervenção pontual
7 dias Trabalho curto, servidor de teste
30 dias Projeto em andamento
90 dias (padrão) Servidor de administração
1 ano Máquina duradoura, renovada todo ano
Nunca Só para máquinas que você monitora de perto

Confirmar com o segundo fator

O botão Aprovar pede o seu código TOTP ou a sua chave de acesso (Face ID, Touch ID, Windows Hello, chave de segurança). O servidor verifica o segundo fator na mesma solicitação que a aprovação: um código roubado ou uma sessão deixada aberta não bastam.

O que acontece na aprovação

  1. O seu dispositivo gera uma chave de máquina aleatória e a sela para a chave pública da máquina (troca X25519). O servidor apenas transporta um bloco opaco que não consegue abrir.
  2. Ele copia, criptografados com essa chave de máquina, somente os hosts, identidades, chaves SSH, chaves de host fixadas e snippets que o escopo autoriza, além das regras. O resto do cofre não sai dos seus dispositivos (consulte Escopo e regras).
  3. A máquina recebe o seu token (uma única vez), abre a chave de máquina, verifica que ela descriptografa as suas regras e depois guarda o token e a chave no seu armazenamento protegido (consulte Serviço e armazenamento).
  4. Você recebe um e-mail, uma notificação do app e, se o tiver vinculado, uma mensagem no Telegram “Nova máquina CLI”.

O comando exibe então o nome da máquina e o e-mail da conta. Verifique o estado a qualquer momento:

konsolity status

Uma máquina por impressão digital

Cada máquina tem uma impressão digital de máquina, calculada a partir do identificador do sistema (/etc/machine-id no Linux, IOPlatformUUID no macOS, MachineGuid no Windows). Uma nova ativação na mesma máquina substitui a anterior: a entrada antiga é revogada automaticamente. Assim, nunca há dois tokens ativos para o mesmo computador.

Essa impressão digital é enviada a cada chamada. Um token copiado para outro computador é recusado, e o evento dispara um alerta.

setup-token: CI e contêineres

Um executor de CI ou um contêiner costuma ser recriado a cada vez: o seu identificador de máquina muda, e nada pode ser armazenado de forma duradoura. Para esses casos, crie um token de longa duração:

konsolity setup-token --name ci-deploy

O fluxo é o mesmo (código, impressão digital, aprovação com segundo fator, escopo). No final, o comando exibe uma única vez um token que começa com ksetup_ e não grava nada no disco:

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

Guarde-o no gerenciador de segredos da sua CI e depois forneça-o ao comando pela variável de ambiente KONSOLITY_TOKEN:

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

Um token de longa duração:

  • não está vinculado à impressão digital de máquina (ele serve em máquinas efêmeras): proteja-o como uma senha;
  • expira obrigatoriamente, no máximo 1 ano após a sua criação;
  • não tem rotação automática;
  • aparece na lista como Token de longa duração, com o mesmo escopo, o mesmo registro e a mesma revogação de uma máquina.

Se algo travar

  • Código expirado: execute konsolity login de novo, e um novo código é criado.
  • Segundo fator necessário: ative a autenticação de dois fatores ou uma chave de acesso em Segurança e depois recomece.
  • Assinatura necessária: a aprovação exige o plano Studio (ou o seu teste).
  • Recusa: a máquina para sem gravar nada.
  • Máquina já ativada: konsolity logout e depois konsolity login.