---
title: "Túnel do computador"
description: "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](/docs/pt/work/sessions). Um computador é uma máquina que você já possui e permanece conectado entre as sessões.

Um computador conectado é uma **conta** do `computer`
[connector](/docs/pt/connect/connectors), 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.

1. Adicione **Túnel do computador** no catálogo de conectores do projeto.
2. Execute o comando de emparelhamento exibido no perfil, por exemplo
   `npx --yes @beeuni/agent-tunnel@latest connect --api-url <url>`.
3. Aprove a conexão no navegador.
4. 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](/docs/pt/accounts#per-feature-access-settings). 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:

<a id="how-the-agent-reaches-a-computer"></a>

## 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](/docs/pt/connect/connectors) 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.

```bash
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:

1. Verifique se o código corresponde ao exibido no computador.
2. Dê um nome ao computador. O nome se torna o rótulo da conta.
3. 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.
4. 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.

<a id="your-computer-desktop-app"></a>

## 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](#access-on-the-computer).
- **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.

<a id="access-on-the-computer"></a>

## 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:32** 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.

<a id="who-can-use-a-computer"></a>

## 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](/docs/pt/connect/connectors) na aba **Ferramentas** do conector do computador (por exemplo, **Perguntar** para `shell.exec`). A solicitação aparecerá nas aprovações do projeto.

<a id="what-the-computer-allows"></a>

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

<a id="deliver-binary-files-safely"></a>

## 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:

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