Agent Orchestrator Remote Access

Mobile Access V1 Review

A practical review artifact for the current branch: what V1 ships, why it is enough for first release, which security concerns are real, and what should move to V2.

V1 scope Cloudflare quick tunnel plus Basic Auth and QR entry point.
Current status Good for a pragmatic V1 after proxy-auth and shutdown fixes.
Deferred scope Session cookies, token TTLs, lockouts, and rate limits.
Included

Remote Dashboard

The dashboard exposes a desktop Remote button. The tunnel is created only when the user enables it at runtime; normal ao start remains local-first.

Included

Basic Auth

Public access requires configured credentials. Local loopback dashboard access remains frictionless unless the request carries a real external proxy address.

Included

Terminal Proxy

Terminal WebSocket traffic routes through the dashboard origin and direct terminal connections validate the active remote credentials.

Runtime Flow

Remote access is a runtime toggle, not a new startup mode. The happy path is intentionally short so it works for quick mobile access without VPN setup.

Step 1

Start AO

Run AO normally. Dashboard starts local and local access stays easy.

Step 2

Click Remote

The dashboard calls /api/remote-info to enable remote access.

Step 3

Start Tunnel

cloudflared is downloaded if needed and starts a quick tunnel.

Step 4

Scan QR

The modal shows public URL, QR code, username, and password.

Step 5

Authenticate

Mobile browser opens the public URL and signs in with Basic Auth.

V1 Threat Model

V1 is for a user-controlled development machine and a temporary public tunnel. It is not a hosted multi-user remote-control service.

  • Public URL is protected with Basic Auth.
  • Loopback bypass is allowed only for local dashboard use.
  • External proxy headers with non-loopback addresses require authentication.
  • Credentials are simple and user-editable for V1.

Credential Storage

Credentials are stored in the AO global config. This is a deliberate V1 tradeoff for a local developer tool, and should be surfaced plainly in the UI. 

~/.agent-orchestrator/config.yaml

remoteAccess:
  username: ao
  password: example-password

Review Findings Triage

Fixed V1 blocker

Cloudflare tunnel auth bypass

Public tunnel traffic can reach Next through a loopback socket. V1 now avoids loopback bypass when proxy headers contain an external client address.

Keep covered by middleware tests.
Fixed Stability

Direct terminal shutdown

Shutdown is now guarded against repeated signal handling and exits cleanly after the server close callback.

Prevents noisy stop behavior.
Fixed Compliance

Inline platform checks

web-dir.ts now uses shared platform helpers instead of direct process.platform checks.

Matches AO cross-platform rules.
Valid Deferred

Plaintext credentials

Real tradeoff: credentials are stored in local plaintext config. Acceptable for V1, but the UI should warn users that this is local config storage.

Track as V1 UX disclosure or V2 hardening.
Valid V2

No rate limiting

Basic Auth attempts are not rate limited. Generated passwords reduce practical V1 risk, but V2 should add throttling or lockout behavior.

Not a V1 release blocker.
Accepted Low

Token secret in process env

AO_REMOTE_WS_TOKEN_SECRET lives in the process environment. That is acceptable for an ephemeral local process.

No V1 action needed.
Non-issue Verified

atob in middleware

Next middleware can use atob. Server code uses Buffer where Node APIs are available. Existing tests cover Basic Auth decoding.

No change recommended.

V1 vs Stronger Proposal

Capability V1 Hardened V2
Login model Basic Auth Token login plus HttpOnly session cookie
Credential store Plaintext local config Hashed/tokenized credential store
Session lifetime Browser-managed Basic Auth lifetime Explicit token TTL and session TTL
Abuse controls No rate limit Rate limit, lockout, revoke sessions

Decision Summary

V1 is enough if the product goal is temporary mobile access for a local developer: click Remote, scan QR, authenticate, and control AO from mobile.

  • Do ship as "remote dashboard access through Cloudflare quick tunnel plus Basic Auth."
  • Do warn that credentials are stored in local plaintext config.
  • Do not describe V1 as a full mobile-auth platform.
  • Do move token sessions, lockouts, rate limits, and revocation to V2.

Source Files

packages/web/src/middleware.ts
packages/web/src/middleware.test.ts
packages/web/server/direct-terminal-ws.ts
packages/web/server/remote-auth.ts
packages/web/src/lib/remote-access-manager.ts
packages/web/src/components/RemoteAccessQR.tsx
packages/cli/src/lib/web-dir.ts
docs/mobile-access-v1.md

Generated as a self-contained review artifact for PR 1901 / Mobile Access V1.