Chapter 21 — Cloud Portal and Web Access

The Cloud Portal is the way to reach your AidaIDE machine from a browser — from your phone, a tablet, a hotel laptop, or a teammate's workstation. Nothing is installed remotely. You log into https://aidaide.app, pick a device you own, and the portal proxies your browser through a secure reverse tunnel back to a small web server running next to your local AidaIDE.

This chapter is also where the in-browser Web Dashboards (Fleet, Network, Security, Containers, Monitoring, Backup, Admin) live — they all serve through the same portal once you log in.

What this chapter covers

Logging in to the Cloud Portal and registering a device.
Inviting a teammate with a Guest Pass — short-lived shareable URL.
The Access panel (sessions, passes, permanent collaborators).
The Remote Desktop browser tab — live frames of your AidaIDE screen.
The Web Hierarchy Composer (browser version of the AI Hierarchy Builder).
The other Web Dashboards bundled with the portal.
Self-hosting the portal for offline / on-prem use.

What is the Cloud Portal?

When AidaIDE is running on your local machine, a small Flask web server inside the app exposes a private API (port 5001 by default). The Cloud Portal is a hosted service at aidaide.app that proxies an authenticated browser request through a secure WebSocket tunnel back to that local Flask, with role-based access control and a "prompt the host" approval flow for sensitive actions.

You do not need to forward a port on your router. You do not need a public IP. The tunnel is initiated outward by your machine.

The portal is a thin façade: every byte of work still happens on your local AidaIDE. The portal is just authentication, transport, and a permission grid.

Logging in

In your browser, open https://aidaide.app/web/login.
Sign in with the same account you use for your AidaIDE license (Google / GitHub / email). The portal uses OIDC.
The first time you log in from a given machine, you may be asked to verify by email.
Once in, you land on My Devices — every AidaIDE machine that has phoned home for this account.

If you have not connected any device yet, see I do not have a device registered yet — setup paths below.

Registering a device

A device must "enrol" once before it appears in My Devices.

On the device, launch AidaIDE and unlock the vault.
Open Settings → Cloud Portal (Chapter 13).
Click Enable Cloud Access. AidaIDE generates a per-device certificate, registers a stable device_id, and starts the outbound tunnel.
Refresh aidaide.app/web/devices — your device appears. Click it to open the device detail page.

The device enrolment is idempotent: re-running it on the same machine reuses the same device_id and rotates the cert.

The device detail page

A device page has four areas:

Header — device name, OS, last-seen time, online dot. Pencil-icon next to the name lets you rename.
Access panel (new in 0.5.66+) — see below.
Activity — audit log of who connected, when, and what they did.
Quick links — buttons that open the in-browser dashboards proxied to this device (Fleet, Remote Desktop, Network, Security, etc.).

The Access panel

The Access panel is where you decide who else can use this device.

ACCESS                                          [+ Invite a guest]
─────────────────────────────────────────────────────────────────
ACTIVE NOW (2)
  alice@x.com   [Read-Only]   23m online · last seen 4s   [Disconnect]
  bob@y.com     [Trusted]      5h online · last seen 11s  [Disconnect]

PASSES (3 active)                           [ ] Show revoked/expired
  ● Active     Read-Only   expires in 47m   claimed by alice@x.com   [Revoke]
  ○ Unclaimed  Trusted     expires in 18h   invited charlie@z.com    [Copy claim URL] [Revoke]

PERMANENT COLLABORATORS (1)                       [+ Add by email]
  wes@example.com    Owner                                (you)
  alice@x.com        Read-Only                       [Revoke]

Three sections in one panel:

Active now polls every 5 seconds. Disconnect kicks a session and frees the guest-pass slot it was using.
Passes is the list of every Guest Pass you have ever issued for this device. Toggle Show revoked/expired to see history.
Permanent collaborators is for teammates who should have ongoing access; they consume a paid seat (not a guest pass).

Inviting a guest

Click + Invite a guest to open the modal:

Permission group — Owner, Trusted, Collaborator, Read-Only.
Duration — 1 hour, 24 hours, 7 days, or custom minutes.
Email (optional) — pre-fills the claim page; not required.
Note (optional) — what the pass is for; visible in the audit log.

Click Issue. The modal flips to a success view with a single-use claim URL and a Copy button.

