Cheetah / Cheetah documentation

Sitewatch cooperative-site relay

Sitewatch is a small consumer application for Cheetah's experimental cooperative-site relay. It shows how an application can give an authenticated viewer a bounded view of a site that is reachable only from a connected client, then carry selected HTTP requests, events, and allowlisted actions across the ordinary Cheetah boundaries.

The relay connects an explicitly shared site to one viewer session. It does not expose the client machine as a general proxy.

The small application-specific layer

The Sitewatch client defines one site descriptor named sitewatch-docs. The descriptor limits the advertised surface to /, /api/status, and /api/mutate-note; declares JSON POST, polling, event-stream, notification, and action capabilities; and allowlists one cooperative action, sitewatch.set_note.

The console runtime registers the reusable cooperative_site_http_request handler and the product-specific note action. A loopback connector service resolves relative relay paths against one configured upstream origin. The browser-facing application mounts Cheetah's cooperative-site router and supplies the authenticated host and viewer identities.

The product-owned pieces remain small but consequential:

• the descriptor says what this local site is and which routes may be used;
• the sharing policy decides which viewer may open it;
• the note action translates one product operation into a bounded local HTTP request;
• the portal chooses how to display a session, events, and action results; and
• the host owns authentication, CORS, retention, rate limits, and deployment security.

The reusable relay code owns URL confinement, request and response framing, session lifecycle, ordinary command dispatch, and authenticated returned evidence.

First verify the embedded shape

The fastest proof does not start a real console connector. Sitewatch's embedded mode mounts the small local docs site in the same FastAPI process and uses the relay API directly:

products\venv\Scripts\python.exe -m pytest \
  products\sitewatch\backend\test_sitewatch_backend.py -q

The tests list the site, open viewer sessions, load the relayed page, read status, post a note mutation, and verify that two sessions keep their state separate. A connector-only test also confirms that the portal remains available while the site list stays empty until a connector registers.

Embedded mode proves the application and session behavior. It deliberately does not prove a WebSocket delivery hop, a separate local origin, or a real remote viewer.

Then inspect the connected shape

The full demonstration separates four processes or surfaces:

1. a localhost-only docs site on the client machine;
2. a console runtime that advertises the descriptor and serves relay commands;
3. Cheetah WebSocket and REST roles plus the browser-facing application; and
4. a viewer that opens the cooperative portal and creates a session.

The local control endpoint registers the site only after the console runtime has connected. Opening a session creates a relay entry URL. Requests under that URL are translated into bounded Cheetah commands, executed against the configured loopback origin, and returned to the application. The portal can also invoke sitewatch.set_note; that action uses the same governed command and result path rather than a hidden administrative tunnel.

The source-local Sitewatch README contains the exact development launch commands and required environment variables. Use them only on a controlled machine or trusted test network. The demonstration defaults include development credentials, plaintext endpoints, permissive CORS, fixed sample identities, and process-local session state.

What the case study proves

Sitewatch demonstrates that a consumer can adopt the relay without duplicating its protocol or turning application code into a generic proxy. It also demonstrates two useful modes: compatibility-style HTTP relay for an ordinary local site, and cooperative behavior through named events and allowlisted actions.

It does not prove production authorization, durable sessions, horizontal session sharing, arbitrary HTML compatibility, or safe exposure to the public Internet. Session identifiers must not become accidental bearer authority, and every session read, action, and relay route must remain under an authenticated viewer policy.

Use this case study to understand the integration seam. Use the site-relay reference for exact descriptors, request confinement, sharing, lifecycle, events, actions, and current limits.