Jian Remote
Install and operate the worker that connects another computer to your gateway.
Jian Remote is the machine worker, published as @jian-ai/remote-control with the jian-remote command. It connects a Windows, macOS, or Linux computer to a gateway using outbound HTTPS polling. You do not need to expose an inbound worker port or set up SSH for this protocol.
The agent continues to run on the gateway. The worker executes requested tasks on its computer and sends results back. The gateway keeps the conversation and task state.
Choose an installation path
| Path | Appropriate when |
|---|---|
| Desktop app's computer-sharing feature | Jian is already installed on this computer and connected to the server |
Standalone jian-remote service | A machine needs to serve agents independently of the desktop app |
Avoid registering the same computer twice without a reason: two worker records with similar names make targeting ambiguous. The desktop's sharing switch manages app-owned workers, not an independently installed CLI service.
Install the standalone worker
Requirements: Node.js 24+, npm, an account allowed to run the tasks, and HTTPS reachability to the gateway's public base address.
- In the gateway panel, open Settings → Machines and add a machine with a recognizable name, such as
Mira workstation. - Jian displays its machine ID and a newly generated worker credential. The credential is shown at creation or rotation; keep it private.
- Run the install command on the computer you want agents to use.
The panel gives a command populated for your installation. The equivalent interactive form avoids placing a token in command history:
npm install -g @jian-ai/remote-control
jian-remote install \
--gateway https://jian.example.com \
--machine 11111111-1111-4111-8111-111111111111 \
--token-promptThe UUID above is fictional. Replace it with the panel's machine ID and enter that machine's worker token at the hidden prompt. The installer also supports --token-stdin for controlled automation and --token for the generated command.
The worker token is not the host owner token. It identifies a particular machine to the worker endpoints. Do not use a provider API key here.
Service lifecycle
| Platform | Normal installation |
|---|---|
| macOS | Per-user LaunchAgent |
| Linux | systemd --user; a system-unit fallback is available on headless/root hosts without a user bus |
| Windows | Task Scheduler task at user logon |
Per-user services normally become available after that user signs in following a reboot. Linux supports install --system for the system-service case; use the account and permissions appropriate to that host.
jian-remote version
jian-remote stop
jian-remote start
jian-remote restartThe installer keeps configuration under ~/.config/jian-remote, with owner-only permissions or the corresponding Windows ACL. Do not publish the directory or paste its contents into support reports.
Check the connection
The Machines page reports whether the worker is online, its OS/architecture, capabilities, version, and whether it needs an update. Choose that machine as the conversation's target, then ask for a harmless read-only check such as the current directory and OS version.
An online worker proves it can poll the gateway. It does not prove that desktop permissions, a particular command, or an external service work. Verify those with their own results.
Update and compatibility
A published worker and gateway must share their major.minor line. A mismatched worker can still connect and show Update needed, but it accepts only an update task until compatible.
The worker does not independently auto-update. Use Update in Machines, ask the agent to use update_remote_machine, or run:
jian-remote updateThe command can take --version for a specific release. Normal updates follow the gateway release, install through npm, refresh the service installation, and retain credentials. Panel/agent updates require an npm-installed worker advertising update support. App-managed workers are maintained with the desktop application.
Rotate credentials or change address
Rotate the worker token in Machines, then apply the new value on the machine:
jian-remote configure --token-prompt
jian-remote configure --gateway https://jian.example.com --token-promptconfigure updates stored values and restarts the existing service. The standalone CLI requires an HTTPS gateway URL without credentials, query parameters, or a fragment. A token rotation invalidates the old credential; it is not a second active credential for the same worker.
Execution and limits
All agents on that gateway can use connected machines. Tasks run with the OS privileges of the account running the worker; the remote computer is not the profile workspace sandbox.
| Operation | Agent tool | Important limit |
|---|---|---|
| Shell | run_remote_command | PowerShell on Windows, /bin/sh on macOS/Linux; default 30 seconds, maximum 120 seconds |
| Desktop | remote_computer | Native helper and OS desktop permissions; primary display |
| Read a file into conversation media | pull_remote_file | Small, size-capped transfer |
| Write a file | push_remote_file | Size-capped UTF-8 or base64 payload |
| Update npm worker | update_remote_machine | Requires the worker's update capability |
The worker result's stdout is capped at 400,000 characters. Binary results use base64, so screenshot/file transfers are roughly limited to 300 KB of binary data, with screenshots scaled or recompressed to fit. This is separate from the larger normal media upload limit. Arrange larger transfers through an authorized file-sharing method.
See Computer Use for screenshots, screen coordinates, permissions, and platform limitations.
Implementation reference
Worker guide, CLI credential handling, and machine/task contracts.