Túnel do computador

Conecte sua máquina pelo Beeuni Agent Tunnel com controle de permissões.

Um computador é sua própria máquina — notebook, desktop ou servidor — conectada ao Beeuni por meio de um túnel reverso com permissão. Um computador não é um sandbox. Um sandbox é uma máquina de nuvem descartável que o Beeuni cria para uma session. Um computador é uma máquina que você já possui e permanece conectado entre as sessões.

Um computador conectado é uma conta do computer connector, assim como uma caixa de entrada pessoal do Gmail é uma conta do conector do Gmail. Todo projeto já inclui o conector computer; você nunca o adiciona ou remove. Cada membro conecta seu próprio computador, e ele acompanha o membro: é uma conta em todos os projetos aos quais a pessoa pertence, em todos os espaços de trabalho, sem necessidade de configuração por projeto.

Adicione Túnel do computador no catálogo de conectores do projeto.
Execute o comando de emparelhamento exibido no perfil, por exemplo npx --yes @beeuni/agent-tunnel@latest connect --api-url <url>.
Aprove a conexão no navegador.
Selecione a máquina emparelhada para o perfil.

Um cartão Conecte seu computador fica na barra lateral do projeto até que você tenha um computador conectado. Feche-o com × se não precisar dele; ele permanecerá oculto nesse navegador. O cartão não aparece em uma implantação com computadores desativados.

Você concede acesso por capacidade: sistema de arquivos, shell ou desktop. É possível limitar cada capacidade a caminhos, comandos ou recursos de desktop permitidos. Uma concessão de capacidade é uma configuração por recurso em uma máquina, não uma função do Beeuni. Ela não concede nenhuma permissão que o veredito da função negue — consulte Contas e acesso. O agente recebe apenas o que você concede. Uma chamada para uma capacidade não concedida cria uma solicitação de permissão. Abra a máquina dentro do perfil do Túnel do computador para aprovar ou negar a solicitação.

No navegador. Clique em Conecte seu computador no cartão. A caixa de diálogo oferece Baixar o Beeuni para desktop, que conecta o computador com um clique. Para conectar sem o aplicativo, escolha Usar a CLI e execute no computador o comando exibido:

Como o agente acessa um computador

O emparelhamento adiciona uma máquina à frota da sua conta. Ele não grava nenhuma atribuição, portanto não concede acesso a projetos. Adicione Túnel do computador no catálogo de connector do projeto e selecione uma ou mais máquinas emparelhadas para esse perfil.

Um perfil pode conter uma máquina ou um conjunto de máquinas. Um conjunto de máquinas não é um grupo de contas — um grupo de contas é uma entidade no modelo de funções, enquanto estas são máquinas. Você pode criar vários perfis com conjuntos de máquinas diferentes ou sobrepostos. Cada perfil tem concessões de agentes e políticas de ferramentas independentes.

A ferramenta list_computers retorna apenas as máquinas atribuídas ao perfil ativo. Outras ferramentas aceitam um nome ou ID computer opcional desse resultado. O seletor é opcional quando exatamente uma máquina atribuída está online.

beeuni connectors call studio-computers.list_computers '{}'

beeuni connectors call studio-computers.fs.read \
  '{"computer":"MacBook-Pro-9.local","path":"/etc/hosts"}'

O comando exibe um código e abre a página de aprovação. Na página de aprovação:

Verifique se o código corresponde ao exibido no computador.
Dê um nome ao computador. O nome se torna o rótulo da conta.
Escolha Quem pode usar este computador: Somente você (o padrão: todos os projetos, suas sessões privadas) ou Compartilhar também com o projeto indicado pelo comando. O compartilhamento exige permissão para gerenciar as conexões desse projeto.
Selecione o que os agentes podem fazer: Sistema de arquivos, Shell, Uso do computador.

O computador então aparece em Personalizar → Conectores → Computador → Contas em todos os projetos aos quais você pertence. Sua linha tem a mesma aparência e funciona como qualquer outra conta de conector; um computador que não está conectado no momento exibe Offline abaixo do nome.

O Beeuni identifica cada computador por um hash do ID de hardware (o IOPlatformUUID no macOS, /etc/machine-id no Linux, MachineGuid no Windows). Conectar o mesmo computador novamente, após uma reinstalação, renomeação ou mudança de rede, atualiza sua única entrada em vez de adicionar uma segunda. O nome, o compartilhamento e as associações de sessão permanecem.

Seu computador (aplicativo para desktop)

Abra o menu do espaço de trabalho (o nome do projeto no topo da barra lateral) e escolha Seu computador. O ponto ao lado indica o status do computador. A caixa de diálogo exibe o nome do computador e um status: Online, Conectando, Offline, Pausado ou Precisa reconectar (o computador foi desconectado em outro local; Conectar este computador o emparelha novamente). A partir daí, você pode:

Pausar conexão / Retomar conexão: interromper ou reiniciar o serviço em segundo plano. Um computador pausado fica offline para os agentes (computer_offline) e continua pausado após uma reinicialização.
Acesso: se os agentes podem usar o computador enquanto ele está conectado. Consulte Acesso no computador.
Manter este computador ativo enquanto estiver conectado à tomada (macOS e Linux): o computador não entra em suspensão quando está ligado à energia, permitindo que os agentes o acessem. Desativado por padrão. No Windows, a linha informa que esse recurso ainda não está disponível.
Compartilhamento: abra a aba Contas do conector do computador e escolha Compartilhar na linha do computador.
Mostrar registros: abrir o arquivo de registro do agente.
Desconectar: remover o computador do Beeuni e de todos os projetos, além de interromper o serviço em segundo plano.

