arc

Agent remote control. Let an AI agent on one machine (e.g. Claude Code on macOS) drive another machine (e.g. Windows) over an encrypted link — build and run apps, operate GUIs, move files — through semantic, structured tools, not a pixel stream.

It is not a remote desktop: there's no screen-sharing for humans. The agent calls tools — run a command, list/click UI elements, type, screenshot, transfer files — over an end-to-end-encrypted channel. Part of agent-rt (rt = runtime).

Install

Controller (macOS / Linux) — the arc CLI, which is also the MCP server:

brew install agent-rt/tap/arc

Runner (Windows) — the machine being driven:

winget install agent-rt.arc-runner

Quickstart

Over Tailscale (recommended — no relay, no pairing code to copy):

On the Windows runner, register it (autostarts at logon). On Tailscale it's one flag — --tailscale auto-detects the tailnet IP and restricts access to this machine's Tailscale owner:
```
arc-runner install --tailscale
```
(Equivalent to --listen :8787 --trust-tailnet --allow , still passable explicitly; --allow-any permits any tailnet peer, --port changes the port, --dry-run previews.) It mints credentials and prints a ready-to-paste [targets.win] block.

On the controller, drop that block into ~/.config/arc/config.toml:

default = "win"

[targets.win]
direct = ":8787"
trust_tailnet = true

Drive it:
```
arc -t win shell --cmd 'ver'
```

arc-runner uninstall removes the task; arc-runner upgrade self-updates it to the latest release (download → validate → swap → restart). For relay mode instead of Tailscale, use arc-runner install --relay .

> Coming from ssh + scp? See docs/from-ssh.md for a > side-by-side migration of the common workflow.

Usage

arc shell --cmd 'dotnet build'      # run a command (streams live; --timeout )
arc run ./fix.ps1 -Port 8788        # ship &amp; run a local script (.ps1/.bat); args pass through
arc push ./app C:/work/app          # send a tree up (incremental, .gitignore-aware)
arc watch ./app C:/work/app --on-change 'cargo build'   # auto-push + rebuild on every save
arc pull C:/work/app/bin ./bin      # fetch a tree (or file) back
arc cat C:/work/app/log.txt         # print a remote file
arc tail C:/work/app/log.txt -f     # follow a remote log (streams new lines)
arc shot ui.png --launch notepad    # launch → wait for render → screenshot, one shot
arc screencap shot.png --window N   # screenshot to a file (.png/.webp by extension)
arc screencap now.png --window N --baseline before.png --diff diff.png   # regression diff
arc windows --filter notepad        # list top-level windows (--json for structured)
arc elements  --json          # list a window's UI Automation elements
arc find  --type Button --name Save   # query elements by attribute (no full dump)
arc wait  --name Done --timeout 30     # block until a matching element appears
arc open notepad                    # launch an app
arc activate                  # restore + foreground a window (before capture/input)
arc ps notepad                      # list remote processes; arc kill 
arc click               # click a UI element (from `elements`)
arc read                # read one control's text (verify without a screenshot)
arc set  'text'         # set a control's value directly
arc type 'hello' --into    # focus an element, then type into it
arc type "$(cat big.txt)" --into  --paste   # paste long text via clipboard (fast)
arc key ctrl+a delete --into    # key chords in sequence (--into focuses an element first)
arc mouse drag 40 80 300 400        # move / click / down / up / scroll / drag
arc clip get                        # read the remote clipboard; arc clip set 'text'
arc agents-md                        # full Markdown command reference for an AI agent

Connecting

