> ## Documentation Index > Fetch the complete documentation index at: https://docs.tembo.io/llms.txt > Use this file to discover all available pages before exploring further. # Devices > Connect your computer or a server to Tembo so sessions you start can run commands, work with files, and show you its screen. 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](https://app.tembo.io). ## 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](https://tembo.io/download). 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](https://docs.tembo.io/features/cli.md) is installed on the machine you want to connect. **1. Get a pairing code** In the [dashboard](https://app.tembo.io), 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: ```bash theme={null} tembo devices pair --api-url ``` The device is named after the machine's hostname. Add `--name ` to choose a different name. **3. Start the device** ```bash theme={null} tembo devices start ``` 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 | Operation | Limit | | - | - | | Command timeout | 2 minutes by default, up to 10 minutes | | Command output | 1 MB each for stdout and stderr; anything longer is truncated | | File reads | Files up to 10 MB | | Directory listings | Up to 2,000 entries | ## 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: ```bash theme={null} tembo devices status ``` Remove the device from Tembo and delete its local credentials: ```bash theme={null} tembo devices unpair ``` 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 ` to every `tembo devices` command. ## CLI command reference | Command | Description | | - | - | | `tembo devices pair --api-url [--name ]` | Pair this machine using a code from **Settings > Devices > Add device**. | | `tembo devices start` | Connect to Tembo and handle requests from your sessions until stopped. | | `tembo devices status` | Show the paired device's ID, name, and API URL. | | `tembo devices unpair` | Remove this device from Tembo and delete local credentials. | | `tembo devices --help` | Show device commands and options. | ## Troubleshooting > [accordion] This pairing code is invalid, expired, or already used > > Pairing codes work once and expire after 10 minutes. Click **Add device** again to get a new code. > [accordion] This machine is not paired > > `tembo devices start` needs a paired device. Run the `tembo devices pair` command from **Settings > Devices > Add device** first. > [accordion] Connected, but requests are blocked > > The device is disabled. Turn on its toggle in **Settings > Devices**. > [accordion] A session says no device is online > > 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. > [accordion] The screen doesn't show > > Screen viewing works on macOS devices only. On macOS, check that Tembo is allowed under **Screen Recording** and **Accessibility** in **System Settings > Privacy & Security**. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.