🤖 remote-agent

remote-agent is a tool for remotely operating coding agents such as Codex, Claude Code, Cursor CLI, and other agent CLIs from a single web interface. Run the remote-agent server on your own machine, then connect from a client device such as iOS, Android, another desktop browser, or an installed PWA to start sessions, resume work, approve tool requests, and interact with your agents.

Requirements

• Node.js v24 and npm-compatible npx on the server machine.
• The agent account/CLI you want to use must be authenticated on the server machine as that agent normally requires. Built-in ACP adapter packages are bundled with remote-agent.

Installation

Quick Start: PWA with Tailscale(Recommended)

remote-agent works best when installed as a PWA from a secure Tailscale URL. PWA installation is strongly recommended for notifications and the mobile experience. To install and use the PWA, the client must access remote-agent through HTTPS.

Start remote-agent with the Tailscale setup helper:

npx -y @kimuson/remote-agent@latest serve --tailscale --port 48989

This command starts the remote-agent SPA/PWA and API server on port 48989, configures Tailscale Serve for https://<magic-dns-name>:48989, then prints the URL and a QR code.

Tailscale Serve may need to update HTTPS certificate settings. If the command asks for your sudo password, enter it to continue. After setup completes, open the printed URL or scan the QR code from the client device, then install the PWA from the browser.

QuickStart: Same-LAN Mobile Setup

For quick access from a phone or tablet on the same Wi-Fi/LAN without Tailscale, use Same-LAN mode:

npx -y @kimuson/remote-agent@latest serve --same-lan --port 4445

Same-LAN mode listens on 0.0.0.0, generates a local CA and HTTPS certificate, advertises a .local HTTPS URL on the LAN, and prints a QR code for the mobile setup page. The setup page first opens over HTTP on the private IP so the phone can download the CA certificate, then guides you to trust it and open the HTTPS/PWA-capable URL.

Same-LAN is intended for trusted private networks only. Do not use it on public or untrusted Wi-Fi unless you understand the risk. --same-lan and --tailscale are mutually exclusive.

Manual Setup

The serve command starts both the client SPA/PWA and the API server:

npx -y @kimuson/remote-agent@latest serve

By default, the server listens on HTTP. If you do not use --tailscale, you are responsible for providing secure communication between the client and the server. This can be a local setwork, a VPN, a reverse proxy, or a tunnel such as Cloudflare Tunnel in front of the local remote-agent server.

Running remote-agent on a public hostname is not the recommended default. If you do expose it, set an API key and only share the URL with trusted users. You can generate an API key with:

npx -y @kimuson/remote-agent@latest generate-api-key

Then pass it to the server:

RA_API_KEY='<generated-api-key>' RA_ALLOWED_IPS='x.x.x.x,y.y.y.y' npx -y @kimuson/remote-agent@latest serve

