nanoctl is a fast, headless remote-desktop service with a browser controller. The host agent runs as an operating-system service on Windows, macOS, or Linux. The web application authenticates with Shoo, stores control-plane state in Convex, and negotiates an encrypted WebRTC connection directly to the host. A TURN relay is used only when a direct connection cannot be made.
This repository contains the nanoctl 2.0 rewrite. The release keeps the browser/WebRTC transport model while giving each session one lifecycle owner, generation-safe signaling, bounded newest-frame handoffs, and actionable readiness/recovery UX.
| Path | Purpose |
|---|---|
apps/web |
Next.js dashboard, browser controller, Convex schema/functions |
crates/nanoctl-agent |
Native headless capture, input, WebRTC, and service process |
packages/protocol |
Versioned signaling and control protocol |
infra/coturn |
Reference TURN deployment |
docs |
Product, architecture, security, platform, protocol, testing, and operations |
- Bun 1.3.14 or newer
- Rust 1.96 or newer
- a Convex project
- a Shoo-supported HTTPS origin
- a public TURN service for production
Linux and macOS:
curl -fsSL https://extoci.lol/nanoctl/install | shWindows PowerShell:
irm https://extoci.lol/nanoctl/install | iexThe installer downloads and verifies the latest release, asks for the setup code on first install, and starts nanoctl automatically in the current desktop session. Run the same command again to update to the latest release.
To test the v2 alpha explicitly:
curl -fsSL https://github.com/extoci/nanoctl/releases/download/v2.0.0-alpha.1/install.sh \
| NANOCTL_VERSION=v2.0.0-alpha.1 shOn Windows PowerShell:
$env:NANOCTL_VERSION = "v2.0.0-alpha.1"
irm https://github.com/extoci/nanoctl/releases/download/v2.0.0-alpha.1/install.ps1 | iexbun install
cp apps/web/.env.example apps/web/.env.local
bun run convex:dev
bun run devIn another terminal:
cargo run --manifest-path crates/nanoctl-agent/Cargo.toml -- doctor
cargo run --manifest-path crates/nanoctl-agent/Cargo.toml -- enroll ABCDE-FGHJK-MNPQR-STVWX
cargo run --manifest-path crates/nanoctl-agent/Cargo.toml -- runRun all repository checks with bun run check. Media-feature builds also require the native desktop
capture development libraries for the target platform.
Host registration and removal instructions are in docs/SETUP.md.
nanoctl is designed for device-owner-authorized access. It does not hide its installation, bypass OS consent, capture a locked secure desktop without supported system APIs, or provide an arbitrary remote shell. Media and input travel over DTLS-SRTP/SCTP. The control plane sees device metadata, session metadata, and encrypted transport addresses, but not unencrypted desktop content.
Read docs/SECURITY.md before deploying.
The source is production-oriented, but a release is not considered supported until its platform package has passed the physical-machine matrix in docs/TESTING.md. VM-only tests cannot validate hardware encoders, macOS TCC prompts, Windows secure desktop behavior, Wayland portals, or hostile NAT traversal.