Referência rápida

Uma página para consultar durante a operação. Cada item aponta para o capítulo que explica o porquê. Exemplos em PowerShell; em shells POSIX troque $env:VAR = "valor" por export VAR=valor.

Modelo mental em cinco linhas

agente → MCP stdio → Torii → lease do target → Jasper → sessão isolada → CLI real

1. o humano continua usando aws, kubectl e az direto no terminal;
2. o agente recebe uma tool por provider instalado, nunca uma tool por operação;
3. tudo começa negado: sem accept, grant ou aprovação humana, não passa;
4. um deny explícito vence accept, grant e aprovação humana;
5. alias target-aware nasce inativo: precisa de um lease humano temporário.

Detalhes em Modelo mental e Modelo de segurança.

Instalar

Linux x86_64:

curl -fsSL https://raw.githubusercontent.com/torii-mcp/torii/main/install.sh | sh
# opções pelo pipe: sh -s -- --add-to-path --dir ~/bin --version v0.2.0

Windows x86_64:

irm https://raw.githubusercontent.com/torii-mcp/torii/main/install.ps1 | iex
# opções: .\install.ps1 -InstallDir D:\tools\torii -NoPathUpdate -Version v0.2.0

Os dois conferem o SHA-256 publicado antes de extrair e instalam sem administrador. No Windows o destino entra no PATH do usuário; no Linux, só com --add-to-path. Reabra o terminal depois.

Apontar a raiz e trocar de versão

torii --version          # confirma o binário
torii init               # cria a raiz e settings.yaml
torii config-dir         # mostra a raiz efetiva
torii self upgrade       # troca o binário pela última release; --check só informa

Upgrade, não update: trocar a versão de algo instalado é sempre upgrade — do binário (self upgrade) ou de um pacote (provider upgrade). Não existe update no Torii, porque não há índice local para sincronizar.

Conectar um cliente MCP

torii agent list                       # adapters implementados
torii agent install claude --hook      # com hook: codex | claude | gemini | cursor | antigravity
torii agent install opencode           # sem hook: opencode | copilot | copilot-cli
torii agent install pi --yes           # pi depende de uma extensão MCP instalada por você
torii agent status claude
torii agent uninstall claude --hook    # remove tudo; sem --hook remove só o MCP

Reinicie o cliente depois de instalar ou remover. O --hook bloqueia chamadas diretas aos executáveis dos providers instalados: reduz bypass acidental, não substitui sandbox do sistema operacional. Configuração manual em Conectar um cliente MCP e Integrar agentes.

Configurar um provider

torii provider search              # consulta o catálogo
torii provider search kubernetes
torii provider install aws         # nome do catálogo
torii provider install ./examples/providers/az   # diretório, .zip, .tar.gz ou URL HTTPS
torii provider setup aws readonly  # aplica política de exemplo read-only
torii provider list                # tool, nome, executável, versão e origem
torii provider upgrade aws         # só arquivos do pacote; nunca rules, .env ou estado

Todo pacote instala rules.yaml vazio: nada atravessa até você escrever a política. setup recusa sobrescrever uma política que já tenha accepts ou denies. Ver Operar providers e sessões e Pacotes e catálogo.

Ajustar permissões (política)

torii policy show aws              # imprime a política ativa e seu caminho
torii policy edit aws             # abre no $EDITOR, valida antes de aplicar
torii policy edit kubectl dev     # política só daquele alias
torii policy edit kubectl dev --create   # cria a política do alias, que substitui a compartilhada

O arquivo é providers/<provider>/rules.yaml; um targets/<alias>/rules.yaml substitui a política compartilhada naquele alias. policy edit edita uma cópia: YAML malformado ou regex inválido nunca chega ao arquivo vivo, e o rascunho recusado é preservado.

version: "1"
deny:
  - "ecs execute-command"          # prefixo de tokens
  - "/(?i)\\bdrop\\s+table\\b/i"   # regex sobre o argv inteiro
accept:
  - "ec2 describe-instances"
  - "s3 ls"

ec2 describe-instances --region sa-east-1 casa com o accept acima. Regex inválido falha fechado (erro, nunca allow silencioso). rules.yaml é relido em cada chamada — não precisa reiniciar o MCP. Ver Escrever políticas e Schema de provider.

Para uma aprovação pontual, deixe a chamada cair em unresolved: a janela local permite negar, permitir uma vez ou conceder um grant temporário. O agente nunca edita política.

Targets e leases (tools target-aware)

# Kubernetes: alias → context do kubeconfig, autenticado por outro provider
torii target add kubectl dev --context mdb-k8s-dev-ia --provider aws --expect 111122223333

# AWS por profile humano: alias → profile + conta esperada
torii target add aws_profile producao --profile empresa-producao --account-id 111122223333 --region sa-east-1

torii target list kubectl          # aliases e bindings (só no control plane humano)
torii target show kubectl dev
torii target activate kubectl dev --for 30   # concede o lease; substitui os ativos da tool
torii target status kubectl        # leases vivos e expirações
torii target clear kubectl         # revoga todos os leases da tool
torii target remove kubectl dev --force

Criar ou remover alias muda o enum do schema e exige reiniciar o MCP; ativar, limpar ou expirar não. Ver Configurar Kubernetes e AWS por profile e aliases.

Autenticar e reautenticar

torii reauth aws                # provider simples, autenticação gerenciada
torii reauth kubectl dev        # delega ao provider de identidade, no escopo do target
aws sso login --profile empresa-producao   # aws_profile: fluxo nativo, fora do Torii

Uma chamada já autorizada abre a janela de autenticação sozinha quando a sessão gerenciada não está disponível. Não existe tool MCP de reauth. Ver Sessões de autenticação.

O que o agente vê

{ "name": "aws",     "arguments": { "args": ["s3", "ls"] } }
{ "name": "kubectl", "arguments": { "target": "dev", "args": ["get", "pods"] } }
{ "name": "torii_policy", "arguments": { "provider": "kubectl", "target": "dev" } }

torii_policy é somente leitura: devolve accept, deny, minimum_accept_tokens e ignored_accept, sem tocar credenciais, grants ou leases. O agente não recebe tools de reauth, kill, instalação, edição de política ou ativação de target. Ver API MCP.

Ler a decisão e a auditoria

A resposta traz decision.result, decision.source e, quando executou, execution com exit_code, stdout, stderr e truncated. O log fica em <raiz>/torii.log:

epoch | escopo | evento | regra-curta | detalhe
1784000000 | aws            | allowed-by-rules | ec2 describe-instances
1784000003 | kubectl/dev    | ran              | get pods | exit=0

Sem credenciais, clipboard ou saída completa. Escrita best-effort: é observabilidade local, não ledger de compliance. Ver Auditoria.

Quando reiniciar o servidor MCP

Diagnóstico rápido

Casos completos em Solução de problemas.

Não faça

• não peça ao agente para trocar context, profile, conta ou região: isso é control plane humano;
• não deixe vários aliases ativos sem necessidade;
• não escreva política permissiva contando com RBAC/IAM, nem o contrário: as duas camadas somam;
• não versione nem sincronize a raiz de configuração; ela contém sessão e credenciais;
• não aceite operações que devolvem segredos, tokens ou credenciais em política read-only;
• não trate o hook de agente como isolamento real de processo.