import { Callout } from 'nextra/components';

Remote Device Tool

The Remote Device tool lets a DocsGPT agent run shell commands on a machine you control, such as a server, a Raspberry Pi, or your own laptop. You install docsgpt-cli on that machine, run it in host mode, and pair it with your DocsGPT account. The paired device then shows up as a tool you can attach to any agent.

The machine connects outward to DocsGPT, so it works behind NAT or a firewall without opening any inbound ports.

How it works

1. You run docsgpt-cli host on the target machine. It pairs to your account and keeps a lightweight connection open: it polls while idle and streams while a command is running.
2. When an agent calls the device's run_command action, DocsGPT sends the command down to the daemon.
3. The daemon runs the command locally, streams stdout and stderr back, and the agent uses the output to continue.
4. Every invocation is recorded in the device's activity log.

Prerequisites

• docsgpt-cli installed on the machine you want to control. See the installation instructions: download a binary from the releases page, use Homebrew (brew tap arc53/docsgpt-cli && brew install docsgpt-cli), or build from source.
• Outbound internet access from that machine to your DocsGPT instance.

Pair a device

Pairing uses a short one-time code (a device-code style flow).

1. In DocsGPT, go to Settings -> Tools, click Add tool, and choose Remote Device.
2. Give it a name, an optional description (the agent sees this, so describe what the machine is for), and pick an approval mode. DocsGPT then shows a pairing code such as ABCD-WXYZ and the command to run.
3. On the target machine, run:
   bashCopy

   docsgpt-cli host pair --url https://your-docsgpt-instance
   

   Enter the code when prompted. (Omit --url to use the default cloud instance.)
4. The UI switches to "Paired" once the code is redeemed. If you ran the command at a terminal, the CLI then offers to start the daemon or install it as a service.

Run the daemon

Start it in the foreground:

docsgpt-cli host

You will see a startup banner, then periodic "idle" heartbeats. Press Ctrl-C to stop.

To keep it running across reboots, install it as a service:

# Linux (systemd). As root this installs a system service; otherwise a user service.
docsgpt-cli host install-service

# macOS (launchd). The default is a per-user LaunchAgent that starts on login.
docsgpt-cli host install-service

# Always-on machine that starts at boot (Linux example):
sudo docsgpt-cli host install-service --system --user $USER

Remove the service with docsgpt-cli host uninstall-service.

Approval modes

The approval mode is set per device, either in the pairing form or later on the device's page under Settings -> Tools. There are two modes:

• Ask (default): every command pauses for your approval before it runs. You approve it from the chat. You can also choose "approve and don't ask again" to auto-approve that command pattern in the future.
• Full access: commands run without asking.

Compound commands are split on operators such as &&, ||, ;, and |, and each part is checked on its own, so a dangerous part cannot be hidden behind a safe one.

Attach to an agent

A paired device behaves like any other tool. Open or create an agent, add the device from the tool picker, and the agent can call its run_command action. The picker shows whether the device is currently online.

If you attach more than one device to an agent, give each a clear description so the agent can pick the right one.

Manage a device

Open the device from Settings -> Tools to:

• See its status (online or offline, with last-seen time), host, OS, and CLI version.
• Change its name, description, or approval mode.
• View recent activity (the command audit log).
• Revoke it.

From the CLI:

docsgpt-cli host status   # live status from the server
docsgpt-cli host revoke   # revoke on the server and clear local state
docsgpt-cli host reset    # clear local pairing only (leaves the server-side device)

Revoking a device stops its daemon: the next time it checks in it sees the revocation, prints a message, and exits. Under a service manager it will not be restarted.

Security notes

• The machine connects outward only. No inbound ports are opened.
• Each device has its own token, stored hashed on the server and revocable at any time.
• Prefer Ask mode for any machine with sensitive data on it. Use Full access only on machines you are comfortable letting an agent drive unattended, and remember that the denylist is the only automatic guard in that mode.
• Every command is logged on the server and visible in the device's activity log.