arc finds a runner via a saved named target (-t , or the config's default), explicit flags (--direct / --relay / --session / --pairing), or env vars (ARC_DIRECT / ARC_RELAY_URL / ARC_SESSION / ARC_PAIRING). Config lives in ~/.config/arc/config.toml:

default = "win"

[targets.win]                  # Tailscale-direct, identity-authenticated
direct = "100.x.y.z:8787"
trust_tailnet = true

[targets.public]               # over a relay
relay   = "wss://relay.example/v1/relay"
session = "0011…ffff"
pairing = "XXXX-XXXX"

Files & the dev loop

push/pull are direction-by-verb (controller→runner / runner→controller). A single file is copied wholesale; a directory transfers incrementally — content-hashed with one round-trip to skip unchanged files, never walking build dirs (target/bin/obj/…). Flags: --delete (mirror the source), --dry-run, --whole (skip the diff). arc watch keeps a tree mirrored live (debounced, build-churn-ignoring); add --on-change '' to rebuild on the box after every sync — a zero-ssh edit → build → run → screenshot loop. To run a local script on the box, arc run ./script.ps1 [args] ships its contents and executes it (interpreter by extension; .ps1 runs with -ExecutionPolicy Bypass) — no push first, no cross-shell quoting to escape, args passed straight through.

> The model is code lives on your Mac; the Windows box is a build/run > container. With Windows App SDK 2.x an unpackaged WinUI 3 app builds with > just the .NET SDK (no Visual Studio), so a fresh runner + .NET SDK builds WPF / > WinForms / console / WinUI 3.

MCP

The same arc binary runs as a stdio MCP server with arc --mcp, exposing every capability as a tool (run_command, run_script, screenshot, list_windows, list_elements, find_elements, click, type_text, set_value, read_file, write_file, …). Register it with, e.g., mcpctl:

mcpctl server add arc --command arc --args --mcp \
  --env ARC_DIRECT=:8787 --env ARC_PAIRING=XXXX-XXXX

It connects lazily on the first tool call and reconnects on drops. run_command streams output (relayed as MCP progress when the client supplies a progressToken), so an agent can watch a long build in real time.

Modes

The relay exists to solve NAT traversal; on a shared private network it's unnecessary.

Direct (recommended on Tailscale / LAN): the runner listens (arc-runner --listen :8787) and the controller dials it — no relay, no extra process, lower latency.
Relay: both peers dial an arc-relay, which matches them by SessionId and forwards opaque ciphertext (it holds no key).
Trusted-tailnet auto-pairing (trust_tailnet = true): the runner authenticates each caller by verified Tailscale identity (tailscale whois, optionally restricted to allow_logins), so no pairing code is exchanged — authentication is the WireGuard transport plus identity, with a fixed public key for the (defense-in-depth) Noise channel.

Architecture

 controller (macOS/Linux)        relay (optional)           runner (Windows)
┌────────────────────┐  wss  ┌──────────────┐  wss  ┌──────────────────────┐
│  arc  /  arc --mcp  │──────►│  arc-relay   │──────►│  arc-runner          │
│  (CLI / MCP server) │◄──────│ opaque relay │◄──────│ shell·UIA·input·     │
└────────────────────┘       │  (no key)    │       │ screenshot·files     │
         └────────── L2: Noise channel, end-to-end encrypted ──────────┘

L1 — relay (proto::relay): Hello + SessionId + Role, then opaque Relay{data} frames forwarded between the session's two peers. Zero-knowledge. Skipped entirely in direct mode.
L2 — end-to-end (proto::wire): Request / Response / Event carrying Commands, sealed in a Noise channel (proto::crypto) and chunked through the 32 MiB frame cap.

Both transports share one Session (arc-net), used by the CLI, the MCP server, and the runner.

Capability tiers (by session state)

Capability	Mechanism	In a detached session?
`list_*`, `set`, element `click`	UI Automation (COM)	✅ works
single-window `screencap`	GDI `PrintWindow`	✅ works
`type`, `key`, coordinate `mouse`, full-screen `screencap`	`SendInput` / DXGI	⚠️ needs an active console/RDP session

UIA pattern-based control works headlessly; raw input and full-screen capture need a connected desktop. ElementId is ":", resolved by RuntimeId identity — it keeps pointing at the same control across tree changes, or returns NotFound.

The runner serves requests concurrently (a hung command never blocks the link or other commands) and enforces a default 10-minute command deadline (--timeout ; 0 to disable).

Security

The relay sees only ciphertext. The low-entropy pairing code is never used as a key directly: both peers run a symmetric SPAKE2 PAKE to derive a high-entropy key that keys Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s. Recording the handshake gives no offline dictionary attack; a wrong code makes the Noise handshake fail. In trust_tailnet mode the boundary is Tailscale ACLs plus verified identity.

The Windows binaries are code-signed — see the code signing policy (free certificate courtesy of the SignPath Foundation).

Build from source

just build      # release `arc` (CLI + MCP server)
just lint       # clippy -D warnings (host crates)
just test

Crate	Role
`arc-proto`	wire protocol, CBOR framing, Noise channel (chunked), SPAKE2
`arc-net`	shared client transport — relay/direct `Session`
`arc-relay`	zero-knowledge `wss` relay (`axum`)
`arc-runner`	Windows runner: shell, screenshot, UI Automation (`windows-rs`), input (`enigo`) — Windows-only
`arc-cli`	the `arc` binary: CLI and `arc --mcp` server

arc-runner builds only on Windows (windows-rs, xcap); the controller crates build everywhere. Release/packaging is in RELEASING.md.

License

Licensed under either of MIT or Apache-2.0 at your option.

arc runner agent-rt

README

arc