Cheetah / Cheetah documentation

Console runtime

createConsoleRuntime() composes Cheetah for a Node.js process or machine agent. It adds a durable file-backed identity, a Node WebSocket adapter, logical execution flows, a state reporter, a filesystem cache, and optional handlers for files, processes, and downloads.

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

const runtime = await createConsoleRuntime({
  serverUrl: 'wss://api.example.com/cheetah/ws',
  authToken: await acquireMachineCredential(),
  identityFilePath: 'C:/ProgramData/MyProduct/cheetah-client-id',
  localPolicySource,
  modules: [productHandlers],
  clientMetadata: { role: 'render-worker', os: 'win32' },
});

await runtime.start();

The console composition is deliberately powerful, not intrinsically safe. Its built-in file and process handlers run with the operating-system account's authority. Deploy it under a restricted account, expose only required handlers, and enforce local policy around paths, commands, working directories, and network destinations.

Identity and state belong to the process host

By default, FileIdentityProvider stores the logical client ID in .cheetah_client_id under the process working directory. It restores that ID on a later construction and generates a fresh instance ID for the new runtime. Set identityFilePath or supply an identity provider when the process working directory is not a durable, protected home for identity.

The runtime also creates a default logical flow and reports flow state through a ConsoleStateReporter. Flows let one machine client expose multiple application execution contexts without pretending that each context is a separate transport connection. The flow handlers are registered even when skipBuiltinHandlers is true; that option removes the filesystem, process, and download handlers, not flow management or core actions.

The built-in cache_data action writes through a FileSystemCacheProvider. Its directory is .cache unless cacheDir is set. A cache directory is operational storage, not an identity store or a protected secret vault.

Configuration surface

The console wrapper accepts the shared server URL, strict-or-development transport mode, credential, optional REST endpoint, command timeout, lease lifetime, logging, local policy, approval, payload-resolution and payload-decryption options, cache directory, flat client metadata, handler modules, and dynamic-handler settings.

It intentionally exposes a smaller surface than createCoreRuntime(). For example, it creates its own Node WebSocket factory, state reporter, cache provider, and clientType: 'console'. Use core directly or extend the package deliberately when a product needs to replace those boundaries rather than bypassing the composition ad hoc.

The normal core defaults still apply where the console wrapper does not override them, including exact package protocol version, one start attempt per runtime object, closed handler registration after startup begins, ACK and result semantics, reconnection, validation, local policy, approval, leases, and cancellation.

Built-in handlers are optional machine authority

With built-ins enabled, the runtime registers:

• read_file, write_file, and list_dir for the local filesystem;
• exec for child-process execution;
• download_files for HTTP or HTTPS retrieval;
• list_flows, create_flow, and close_flow for logical execution contexts.

Relative paths are resolved by Node against the process working directory. The handlers do not provide a sandbox or configurable root boundary. write_file creates missing parent directories and overwrites the destination. exec runs through the host process environment, and a nonzero child exit is a completed Cheetah action whose payload carries that exit code. These details make product-specific local policy essential.

Set skipBuiltinHandlers: true when the process should expose only product modules. Flow handlers and the harmless core probes remain present. The console action catalog defines parameters, results, and failure boundaries in detail.

Modules are the normal extension point

Pass compiled HandlerModule objects through modules. Compatible console modules are loaded after built-ins and before startup; incompatible modules are skipped, and a module failure is isolated by the shared module loader. Each registration contains executable handler code and a matching public action descriptor.

Dynamic directory loading is a separate, opt-in extension point. When enableDynamicHandlers is true, the runtime reads handler descriptors and corresponding JavaScript modules from handlerDir, or from the platform user's .cheetah/handlers directory when no path is supplied. Dynamic handlers load last, so built-in and configured modules retain priority.

Treat that directory as executable-code deployment. Only trusted administrators or a verified software-update path should be able to write there. JSON descriptors do not make adjacent .mjs code safe, and Cheetah does not sandbox it.

Shutdown integration is explicit

Stopping the runtime closes its Cheetah facilities, but applications still own process signal handling and any resources opened by custom handlers. ConsoleLifecycleHost is an optional utility that can install idempotent SIGINT, SIGTERM, and fatal-error coordination. Register shutdown handlers, include runtime.stop(), and dispose the host when another owner takes over process lifecycle.

Shutdown remains cooperative. It prevents new useful work and signals in-flight handlers, but cannot undo a filesystem write, child-process effect, or remote download that already occurred. Long-running custom handlers should observe their abort signal, stop producing progress after cancellation, and design external effects for idempotency or reconciliation.

Continue to web and mobile runtimes