rmoted

README

rmoted

Rmote Daemon — a Go daemon that hosts resumable, multi-agent terminal sessions and exposes them over a clean REST + WebSocket API. Run it on any macOS or Linux host; drive it from the rmote CLI, the Rmote iOS app, the Rmote Mac app, or any client that speaks the protocol.

Each session is a real PTY running your shell or AI coding agent (Claude Code, Codex, Grok, Gemini, and more via a pluggable catalog). Sessions survive disconnects: clients reconnect through ring-buffer replay and lossless delta recovery, so closing and reopening a client never loses state.

Highlights

• Resumable agent sessions — PTY hosting with reconnect replay + delta sync.
• Multi-agent, catalog-driven — detect/enable Claude, Codex, Grok, Gemini, and any future agent via agents.json + rmoted agents enable|disable <id> (a universal off-switch across every surface).
• Hooks forwarder — agent lifecycle hooks (turn start/done, prompts, tool events) published to subscribers.
• Skills — per-agent skill scanners exposed via REST.
• Git, worktrees, usage/quota, plan-preview, orchestration events — first-class REST endpoints.
• Single static binary, CGo-free — darwin/{arm64,amd64}, linux/{amd64,arm64}.
• Apache-2.0.

Quick start

# Build + run in the foreground (listens on 127.0.0.1:17783 by default).
make run

# In another shell, drive it with the CLI:
rmote health       # version, port, detected agents
rmote sessions     # list live sessions
rmote              # attach to the active session (or create a shell)
rmote new claude   # start a Claude Code session and attach

Install the CLI:

go install github.com/8ugustdev/rmoted/cmd/rmote@latest

Install the daemon

The curl installer places the binary at ~/.rmote/bin/rmoted and registers the user service + daemon hooks without touching unrelated hooks in the same config:

curl -fsSL https://raw.githubusercontent.com/8ugustdev/rmoted/main/scripts/install-rmoted.sh | sh

Then:

"$HOME/.rmote/bin/rmoted" install   # set up the user service + hooks
"$HOME/.rmote/bin/rmoted" health

Add ~/.rmote/bin to PATH to drop the absolute path. On macOS, the generated LaunchAgent can bind a LAN interface so mobile clients can pair directly:

rmoted qrcode        # print a pairing QR for LAN clients

Keep the pairing secret private — every route except /api/health requires it. Use a host firewall when untrusted networks can reach a LAN-bound listener.

Uninstall

rmoted uninstall     # remove the user service + daemon-owned hooks (preserves state)

The rmote CLI

A terminal client for the daemon. Runs against the local loopback daemon by default (reads ~/.rmote/agent/secret); override with RMOTED_HOST / RMOTED_PORT.

Command	Action
rmote	Attach to the active (or most-recent) session; create a shell if none.
rmote health	Daemon version, port, detected agents, features.
rmote sessions	List live sessions (id, active, agent, command, path).
rmote new [command...] [-cwd DIR]	Create a session (default $SHELL) and attach.
rmote attach <session-id>	Attach to an existing session.

See docs/cli.md for details.

Clients

rmoted is a server. Clients connect over REST + WebSocket:

• rmote CLI — included here (cmd/rmote).
• Rmote iOS — the reference mobile client (separate project).
• Rmote Mac — the reference desktop client (separate project).
• Your own — the wire protocol is documented in the internal/ws package (protocol.go for frame definitions); rmote is a readable reference implementation.

State

Path	Purpose
~/.rmote/agent/secret	Auth secret (mode 0600). Required on all non-health routes.
~/.rmote/agent/agent.pid	Pidfile (managed by serve).
~/.rmote/agent/agent.log	Structured log (JSON, append-only).
~/.rmote/agent/agents.json	Desired enabled agent IDs (schema v1, mode 0600).

Inspect agent support without mutating config:

rmoted agents                # which agents are detected + enabled
rmoted agents list --json
rmoted agents doctor

Environment overrides: RMOTE_AGENT_DIR (state dir), RMOTE_AGENT_PORT (port), RMOTE_AGENT_BIND (listener address, e.g. 0.0.0.0), or rmoted serve --bind 0.0.0.0.

Auth model

/api/health is unauthenticated (clients probe it during discovery). Every other route requires Authorization: Bearer <secret> where <secret> is read from ~/.rmote/agent/secret. The secret is the actual auth boundary (loopback is reachable by any process on the shared host; macOS QR installs also accept LAN traffic).

Cross-compile

make dist
# → dist/rmoted-{darwin-arm64,darwin-amd64,linux-amd64,linux-arm64} + SHA256SUMS

Background notifications (optional)

rmoted can forward agent lifecycle events to mobile clients via Apple Push Notification Service. This requires a separately-operated APNs relay (not included in this repo) plus a publisher .p8 key. Without those, the daemon's APNs code is inert — it builds and runs normally; notifications simply don't fire. See internal/apns + internal/relayclient if you want to wire up your own relay.

License

Apache License 2.0. See LICENSE.