Cheetah / Cheetah documentation

Prepare the source checkout

The maintained examples run from a Cheetah source checkout. Prepare the core server and client libraries first; add the larger example products only when you need them.

Prerequisites

For the core setup, provide:

• Python 3.10 or newer;
• Node.js 18 or newer and npm;
• Git and a supported command shell.

Redis is not required for the first connected action. It becomes necessary for the Redis-coordinated examples and deployments. Browser-extension development also requires a Chromium-based browser in which you can load the built extension.

From the repository root, confirm the runtimes that will be selected by the bootstrap:

python --version
node --version
npm --version

If several Python or Node.js versions are installed, make the intended supported version visible on PATH before bootstrapping. Mixing artifacts built by different Node.js installations is a common source of confusing client failures.

Prepare the core libraries

On Windows:

bootstrap.cmd --core

On macOS or Linux:

./bootstrap.sh --core

The core target creates the Python development environment under serverCheetah, installs the server package with its development and optional server features, installs the TypeScript workspaces, builds the shared client packages, and prepares the console example used on the next page.

Use the repository bootstrap rather than adding import-path shortcuts or installing isolated packages by hand. The server and TypeScript packages evolve together, and the bootstrap keeps their local versions aligned.

Choose a broader target only when needed

Running the bootstrap without flags prepares the default example products. Other useful targets include:

These targets are composable repository setup choices, not server runtime modes. For example, selecting --dashboards builds operator interfaces but does not automatically mount or secure them in an application.

Check the prepared environment

After the Windows core bootstrap, this file should exist:

Test-Path serverCheetah\venv\Scripts\python.exe

PowerShell should print True. On macOS or Linux, the interpreter is serverCheetah/venv/bin/python.

You can also run the repository's quick quality checks:

ci_local.cmd --quick

or, cross-platform:

python scripts/ci_check.py --quick

The quality suite covers much more than the first example, so it is a useful repository health check but not a substitute for running the connected path itself.

Rebuild after client changes

The TypeScript packages are workspace dependencies. If you change @cheetah/core, a platform package, or an example handler, rebuild the relevant artifacts before testing. From the repository root:

rebuild_all.cmd --core-only

or on macOS and Linux:

./rebuild_all.sh --core-only

After rebuilding a browser package, reload the unpacked extension in the browser. An open tab can keep talking to an older extension instance, so include the active runtime version in any diagnosis of unexpected behavior.

Development transport is deliberately explicit

The connected example uses ws:// and http:// only because both sides select debug_insecure transport on localhost. Cheetah warns about this configuration. For an externally reachable deployment, use wss:// and https://, select strict transport, and terminate TLS at a boundary whose forwarded identity and scheme are configured correctly.

Run the first connected action