Then clients must send the API key as a bearer token for /api/* requests. You can also restrict accepted client IPs with RA_ALLOWED_IPS.

Features

• 🤖 Multi-provider support: built-in providers for Codex, Claude Code, GitHub Copilot CLI, pi-coding-agent, Cursor CLI, and OpenCode. Any ACP-compatible agent can also be added as a custom provider.
• 🌐 Browser/PWA client: the client is served as an SPA and works through a browser on any OS. Install it as a PWA for an app-like experience.
• ⚡ Real-time preview: stream agent output as it is produced.
• 🛠️ Visual tool viewers: inspect common tool calls such as Bash, Read, Write, and Edit with terminal, file, and diff viewers.
• ✅ Tool approval: approve or reject tool-approval requests from supported agents.
• 🧱 Sandboxed execution: optionally run agent CLIs through srt sandboxing with global, project-level, and per-session controls.
• 🔔 Notifications: receive task-completion and approval-request notifications. When installed as a PWA, device notifications are available through the service worker.
• 🔊 Completion sound: play an audible notification when an agent task finishes.
• ✍️ Efficient prompt input: use agent command completion, file-path completion, voice input, and image attachments.
• 🎚️ Model and mode controls: switch supported providers' model/mode from the UI, remember the last used choices per project/provider, and pin favorite models.
• 🧑‍💻 Code review: open a GitHub-like diff viewer, leave line comments, and seamlessly turn them into review instructions for the agent.
• 🌿 Git worktree support: start sessions in a selected worktree. Supports .worktreeinclude, optional setup scripts, and preserving subpaths when starting from a subdirectory in a monorepo.
• ⏰ Routines: run agents on cron schedules or at a specified datetime.
• 🔐 Authentication: supports API key authentication and IP address restrictions.

Configuration

remote-agent is configured with CLI flags and environment variables.

Environment variable	CLI flag	Default	Description
PORT	--port	8989	HTTP port for the remote-agent server.
RA_DIR	--ra-dir	~/.ra	Directory for the SQLite database and app state.
RA_API_KEY	--ra-api-key	-	Bearer token required for /api/* requests. If unset, API key auth is off.
RA_ALLOWED_IPS	--ra-allowed-ips	-	Comma-separated IP allowlist checked via X-Forwarded-For / X-Real-IP.
RA_ALLOWED_ORIGINS	--ra-allowed-origins	-	Comma-separated CORS origin allowlist for /api/* requests.
-	--server-only	false	Start only the API server without serving the client build.
-	--same-lan	-	Serve HTTP/HTTPS on one LAN port and print a mobile certificate setup QR.
-	--tailscale	-	Publish through Tailscale Serve. Use --port for the HTTPS port.

When both an environment variable and a CLI flag are provided, the CLI flag takes priority.

Available Providers

remote-agent includes built-in provider presets for these agent CLIs:

Provider	Preset ID	Log import
Codex	codex	✅
Claude Code	claude-code	✅
GitHub Copilot CLI	copilot-cli	❌
pi-coding-agent	pi-coding-agent	✅
Cursor CLI	cursor-cli	❌
OpenCode	opencode	❌

remote-agent does not require you to install built-in ACP adapter packages separately. Make sure the agent account or underlying CLI credentials you want to use are available on the server machine and authenticated as that agent normally requires.

Warning

Do not use Claude Code through remote-agent with a Claude subscription account. remote-agent only connects to a local CLI process, so it may technically work with subscription-based Claude Code authentication. However, Claude Code ACP is implemented through Agent SDK, and Anthropic does not allow Claude Code subscription access to be used from third-party tools. Use provider authentication only when it is permitted by the provider's current terms.

Custom Provider

Want to use another agent? Add it as a Custom Provider through ACP.

See the ACP agent list at https://agentclientprotocol.com/get-started/agents to find an available agent. If the agent you want is not listed, implement an ACP-compatible agent server and register its command as a Custom Provider.

Sandboxed Agent Execution

remote-agent can launch agent CLIs through @anthropic-ai/sandbox-runtime (srt) so agent processes run with explicit filesystem and network rules.

Sandboxing is opt-in and has three layers:

1. Global Settings → Sandbox: choose which provider presets are allowed to use sandboxing and define global filesystem/network rules.
2. Project Settings → Sandbox: enable sandboxing by default for that project and add project rules. Relative paths are resolved from the session working directory.
3. New session toolbar: toggle sandboxing for an individual session before it starts.

Filesystem rules support read/write allowlists and denylists. Network policy can be unrestricted (none) or restricted to an allowlist of domains. Project network policy can inherit the global policy, override it with its own restricted allowlist, or disable network restriction for that project.

For agent runtime files, remote-agent automatically grants read access to common local agent configuration directories such as ~/.codex, ~/.pi, ~/.claude, ~/.github, and ~/.copilot. Provider-specific writable runtime directories are added where needed, such as ~/.codex for Codex and ~/.pi for pi-coding-agent. The default write allowlist includes the session working directory (.).

Sandboxing is a defense-in-depth feature, not a replacement for normal security controls. Keep using private networks, API key authentication, IP restrictions, and trusted agent credentials.

How It Works

remote-agent keeps ACP sessions on the Node.js server instead of starting local agents directly from the browser. The browser SPA talks to the Hono API/BFF, the server manages ACP-compatible provider processes, and agent output, plans, diffs, terminal data, and approval requests are streamed back to the browser.

Security

remote-agent is designed to run on trusted machines and private networks, and its dependency policy is intentionally conservative:

• pnpm minimumReleaseAge is enabled so newly published package versions are not installed immediately.
• Every release must pass pnpm audit --audit-level low before publishing.
• Runtime dependencies are kept at zero except for ACP packages that must be available directly at runtime for the built-in agent providers.

Contribute

Contributions are welcome. See CONTRIBUTING.md for development setup, common commands, generated files, and release checks.

License

MIT License. See LICENSE.