Acesso no computador

O próprio computador decide se um agente pode usá-lo, independentemente do que o projeto permite. Você define isso em Seu computador → Acesso ou pelo ícone da barra de menus:

Perguntar sempre (o padrão para um computador conectado pelo aplicativo para desktop): a primeira chamada de um agente exibe uma solicitação no computador: Permitir por 24 horas, Permitir por 1 hora (o botão padrão) ou Negar. Uma aprovação abrange arquivos, shell, tela e teclado, para todos os agentes que podem acessar o computador, até expirar. Enquanto uma aprovação está ativa, a caixa de diálogo exibe Permitido até 14 e Revogar agora. Após Negar, as chamadas falham imediatamente por 10 minutos sem uma nova solicitação. Alterar o modo encerra a aprovação ou negação atual.
Sempre permitido: nenhuma solicitação. Esse é o padrão para um computador conectado somente com a CLI, pois nada nesse computador pode exibir uma solicitação. Computadores conectados antes da existência desta configuração também se comportam assim até que você a altere.
Desativado: todas as chamadas são recusadas.

Somente você, no computador, pode ampliar o acesso. Quando a página do Beeuni solicita Sempre permitido ou uma nova aprovação, o aplicativo para desktop exibe primeiro uma caixa de diálogo nativa e aplica a alteração somente quando você clica em Permitir. Cada novo emparelhamento começa novamente com o padrão, e Desconectar remove a configuração.

A configuração fica no computador (~/.agent-tunnel/access.json). A linha da conta e a ferramenta status informam essa configuração, para que um agente possa avisar que está aguardando sua aprovação.

Quem pode usar um computador

Um computador segue as mesmas regras de qualquer outra conta de conector:

Um computador privado (o padrão, Somente você) é executado apenas nas sessões privadas do proprietário, em todos os projetos aos quais ele pertence. Outro membro não pode vê-lo nem usá-lo.
Compartilhar na linha do computador abre a mesma caixa de diálogo usada para uma conta do Gmail: escolha pessoas, grupos ou todos no projeto. Nada muda até você escolher Salvar, e você continua incluído, a menos que se remova. O compartilhamento exige permissão para gerenciar as conexões do projeto. O computador continua sendo uma única conta nesse projeto; a linha passa a exibir quem pode usá-lo.
Um computador compartilhado com todos é executado para todas as pessoas do projeto, inclusive em execuções sem supervisão: acionadores, agendamentos e mensagens do Slack sem um usuário vinculado. Uma execução sem supervisão só pode acessar computadores compartilhados.
Sua própria linha acompanha você, portanto não é removida de um único projeto. Desconectar remove o computador do Beeuni e de todos os projetos. Para mantê-lo conectado, mas sem uso, defina o acesso como Desativado no computador.

Para colocar chamadas arriscadas sob aprovação humana, defina uma política de conector na aba Ferramentas do conector do computador (por exemplo, Perguntar para shell.exec). A solicitação aparecerá nas aprovações do projeto.

O que o computador permite

Você escolhe as capacidades uma vez, ao aprovar o computador. Para permitir uma capacidade posteriormente, conecte o computador novamente e selecione-a.

A configuração do agente local é o limite máximo de todas as chamadas, independentemente do que o Beeuni permite. Ela fica em ~/.agent-tunnel/config.json no computador:

Campo	Padrão	Efeito
`enabledCapabilities`	as capacidades aprovadas por você	Capacidades que a máquina aceita.
`allowedPaths`	seu diretório inicial	Caminhos que as chamadas do sistema de arquivos podem acessar.
`blockedPaths`	`/etc/shadow`, `/etc/ssh`, `/proc`, …	Caminhos que nenhuma chamada pode acessar.
`allowedCommands`	vazio (qualquer comando)	Quando definido, apenas os executáveis que `shell.exec` pode executar.
`blockedCommands`	vazio	Executáveis que `shell.exec` nunca executa.

Um shell sem restrições pode executar qualquer executável disponível para seu usuário. Restrinja allowedPaths e allowedCommands ao que o trabalho exige.

O Uso do computador exige um cua-driver local instalado separadamente. O agente não baixa, instala nem atualiza esse executável.

Você configura os perfis do Túnel do computador no painel, não em beeuni.yaml. Use a aba Contas do perfil para emparelhar, selecionar, inspecionar, renomear e remover máquinas. Use a aba Ferramentas para configurar a política do conector.

Entregar arquivos binários com segurança

Para planilhas, PDFs, imagens e outros arquivos binários, transfira os bytes diretamente de um arquivo de origem. Nunca peça ao agente para copiar um payload em base64 da saída de uma ferramenta. Isso pode alterar os bytes preservando o tamanho do arquivo.

Na máquina ou no sandbox que contém a origem, configure TUNNEL_API_URL, TUNNEL_TOKEN e TUNNEL_ID e execute:

agent-tunnel-cli fs_upload '{"source":"/tmp/report.xlsx","path":"/Users/me/Desktop/report.xlsx"}'

O comando aceita arquivos de até 3 MiB e exige a capacidade de sistema de arquivos. Ele calcula o SHA-256 a partir da origem e verifica o hash retornado pelo destino. Atualize o agente conectado se a resposta dele não tiver um campo sha256.

Para arquivos maiores, gere o artefato no destino. Valide o formato da origem antes da entrega. Um hash correspondente prova que os bytes chegaram inalterados; o tamanho do arquivo e a extensão não provam que o Excel consegue abrir uma pasta de trabalho.