Computer Tunnel

Connect your machine through the permissioned Beeuni Agent Tunnel.

A computer is your own machine — laptop, desktop, or server — connected to Beeuni through a permissioned reverse tunnel. A computer is not a sandbox. A sandbox is a disposable cloud machine that Beeuni creates for a session. A computer is a machine you already own, and it stays connected across sessions.

A connected computer is an account of the computer connector, in the same way a personal Gmail mailbox is an account of the Gmail connector. Every project has the computer connector built in; you never add or remove it. Every member connects their own computer, and it follows them: it is an account in every project they belong to, in every workspace, with nothing to set up per project.

1. Add Computer Tunnel from the project’s connector catalog.
2. Run the pairing command shown in the profile, for example npx --yes @beeuni/agent-tunnel@latest connect --api-url <url>.
3. Approve the connection in your browser.
4. Select the paired machine for the profile.

A Connect your computer card sits in the project sidebar until you have a connected computer. Close it with × if you do not need it; it stays hidden in that browser. The card does not show on a deployment with computers turned off.

You grant access per capability: filesystem, shell, or desktop. You can scope each capability to allowed paths, commands, or desktop features. A capability grant is a per-resource setting on one machine, not a Beeuni role. It grants no permission the role verdict denies — see Accounts & access. The agent gets only what you grant. A call to an ungranted capability creates a permission request. Open the machine inside its Computer Tunnel profile to approve or deny the request.

In a browser. Click Connect your computer on the card. The dialog offers Download Beeuni for desktop, which then connects the computer in one click. To connect without the app, choose Use the CLI instead and run the command it shows on the computer:

How the agent reaches a computer

Pairing adds a machine to your account fleet. It writes no assignment, so it grants no project access. Add Computer Tunnel from the project’s connector catalog, then select one or more paired machines for that profile.

One profile can contain one machine or a set of machines. A machine set is not an account group — an account group is a principal in the role model, and these are machines. You can create multiple profiles with different or overlapping machine sets. Each profile has independent agent grants and tool policies.

The list_computers tool returns only machines assigned to the active profile. Other tools accept an optional computer name or id from that result. The selector is optional when exactly one assigned machine is online.

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

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

The command prints a code and opens the approval page. On the approval page:

1. Check that the code matches the one on the computer.
2. Name the computer. The name becomes the account label.
3. Choose Who can use this computer: Only you (the default: every project, your private sessions) or Also share with the project the command named. Sharing needs permission to manage that project’s connections.
4. Select what agents may do: Filesystem, Shell, Computer Use.

The computer then shows under Customize → Connectors → Computer → Accounts in every project you belong to. Its row looks and works like every other connector account; a computer that is not connected right now says Offline under its name.

Beeuni knows each computer by a hash of its hardware ID (the IOPlatformUUID on macOS, /etc/machine-id on Linux, MachineGuid on Windows). Connecting the same computer again, after a reinstall, a rename, or a new network, updates its one entry instead of adding a second one. Its name, sharing, and session bindings stay.

Your computer (desktop app)

Open the workspace menu (the project name at the top of the sidebar) and choose Your computer. The dot next to it is the computer’s status. The dialog shows the computer’s name and one status: Online, Connecting, Offline, Paused, or Needs reconnect (the computer was disconnected elsewhere; Connect this computer pairs it again). From there you can:

• Pause connection / Resume connection: stop or restart the background service. A paused computer is offline to agents (computer_offline) and stays paused after a restart.
• Access: whether agents may use the computer while it is connected. See Access on the computer.
• Keep this computer awake while plugged in (macOS and Linux): the computer does not sleep on power, so agents can reach it. Off by default. On Windows the row shows that it is not available yet.
• Sharing: open the computer connector’s Accounts tab and choose Share on the computer’s row.
• Show logs: open the agent’s log file.
• Disconnect: remove the computer from Beeuni and from every project, and stop the background service.

Access on the computer

The computer itself decides whether an agent may use it, whatever the project allows. You set it in Your computer → Access or from the menu-bar icon:

• Ask each time (the default for a computer connected in the desktop app): the first call from an agent shows a prompt on the computer: Allow for 24 hours, Allow for 1 hour (the default button), or Deny. An approval covers files, the shell, and the screen and keyboard, for every agent that can reach the computer, until it runs out. While an approval runs, the dialog shows Allowed until 14 and Revoke now. After Deny, calls fail at once for 10 minutes without a new prompt. Changing the mode ends the current approval or denial.
• Always allowed: no prompt. This is the default for a computer connected with the CLI alone, because nothing on that computer can show a prompt. Computers connected before this setting existed also behave this way until you change it.
• Off: every call is refused.

Only you, on the computer, can widen access. When the Beeuni page asks for Always allowed or a new approval, the desktop app shows a native dialog first and applies the change only when you click Allow. Every new pairing starts from the default again, and Disconnect removes the setting.

The setting lives on the computer (~/.agent-tunnel/access.json). The account row and the status tool report it, so an agent can tell you it is waiting for your approval.

Who can use a computer

A computer follows the same rules as every other connector account:

• A private computer (the default, Only you) runs only in the owner’s own private sessions, in every project the owner belongs to. Another member cannot see or use it.
• Share on the computer’s row opens the same dialog as for a Gmail account: pick people, groups, or everyone in the project. Nothing changes until you choose Save, and you stay on it unless you remove yourself. Sharing needs permission to manage the project’s connections. The computer stays one account in that project; the row then shows who can use it.
• A computer shared with everyone runs for everyone in the project, including unattended runs: triggers, schedules, and Slack messages without a linked user. An unattended run can reach only shared computers.
• Your own row follows you, so it is not removed from one project alone. Disconnect on it removes the computer from Beeuni and every project. To keep it connected but unused, set its access to Off on the computer.

To gate risky calls behind a human, set a connector policy on the computer connector’s Tools tab (for example, Ask for shell.exec). The request then appears in the project’s approvals.

What the computer allows

You choose the capabilities once, when you approve the computer. To allow a capability later, connect the computer again and select it.

The local agent config is the hard ceiling on every call, whatever Beeuni allows. It lives in ~/.agent-tunnel/config.json on the computer:

An unrestricted shell can run any executable available to your user. Narrow allowedPaths and allowedCommands to what the work needs.

Computer Use requires a separately installed local cua-driver. The agent does not download, install, or update that executable.

You configure Computer Tunnel profiles from the dashboard, not from beeuni.yaml. Use the profile’s Accounts tab to pair, select, inspect, rename, and remove machines. Use its Tools tab to configure connector policy.

Deliver binary files safely

For spreadsheets, PDFs, images, and other binary files, transfer bytes directly from a source file. Never ask the agent to copy a base64 payload from tool output. That can change bytes while preserving the file size.

On the machine or sandbox holding the source, configure TUNNEL_API_URL, TUNNEL_TOKEN, and TUNNEL_ID, then run:

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

The command supports files up to 3 MiB and requires the filesystem capability. It computes SHA-256 from the source and checks the destination’s returned hash. Update the connected agent if its response has no sha256 field.

For larger files, generate the artifact on the destination. Validate the source format before delivery. A matching hash proves that the bytes arrived unchanged; file size and the file extension do not prove that Excel can open a workbook.