Send that URL to the person you want to invite. When they open it they go through OIDC login (or sign up if needed), then are redirected straight into your device with the chosen permission group. The pass auto-revokes at the expiry; you can also revoke it manually any time.

A single guest pass can only be claimed by one user. Multiple people need multiple passes.

Permission groups in plain language

Group	Can read	Can change settings	Can run commands	Can use Remote Desktop
Read-Only	yes	no	no	view-only
Collaborator	yes	no	yes (with prompt-host)	yes (input gated)
Trusted	yes	yes	yes	yes
Owner	yes	yes	yes (no prompt)	yes

"Prompt-host" means: when a Collaborator tries to do a sensitive thing (run a WRITE LCOT command, change a file outside the workspace, open the vault), the request pauses and the device owner gets a desktop popup asking Allow / Deny / Always for this user.

Remote Desktop in the browser

From a device page, click Remote Desktop to open a live mirror of your AidaIDE window in the browser tab. This is a Socket.IO-driven streaming view: frames flow from your local screen up the tunnel; keyboard and mouse events flow back down.

When you first open it, you may be prompted for a six-digit RD PIN that pops up on the host machine. The PIN expires in 60 seconds; entering it pairs this browser session with the host.

Once paired:

Mouse and keyboard are forwarded. The browser tab grabs keystrokes; press Esc + ~ to release if you ever need to.
Quality drop-down picks between 1080p / 720p / 480p substreams. Lower resolutions stay smooth on slow connections.
Read-only badge appears in the header if your role does not include input.

Behind the scenes:

Transport is WebSocket-only (no long-poll). The tunnel forwards Socket.IO frames between your browser and a local Socket.IO server on localhost:5001.
The api.aidaide.app proxy forwards your authenticated browser cookie via the WS as additional_headers, so server-side capability checks still work.
Mouse coordinates are translated from browser viewport → desktop coords with DPI scaling applied.

Other web dashboards

The portal also serves these full-page dashboards for the connected device. Each is opened from Quick links on the device detail page or from the global toolbar.

Fleet Dashboard (/fleet) — the same Fleet Manager view from Chapter 5, in HTML.
Network Dashboard (/network) — scanner results, topology map, traffic charts (cross-reference Ch. 6).
Security Dashboard (/security) — vulnerability scanner, threat-intel feeds (cross-reference Ch. 7).
Container Dashboard (/containers) — Docker / Compose / k8s controls (cross-reference Ch. 12).
Monitoring Dashboard (/monitoring) — CPU / RAM / disk / alerts.
Backup Dashboard (/backup) — backup jobs, last-run status.
Admin Dashboard (/admin) — only visible to Owners; user/seat/license management for the account.
Config Dashboard (/config) — read-only view of settings the desktop app is currently using.

All eight dashboards reuse the same auth / role checks. A Read-Only guest sees data but every button that mutates state is hidden or disabled.

Web Hierarchy Composer

The Composer is the browser version of the AI Hierarchy Builder (Chapter 9). Open it from the device dashboard via the Composer toolbar button — internally showAIPanel('composer').

Toolbar (top of the canvas), left to right:

Zoom In / Out / Fit — + / - / Fit buttons. Fit auto-frames every node in the current document.
Auto Layout — runs the canvas auto-layout algorithm. Tidy when you have pasted a lot of nodes in by hand.
Auto Wire — connects unwired outputs to the nearest matching input (best-effort, you can undo with Ctrl+Z).
Validate — runs the same checks as the desktop's Validate button: dangling wires, type mismatches, missing properties.
Run / Stop — calls /api/ai/composer/run against the SignalFlowEngine in your local AidaIDE.

Modes (pill row, top-left): flat / ic / soc / hierarchy. They mirror the desktop builder's modes — see Chapter 9 §Modes.

Library, properties, and minimap panes float on the right. The composer state is persisted in ~/.aidaide/builder_drafts/ so the desktop builder picks up exactly the same document.

Known parity gaps with the desktop builder (as of run 1 / 2026-05-29):

The animated trace view is desktop-only — the web composer runs validation but does not animate signal flow.
Right-click context menus on the web canvas are a subset.
Macy tour (the 16-section tutorial overlay) is desktop-only.

Track parity progress in Ch. 18 §Composer parity gaps.

Self-hosting the portal

For air-gapped or compliance-sensitive environments you can run the portal on your own infrastructure.

