Skip to main content
Glama
JIA-ss

ai-remote

by JIA-ss
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

ai-remote

AI-native remote control across your devices, over encrypted P2P. Your phone, your tablet, your Mac, your PC — and your AI agent, connected through one shared control layer. Use the human apps to view and control your paired computers, or connect your existing MCP agent to do the work. Watch the screen, take over, and hand control back whenever you want.

Mac + Windows implemented · iOS / iPhone WIP · iPadOS / iPad WIP · Android WIP · Linux WIP

Across your devices

Platform

Role

Status

macOS / Mac

Host + desktop controller

Implemented; local Apple Silicon pairing, capture, input and H.264 stream acceptance. Mac setup

Windows / PC

Host + desktop controller

Implemented; Windows UIA and native input paths. Operations · Structured UI evidence

iOS / iPhone

Native mobile controller

WIP — SwiftUI/UniFFI source, device/simulator SDK builds and simulator UI tests; physical remote-control acceptance pending. Validation

iPadOS / iPad

Tablet controller

WIP — the iOS app targets iPhone and iPad; iPad layout and real-device acceptance pending. Source and builds

Android

Phone / tablet controller

WIP — planned; native app implementation pending.

Linux

Desktop host / controller

WIP — desktop support and platform acceptance pending.

Mobile devices are controllers for your computers. The project does not currently host a remotely controlled iPhone, iPad or Android device. Linux is a development target, not a supported desktop today.

NOTE

Pre-alpha; build from source. No signed release or App Store app is available. Mac acceptance used Apple Silicon and macOS 27; Intel Macs and older systems need runtime checks. Platform implementation, SDK builds and simulator tests have different validation scopes. See Mac evidence, Windows/Mac UI evidence and iPhone validation.

Related MCP server: rc-mcp

Paired devices, connected over P2P

Computer to computer. Phone or tablet to computer. Your agent to your paired hosts. The desktop apps, experimental iOS controller and MCP bridge share the Rust controller and encrypted QUIC transport. Pair by device identity, then reach the computers you trust — whether you drive them yourself or hand the tools to your agent.

  • P2P first. NAT hole punching attempts a direct device-to-device path. If a direct path is unavailable, an encrypted relay carries the traffic; it sees ciphertext.

  • Pair once, keep trust. One-time tickets and a matching safety code establish device identity. A fresh connection reattempts connectivity; pairing does not promise a permanent direct path.

  • No manual port forwarding or project cloud account in normal setup. Restrictive networks can still prevent a connection. Self-hosted relays can be configured on the host. Transport architecture

AI-native, from protocol to control

Bring the agent you already use: Codex, Claude Code, Cursor, VS Code, or any stdio MCP client. One MCP bridge exposes your paired computers as tools; no ai-remote hosted model is required.

Capability

What your agent can do

Native MCP

Discover and call remote tools through the local stdio bridge; reach multiple paired hosts from one client configuration. Client setup

Structured UI

Read native macOS AX / Windows UIA trees and act on elements with ui_tree, ui_read and ui_action, alongside screenshots. UI contracts

Computer tools

Capture screens, inspect windows, send mouse/keyboard input, run shell/background jobs and copy files at the permitted access level, from an agent or straight from a terminal (ai-remote exec, job, shot, push, pull). Tools · Command line

Shared human / agent control

Watch live video and activity. Taking over stops agent control calls; handing back lets the agent resume. Control and approvals

Extensible integrations

Mount existing local MCP servers with a pinned executable and an explicit tool allowlist.

The host checks access level, turn, policy and approval before executing tools. You decide which computers the agent can reach and what it can do on each one.

