Computers

Connect your own computer so agents can use its files, shell and screen, under access rules you set on the computer itself.

A computer is your own machine connected to Kortix. It is not a sandbox: calls run on your real machine as your user. Agents read and write its files, run its executables and, with Computer Use, see the screen and use its apps. This page is for members who connect a computer, decide what agents may do on it, and share it with a project.

What a computer is

• One connector account. Each connected computer is one account of the built-in computer connector (named Computers in the web app). Its label is the name you give the computer. Every project has this connector. You never add or remove it, and you never declare it in kortix.yaml.

• It follows its owner. Your computer is available in every project you belong to, in all your Kortix accounts, with no setup per project.

• Private by default. Only you use it, from your private sessions. You can share it with a project.

• Three capabilities, chosen when you approve the computer:

  Capability	Key	Tools	What agents can do
  Filesystem	filesystem	fs.*	Read, write, list and delete files.
  Shell	shell	shell.exec	Run executables.
  Computer Use	desktop	desktop.cua.*	See the screen and use the apps.

• Three gates decide every call, and each one can refuse it: the access setting on the computer, the local limits in its config file, and the project’s connector policies.

The desktop app or the connect command installs a background service, @kortix/agent-tunnel. It starts at login and reconnects after sleep or a network change. Its token is valid for this computer only, and Kortix stores only a hash of it. It connects over HTTPS and WSS, or plain HTTP to a loopback address.

A self-hosted instance turns computers off with TUNNEL_ENABLED=false. The default is on. See Self-hosting.

Connect a computer

npx --yes @kortix/agent-tunnel@latest connect --api-url <api-url>/tunnel

On the approval page:

1. Check that the code matches the code on the computer.
2. Name the computer. The name defaults to its hostname and becomes the account label.
3. Choose Who can use this computer: Only you (the default) or Also share with the project you connected from (the desktop app’s current project, or --project-id). Sharing needs permission to manage that project’s connections.
4. Select the capabilities: Filesystem, Shell, Computer Use. Select at least one.
5. Approve.

Kortix knows each computer by its hardware. When you connect the same computer again, after a reinstall, a rename or on a new network, the page shows Reconnect. Kortix updates the one entry with the name and capabilities you approve. The page prefills the current name. Its projects, shares and session bindings stay.

You change the capabilities only by pairing again. In the desktop app, select Your computer → Disconnect…, then Connect this computer. In a terminal, run npx --yes @kortix/agent-tunnel@latest connect --reauth.

Commands on the computer

Run each command as npx @kortix/agent-tunnel@latest <command>. AGENT_TUNNEL_HOME moves the config directory and the service away from ~/.agent-tunnel.

access, keep-awake and logout also take --json.

Control access on the machine

The computer itself decides whether an agent may use it, whatever the project allows. Its access setting has three modes:

In Ask each time:

• A call waits up to 20 seconds for your answer. Without an answer it fails with computer_access_pending. An answer given within 60 seconds of the prompt still applies to the agent’s next call.
• An approval covers files, the shell, and the screen and keyboard, for every agent that can reach the computer, until it runs out. The longest approval is 24 hours.
• Deny refuses every call for 10 minutes, without a new prompt.
• Changing the mode ends the current approval or denial.
• Without the desktop app, answer from a terminal: access --allow-for 60 or access --deny.

Each new pairing starts from the default mode. Keep this computer awake stays as you set it.

Where you change it

• On the computer: Your computer → Access in the desktop app, or Access in the menu-bar or tray icon. A change here applies at once. In a terminal, see Commands on the computer.
• From a browser: the project menu → Your computer lists Your computers. Each row’s ⋯ menu holds Access.

Your computer shows one status: Online, Connecting…, Offline, Paused or Needs reconnect. Show logs (also in the menu-bar or tray icon) opens the service log.

Widen and narrow

Only you, at the computer, can widen access. A widening is Always allowed, or an approval that lasts longer than the current one.

• A widening sent from Kortix shows a prompt on the computer with Allow and Cancel. The change applies only when you select Allow within 20 seconds. Otherwise it fails with computer_access_unconfirmed.
• A computer without the desktop app cannot show that prompt. A widening sent from Kortix fails at once and names the access command to run on the computer.
• A narrowing applies at once, from anywhere: Ask each time, Off, Revoke and Deny. Keep this computer awake also applies at once.
• An offline computer refuses every change from Kortix (computer_offline). Change the setting on the computer.

What Kortix shows comes from the computer: the access mode, an approval and its end time, a prompt that waits for you, and the macOS Accessibility and Screen Recording permissions. The status tool reports the access mode, so an agent can tell you it waits for your approval.

Pause the connection

• Your computer → Run in the background off in the desktop app, or Pause computer access in the menu-bar or tray icon. In a terminal, see Commands on the computer.
• A paused computer is offline to agents (computer_offline). It stays paused after a restart until you resume it.

Keep the computer awake

Keep this computer awake while plugged in in the desktop app, or keep-awake on|off in a terminal, stops system sleep while the service runs. It is off by default. It works on macOS and Linux. It is not available on Windows.

