Cheetah / Cheetah documentation

Describe and register a site

A site descriptor is a public offer from one host: this named local application is available through this connector, with these routes, methods, capabilities, and sharing inputs. It is not proof that the origin is healthy, and it does not authorize a viewer by itself.

Describe the smallest truthful surface

The descriptor combines four kinds of information:

read_write_mode is descriptive. The route allowlist still decides which methods and paths can cross the relay. Capability fields are also promises, not decoration: do not advertise events without the cooperative ingest path, or actions without handlers and local policy.

The console helper builds a normalized descriptor:

import { defineCooperativeSite } from '@cheetah/console';

const site = defineCooperativeSite({
  site_id: 'project-docs',
  display_name: 'Project documentation',
  local_origin: 'http://127.0.0.1:8090/docs/',
  integration_mode: 'external_compat',
  change_strategy: 'manual',
  read_write_mode: 'read_only',
  route_patterns: ['/', '/assets/*', '/search'],
  methods: ['GET', 'HEAD'],
  capability_profile: {
    html: true,
    assets: true,
    json_get: true,
  },
});

Route patterns use Python fnmatch. A missing route_exposure denies every request. Methods are limited to GET, HEAD, and POST. Begin with the few paths a viewer needs, include assets deliberately, and add POST only after deciding which local mutations may be exposed.

Registration confirms two independent statements

Connector-backed registration succeeds only when current client presence says that the same authenticated host and connector:

1. advertise the cooperative_site_http_request action; and
2. claim the same site_id in client_metadata.cooperative_sites.

After the Cheetah connection is live, the connector posts its descriptor and connector client ID to /api/cooperative-sites/connectors/register. The route derives host_user_id from the required authentication dependency; a body field cannot select another host. The stored descriptor records connector mode cheetah_console and the connector client ID.

Registration can refresh an existing descriptor. Authenticated unregistration requires both the same host identity and the registered connector client ID. A foreign-owned site is reported like an absent site; trusted in-process application code has a separately named system-level removal method when administrative cleanup is genuinely intended.

Availability follows live presence

A descriptor may remain stored after its connector disconnects. Listing or resolving it refreshes availability_state from the current connection registry. New sessions require available; a disconnected descriptor therefore remains discoverable but cannot be opened until its connector returns and again advertises the relay action.

Availability proves a current command route, not that the local HTTP origin will answer the next request. health_state is correspondingly limited; products that need real origin health should add a deliberate probe and failure policy.

Metadata is visible policy input

The supplied sharing policy understands sharing_mode and allowed_viewer_user_ids from application_metadata. Relay helpers also use connector metadata, upstream_origin, html_compat_mode, and loopback path information. Other fields remain application-owned.

Do not place secrets in descriptor metadata. The supplied site-list and site-detail routes are anonymous, and descriptors include local_origin, capabilities, ownership, and application metadata. A product that treats any of that information as sensitive must protect or replace those routes and decide what to redact.

In-process loopback sites are a separate connector mode

create_loopback_site_descriptor() can seed an ASGI application mounted in the same server process. It uses connector mode loopback, needs no live client claim, maps requests below a configured path prefix, and gives each open session its own httpx client and cookie state.

Loopback mode is useful for an embedded application or focused test. It does not demonstrate that a separately running site is reachable from a remote machine. Use a console-backed descriptor when the origin lives beside a connected client.

Next: Relay HTTP.