The portal is a FastAPI service in cloudportal/api/ plus a Python tunnel gateway in cloudportal/gateway-py/.
A docker-compose.yml is included for a quick local stand-up.
A docker-compose.prod.yml plus fly/ configs are included for the reference Fly.io deploy.
Set DEV_AUTH_BYPASS=1 to bypass OIDC for local development (do not enable in production).

Read cloudportal/README.md for the run-order, and cloudportal/HANDOFF.md for the architecture brief.

Terms & Setup

Cloud Portal

Hosted service at https://aidaide.app that proxies authenticated browser requests to your local AidaIDE through a secure reverse tunnel. No port forwarding required.

Guest Pass

A single-use, time-bound, role-scoped invitation URL. Issued from the Access panel; claimed by clicking the URL and signing in. Auto-revokes at expiry, can be revoked manually.

Permission group

The bundle of capability flags applied to a session. Read-Only / Collaborator / Trusted / Owner. Defined in cloudportal/db/migrations/versions/0001_groups.py.

Prompt-host

The interactive approval flow: when a Collaborator tries a sensitive action, the device owner sees a popup with Allow / Deny / Always for this user. Decisions are logged in the device audit trail.

Device enrolment

The one-time handshake where an AidaIDE install registers itself with the portal. Generates a per-device cert under ~/.aidaide/cloud_portal/device.pem.

Tunnel gateway

The hosted WebSocket endpoint that brokers traffic between the portal and your local AidaIDE. Speaks mutual TLS using the device cert.

`webportal/d/<device_id>/` path

The portal's URL space for proxied access. Anything you would normally reach at localhost:5001/foo on the device is reachable as aidaide.app/webportal/d/<id>/foo once authenticated.

Remote Desktop (browser)

Socket.IO streaming of your AidaIDE window into a browser tab. Transport is WebSocket-only. Authenticated by the same session cookie as the rest of the portal.

RD PIN

The 6-digit pairing code shown on the host's desktop the first time a browser tries to open Remote Desktop. Expires in 60 seconds. Prevents a session that has compromised your browser cookie alone from opening a screen mirror.

OIDC (OpenID Connect)

The federated login protocol used by the portal. Same identity you used to buy your AidaIDE license.

Web Hierarchy Composer

Browser-based UI for the AI Hierarchy Builder (Chapter 9), opened with the Composer toolbar button on a device's dashboard.

"I do not have a device registered yet" — setup paths

You need at least one AidaIDE install enrolled before the portal has anything to proxy.

Easiest — the machine you are already on:
1. Open Settings → Cloud Portal.
2. Tick Enable Cloud Access.
3. Wait 5-10 seconds for the green Tunnel up badge.
4. Reload https://aidaide.app/web/devices.

Headless server (Pi / Linux VM):
1. Install AidaIDE on the headless box (Chapter 1).
2. Run aidaide --enable-cloud --headless once with the vault unlocked.
3. The CLI prints the enrolment URL — open it once in a browser to confirm ownership.
4. From then on the tunnel auto-starts with the service.

Test without a real device — self-host the portal:
1. cd cloudportal && docker compose up -d to start API + gateway + Postgres locally.
2. Run the example local Flask: python -m cloudportal.examples.local_flask.
3. Open http://localhost:8000/web/login and use the seeded dev user wes@electronyx.test.
4. The example Flask appears as a device you can proxy to.

"I do not have a teammate to invite yet" — practice without exposing your machine

If you want to see what a guest sees but have no one to send the URL to:

Issue a pass with the Read-Only group.
Copy the claim URL.
Open it in a private/incognito window.
Sign in with a second account (a free Google account is fine).
You will land on your own device with the Read-Only badge — exactly what your teammate would see.

Revoke the pass when you are done.

Chapter 21 — Cloud Portal and Web Access

What this chapter covers

What is the Cloud Portal?

Logging in

Registering a device

The device detail page

The Access panel

Inviting a guest

Permission groups in plain language

Remote Desktop in the browser

Other web dashboards

Web Hierarchy Composer

Self-hosting the portal

Terms & Setup

Cloud Portal

Guest Pass

Permission group

Prompt-host

Device enrolment

Tunnel gateway

webportal/d/<device_id>/ path

Remote Desktop (browser)

RD PIN

OIDC (OpenID Connect)

Web Hierarchy Composer

"I do not have a device registered yet" — setup paths

"I do not have a teammate to invite yet" — practice without exposing your machine

See also

`webportal/d/<device_id>/` path