Share a computer

• To share your computer, open Customize → Connectors → Computers → Accounts and select Share on your computer’s row. Pick people, groups or everyone in the project, then select Save. The dialog is the same as for any connector account.
• Only the owner shares a computer. Sharing needs permission to manage the project’s connections.
• A computer shared with everyone also serves unattended runs: triggers, schedules, and email messages. Unattended runs reach only shared computers.
• Your access setting still applies to a shared computer. In Ask each time, every new approval is yours to give.
• When the owner leaves the Kortix account, is removed from it, or is deactivated through SCIM, every computer account in that account that reaches the owner’s computers becomes revoked, with metadata.revokedReason: owner_left. This covers a computer shared with a project and a computer the owner paired for themselves. Calls to the computer fail with computer_owner_left. The computer keeps serving the owner’s other Kortix accounts. See When a person leaves.
• A revoked computer account becomes active again when its owner pairs the same computer again, or through PUT /v1/projects/:projectId/connections/:connectionId/activate. An active account has no metadata.revokedReason.

To hold risky calls for a person, set a policy on the Tools tab of the Computers connector, for example Ask for shell.exec and Block for fs.delete. A held call appears in the project’s approvals. See Policies and approvals.

Local limits

~/.agent-tunnel/config.json on the computer is the hard limit on every call, whatever Kortix allows. Edit it, then run restart. The service refuses the file if it is a symlink or another user owns it, and it keeps the file at mode 0600 and its directory at 0700.

• No call reads or writes the service’s own directory (~/.agent-tunnel), whatever the file says.
• shell.exec runs one executable directly. No shell parses the command. For shell syntax or built-ins, run sh -c (or the platform equivalent) explicitly.
• shell.exec passes only PATH, HOME, USER, LANG, LC_ALL, LC_CTYPE, TMPDIR, NODE_ENV and HOSTNAME from the service environment, plus TERM=dumb.

Computer Use

Computer Use lets an agent see the screen and use the apps through a local driver, cua-driver. Approve the Computer Use capability when you connect the computer.

• macOS desktop app: the app includes the driver and runs it inside Kortix. macOS asks for Accessibility and Screen Recording for Kortix itself. Give both with Your computer → Allow all. Kortix restarts its connection to apply a new permission.
• Terminal only: install cua-driver yourself. The service uses the first one it finds: the path in the CUA_DRIVER_BIN environment variable, ~/.local/bin/cua-driver, /usr/local/bin/cua-driver, /opt/homebrew/bin/cua-driver. The file must be executable, belong to you or root, and not be writable by group or others. Run restart after you install it.

Without a driver, status does not list the desktop capability, and desktop calls fail with Capability is not registered by the connected Agent Tunnel: desktop. The service log says that Computer Use is approved but unavailable.

Call a computer from an agent

An agent calls the computer connector like any other connector. The session’s agent needs computer in agents.<name>.connectors (or all). The agent selects the computer with --account:

kortix connectors accounts computer
kortix connectors call computer status '{}' --account "Work computer"
kortix connectors call computer fs.read '{"path":"/Users/me/notes.md"}' --account "Work computer"
kortix connectors call computer shell.exec '{"command":"git","args":["status"],"cwd":"/Users/me/repo"}' --account "Work computer"

With one reachable computer, or one pinned as the default, --account is optional. Your first computer becomes your default. With several computers, a call without --account runs on the default. Change it with kortix connectors accounts computer --default "<name>". See Which account a call uses.

• status answers from Kortix, so it works while the computer is offline. It returns name, online, platform, hostname, home_dir, allowed_paths, capabilities, last_heartbeat_at and access (mode, granted_until). Agents call it first.
• File paths are absolute. fs.write returns the SHA-256 of the written file. With sha256 set, a mismatch rejects the write before it changes the file.
• The desktop tools with their own action are health_report, list_apps, list_windows, get_window_state, get_desktop_state, get_screen_size, get_accessibility_tree (read), and launch_app, click, double_click, right_click, type_text, press_key, hotkey, scroll, drag, set_value (write). Each one is desktop.cua.<tool>. desktop.cua.call reaches every other tool the driver has.

Errors

A call that cannot run fails with a named reason:

An access change sent from Kortix can fail with:

Disconnect

• Desktop app: Your computer → Disconnect…, or Disconnect this computer… in the menu-bar or tray icon. Kortix removes the computer from every project and stops the service.
• Terminal: npx --yes @kortix/agent-tunnel@latest logout. The computer removes itself from Kortix with its own token, then deletes the local credential and access setting and removes the service. --keep-service keeps the service installed. If Kortix is unreachable, the computer stays listed in Kortix. Remove it there too, as the next item shows.
• From another device, for example for a lost computer: the project menu → Your computer → the computer’s ⋯ menu → Disconnect…, or Disconnect on its row under Customize → Connectors → Computers → Accounts. A desktop app still running on that computer shows Needs reconnect.
• A shared computer in one project: a member who manages connections selects Disconnect on its row. That removes the shared account from this project only. The computer stays connected.

To keep a computer connected but unused, set its access to Off.