Desktop stream presets request 1080p30, 1080p60 or 4K30 and show actual decoded resolution/frame rate and received bitrate. macOS 13+ uses native ScreenCaptureKit and VideoToolbox hardware encoding (HEVC or H.264 High, the display's refresh rate, up to 8K for HEVC), with software fallback. Measurements and limits separate encoder benchmarks from live remote performance; presets are requested limits, not guaranteed throughput.

Start from source

You need the pinned Rust toolchain (1.95.0). The desktop app also needs Node/npm and the platform's native development tools.

git clone https://github.com/JIA-ss/ai-remote.git
cd ai-remote
cargo install --path crates/ai-remote --locked

On macOS, build and open a development app with its CLI included:

tools/macos.sh build --debug --bundles app
open target/debug/bundle/macos/ai-remote.app

On the computer to control, run the installed CLI (make sure Cargo’s bin directory is on PATH):

ai-remote host
# In another terminal on that computer (or in the desktop app: This device → Show pair code):
ai-remote pair-code --level control

It shows a QR code and an eight-digit pair code. Scan the QR code with the iPhone app, or type the digits on the controller computer (the desktop app's Pair a computer page, or the CLI):

ai-remote pair 4821 0937 --name office-pc
ai-remote call system_info --host office-pc

Compare the same three-word safety code on both devices. On a Mac host, grant Screen Recording and Accessibility to the actual running executable, restart it, and run ai-remote doctor. A locked or unauthorized desktop must be repaired before capture/input, not worked around. Detailed operations

Connect your agent

In the desktop app, open Settings → Agents, choose your MCP client, then copy its setup. The app supplies the actual executable path and the current pairing profile, including when the CLI lives inside the Mac bundle.

If ai-remote is on PATH, the basic commands are:

# Claude Code, available across your projects
claude mcp add --transport stdio --scope user ai-remote -- ai-remote mcp
# Codex
codex mcp add ai-remote -- ai-remote mcp

Cursor uses mcpServers JSON in ~/.cursor/mcp.json. VS Code uses servers JSON in its MCP configuration. Codex also supports [mcp_servers.ai-remote] in ~/.codex/config.toml. Paths, quoting and exact examples: MCP client setup.

Then give the agent the working method: skills/ai-remote/SKILL.md tells it how to start a session, look, act, run commands and files, and what levels, approvals, refusals and the owner taking over mean. Copy the folder to ~/.claude/skills/ for Claude Code, or paste it into any other agent's rules.

Your computers, your rules

Level

Allowed tools

observe

Screen, window list, system info and permitted read-only integrations

control

Observe plus mouse, keyboard and clipboard

admin

Control plus shell, background jobs and files; risky calls ask first

High-risk steps wait for owner approval. An unanswered request is denied. Every decision and outcome goes to the host's audit log. Revoke/unpair a device to remove its access. On a machine you only drive yourself, bypass (set at that machine: ai-remote bypass on <controller> or the app's device settings) trusts chosen controllers with everything: every tool, no approvals. Bypass

Allowing remotely currently requires Windows Hello. Mac and iPhone controllers can deny; their Touch ID / Face ID signing backends are not implemented. The native host prompt remains an approval path when the host's desktop is usable. Approval design

Questions people ask

Can my iPhone control my computer? That is the purpose of apps/ios: native SwiftUI UI over the shared Rust controller. The source includes pairing, video, touch/text, takeover and activity. Device and arm64 simulator builds pass with the iOS SDK, as do simulator startup, invalid-ticket, background/resume and relaunch tests. Live control on a physical iPhone still needs acceptance.

Can an agent control my iPhone through this app? No. The iOS source is a controller, not an iPhone host.

Do I need port forwarding or an ai-remote cloud account? No manual port-forwarding or project cloud account is part of normal pairing. Network restrictions can still make a peer unreachable; the tool reports that rather than guaranteeing every network works.

Does it include a native accessibility tree or file manager? The core includes native Mac AX and Windows UIA trees and element actions, alongside screenshots, input and windows. See structured UI contracts and acceptance. File transfer remains planned.

Where are the binaries? No signed release is published yet. Build from source; Windows, Intel Mac, iPhone signing and notarization have separate verification needs.

Development and evidence

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
node --test tools/mcp-install.test.mjs

Mac acceptance · iPhone validation ledger · Tool reference · Security · Contributing

Roadmap

Stage

Next work

M0–M2

Continue Windows/Mac acceptance, improve capture performance, complete file/accessibility work and signed packaging

M3

Mobile controllers: iOS/iPhone and iPadOS/iPad acceptance, Android implementation; Face ID signing, QR pairing and notifications

Platform expansion

Linux desktop host/controller support and acceptance

M4

Optional self-hosted account/relay services and device sharing

License

AGPL-3.0. The official project is JIA-ss/ai-remote.

Available Tools

2 tools
list_hostsA
Read-onlyIdempotent

List the computers paired with this machine, whether each is reachable now, and whether the connection is direct or relayed.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value beyond that by disclosing that results include live reachability and connection type (direct vs relayed), which tells the agent the call surfaces current network state rather than static configuration.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; every clause conveys distinct, actionable information (inventory, reachability, connection mode).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description carries the burden of describing return content and does so for the three key fields. It could go slightly further on output shape (e.g., per-host naming/grouping) or latency, but it is adequate for an agent to call correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is an empty object and the description correctly implies no inputs are required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('List') plus a precisely scoped resource ('computers paired with this machine'), and it names the returned attributes (reachability, direct vs relayed). It does not explicitly contrast with the sibling use_host, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The purpose implies when to use it (checking paired-device inventory and connectivity), but there is no explicit guidance about when to prefer this over use_host or what to do after obtaining a reachable host. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

use_hostA
Idempotent

Make a host the default for later calls in this session and return its system_info.

ParametersJSON Schema
NameRequiredDescriptionDefault
hostYesName of a paired host (see list_hosts).

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and idempotentHint=true, and the description adds genuinely new behavioral context: that the change persists as a session default for subsequent calls, not just this one. It also discloses that system_info is returned, though it says nothing about failure modes for an unknown/unpaired host.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that conveys the action, its persistent scope, and its return value with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool this covers the essential behavior: the session-level side effect and that system_info comes back. Return contents are unspecified, but with no output schema a brief hint is a reasonable level of detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the host parameter is documented there with a pointer to list_hosts for valid names. The description adds no further detail on the parameter (e.g., case sensitivity or accepted formats), so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (make a host the default) plus the return value, and makes the session-scoped nature of the effect explicit. It does not name list_hosts as the contrasting retrieval tool in the description itself, so sibling differentiation is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'for later calls in this session' implies when this is useful, but there is no explicit when-to-use/when-not guidance or statement of how it relates to list_hosts. Usage must be inferred from the side-effect phrasing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observedlist_hosts
    • First observeduse_host

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation4/5

The tools are mostly distinct: list_hosts is read-only discovery, while use_host changes session default. There is some overlap because use_host also returns system_info, but the purposes remain separable.

Naming Consistency5/5

Both tools follow a clear verb_noun snake_case pattern: list_hosts and use_host. The convention is consistent and predictable.

Tool Count2/5

Two tools is too thin for a remote-host management server. A useful surface would likely include commands to connect, execute, inspect, or manage host pairings.

Completeness2/5

The surface only supports listing hosts and setting a default. There is no way to execute commands on a host, pair/unpair hosts, disconnect, or perform the apparent core remote operations, leaving significant dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • rc-mcp

    champi-ai
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables controlling your own Linux desktop machines from any MCP-capable LLM client, with opt-in agent capabilities for shell, filesystem, processes, screenshots, system info, and input injection.
    1
    MIT
  • FlashDesk by flashdesk

    FlashDeskofficial

    flashdesk
    A
    license
    Not graded
    quality
    C
    maintenance
    Control another PC's desktop from Claude Code via MCP — screenshot, mouse, keyboard, SSH, file transfer. For GUI work SSH can't reach on a remote machine; the remote PC approves each connection. Not Remote Control of your own Claude session.
    MIT

  • Localbridge-MCP

    danielcanfly
    A
    license
    A
    quality
    A
    maintenance
    LocalBridge MCP is a bridge between an online AI chats and your computer. Most online AI chats can reason, and write code, but they normally cannot touch the local files, terminals, and scripts that make real work happen. This gives a trusted assistant a controlled doorway into a machine you own, so it can inspect files, edit text, search a project, run tests, use Git, and operate a shell.
    17
    3
    Apache 2.0