Skip to main content
Devices let Tembo sessions work on your own machines. Connect a laptop, workstation, or server, and sessions you start can run commands and read or write files on it. On macOS, you can also watch and control the device’s screen from Tembo while the agent works. You manage devices in Settings > Devices in the dashboard.

​
Connect a device

You can connect a machine in two ways:
  • Desktop app: connect the computer you’re using with one click. Use this for your own laptop or workstation.
  • Tembo CLI: pair a machine from its terminal. Use this for servers, Linux boxes, and other machines without the desktop app.

​
Connect with the desktop app

  1. Open the Tembo desktop app.
  2. Go to Settings > Devices and click Connect this computer.
Sessions can use the computer while the desktop app is open. To disconnect it, click Disconnect on the same card. A computer can be connected to one workspace at a time. If it’s connected to another workspace, the button says Connect here, and connecting it disconnects it from the other workspace.

​
Connect with the CLI

​
Prerequisites

  • The Tembo CLI is installed on the machine you want to connect.
1

Get a pairing code

In the dashboard, open Settings > Devices and click Add device. The dialog shows two commands to run on your machine. The pairing code works once and expires after 10 minutes.
2

Pair the machine

Copy the first command from the dialog and run it on your machine. It includes your pairing code and your Tembo API URL:
The device is named after the machine’s hostname. Add --name <name> to choose a different name.
3

Start the device

Leave this command running. The device appears in Settings > Devices once it connects, and your sessions can use it while the command runs. Press Ctrl+C to stop it.
On a server, run tembo devices start under a process manager or terminal multiplexer, such as systemd or tmux, so it keeps running after you log out.

​
Use a device in a session

Ask Tembo to work on your machine in a session, for example “Run the test suite in ~/code/app on my laptop.” The agent can:
  • Run shell commands on the device in your login shell (PowerShell on Windows), starting in your home directory.
  • Read, write, and list files on the device.
  • Check the device’s operating system, user, home directory, and shell.
Commands run on your real machine with your user’s permissions. When more than one of your devices is online, mention the one you want by name. To see which devices a session can use, click + (New tab) in the session’s side panel and choose Devices.

​
Limits

​
View a device’s screen

You can watch and control the screen of a device you own, for example to follow along while the agent works or to finish a step yourself.
  • In a session: the first time the agent uses one of your devices, the session’s side panel opens a Device tab showing its screen. This doesn’t happen when you’re viewing the session in the desktop app on that same computer. To open a screen yourself, add the Devices tab and click View screen. Click Switch device in the tab to choose another device.
  • In settings: open Settings > Devices and click View screen next to an online device.
The device shares its screen only while you have it open, and stops shortly after you close it. Screen viewing works on macOS devices connected with the desktop app or the Tembo CLI. The first time, macOS may ask you to allow Screen Recording and Accessibility for Tembo: Screen Recording lets Tembo show the screen, and Accessibility lets you control it.

​
Access

  • Only you can use your devices. Other members of your workspace can see your devices in Settings > Devices, but their sessions can’t use them and they can’t view their screens.
  • Devices work in sessions you start in the Tembo app, for messages you type. Sessions started by agents or integrations can’t use devices, and neither can messages other members send in your sessions.
  • Disable a device to pause access. Turn off the device’s toggle in Settings > Devices to block requests without unpairing it. Workspace admins can also disable or remove any device.

​
Manage a device

Settings > Devices lists every device in your workspace with its owner, platform, how it’s connected (desktop app or CLI), and whether it’s online, offline, or disabled. To remove a device, open its menu and click Remove. If tembo devices start is running on the machine, it stops and deletes the machine’s local credentials. To use the device again, pair it again. On a machine paired with the CLI, show which device it’s paired as:
Remove the device from Tembo and delete its local credentials:
The CLI stores credentials in ~/.config/tembo-device/device.json ($XDG_CONFIG_HOME/tembo-device if XDG_CONFIG_HOME is set), or %APPDATA%\tembo-device\device.json on Windows. To store them somewhere else, set TEMBO_DEVICE_CONFIG_DIR or pass --config-dir <dir> to every tembo devices command.

​
CLI command reference

​
Troubleshooting

Pairing codes work once and expire after 10 minutes. Click Add device again to get a new code.
tembo devices start needs a paired device. Run the tembo devices pair command from Settings > Devices > Add device first.
The device is disabled. Turn on its toggle in Settings > Devices.
Make sure the desktop app is open or tembo devices start is running on the machine, and that the device is enabled in Settings > Devices. Devices are only available for messages you type in sessions you started in the Tembo app.
Screen viewing works on macOS devices only. On macOS, check that Tembo is allowed under Screen Recording and Accessibility in System Settings > Privacy & Security.