Pair an agent

Cloud Ring brokers everything that touches your filesystem or spawns a shell through a small per-machine binary called ringagent. It runs as you (not LocalSystem), holds a SignalR connection to this cloud, and answers requests like “list this directory” or “spawn pwsh in my-project/.”

Until an agent is paired, the Files / Terminal / Drive panes show empty “no agent connected” states. Below is what you need to do once per machine.

Quick install (Windows, PowerShell)

One configuration point: your projects folder — anything under it is what the agent will expose to this cloud (file browser, terminal cwd, drive sync source). Pick a parent that contains the projects you want reachable, not your whole user profile.

Projects folder (RootPath) PowerShell-style. $HOME expands to your profile dir. Common picks: $HOME\source, $HOME\Projects, C:\dev.

Two-line install. Doesn’t need admin — the script installs into your user profile + a per-user scheduled task. Re-running it self-purges any previous install (you don’t need to uninstall first).

loading…

The script extracts the agent to %LOCALAPPDATA%\Ring\bin\, writes a per-machine appsettings.json with the cloud URL + your RootPath, registers a RingAgent Task Scheduler task that triggers at logon, and starts it.

Manual download

If you’d rather inspect the binary before running it, or you’re on macOS / Linux (cross-platform support is coming — see ADR 0020):

Download ringagent (Windows x64) version.json install-agent.ps1 loading version…

The zip is self-contained — no .NET runtime install needed. SHA-256 + size are in version.json for verification.

What happens after install

1

Agent prints a device code on first run

If you used the Quick install, watch the RingAgent Task Scheduler task or run the agent foreground once: & "$env:LOCALAPPDATA\Ring\bin\ringagent.exe". It prints something like X8KP-JNQ4 plus a claim URL.

2

Open the claim URL on a signed-in browser

The claim URL points at /agents/pair.html. You need to be signed in via brandongrossutti.com (cookie SSO). Type the device code (or follow the URL with ?code=… prefilled), click Claim.

3

Agent gets a JWT and connects

Within a few seconds of claim, the agent finishes its pair-finish poll, persists a DPAPI-encrypted token in %LOCALAPPDATA%\Ring\agent-token.bin, and connects to /ws/agent. The disconnected banner on the home page disappears.

4

Open a project tab

Back on the Ring home, click any project card with a marker. The Files, Terminal, and Drive subviews are now live against your machine.

Re-pairing or moving cloud

Just re-run the Quick install above. The script self-purges any previous install — stops the scheduled task, removes %LOCALAPPDATA%\Ring\bin\, clears the saved token + machine fingerprint, then installs fresh. Pair flow happens once more on first run; one click on the claim page and you’re back.

Why this can come up: the agent's saved JWT is signed with whatever cloud you last paired against. If you switch clouds (e.g. you paired against localhost:5550 earlier and now point at this cloud), the old token won’t verify. The current agent build (v?) detects 401 on the hub negotiate and self-recovers anyway, but a fresh install is the cleanest way through.

Verify it’s working

After pairing, the topbar's brand-sub goes from “no agent connected” to agent · YOUR-HOSTNAME · Ns ago. Or hit /api/v1/agents/connected directly to see the registry contents.