Ativar uma máquina
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
- 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.
- 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).
- 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).
- 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 loginde 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 logoute depoiskonsolity login.