Console actions
Console actions expose selected machine capabilities from a Node.js client. Flow actions are always part of the console composition. Filesystem, process, and download actions are omitted when skipBuiltinHandlers: true.
These handlers use the process account and working directory. They do not create a filesystem sandbox, command allowlist, container, or privilege boundary. Production products should run under a restricted account and enforce client-local constraints appropriate to the machine's role.
Logical execution flows
Flows are numeric contexts analogous to browser tab targets. The runtime creates a default flow before startup and reports flow state to the server.
list_flows
Returns flows, count, and active_count. Each listed flow contains id, name, status, and millisecond created_at. Closed flows remain in the list with status closed; active count excludes them. The current list response does not include the flow's worker flag.
create_flow
Accepts optional string name and optional boolean worker. Without a name, the manager uses flow-N; worker defaults to false. The result contains id, name, status, created_at, and worker.
After creation, the state reporter is triggered on a best-effort basis so the server can learn the new context. The applied action does not wait for or prove successful state ingestion.
close_flow
Requires numeric flow_id and returns flow_id with closed: true. A missing ID produces missing_param; an unknown or already closed flow produces not_found. Closing changes the flow's status rather than deleting its record, then triggers the same best-effort state report.
Flows provide addressing and reported context. They do not isolate process memory, create a new operating-system session, or sandbox actions from one another.
Read and write files
All three filesystem handlers resolve relative paths against process.cwd(). The applied result returns the resolved absolute path. No handler-level root restricts where an absolute path may point.
read_file
Requires string path; optional encoding is utf-8 by default or base64. It rejects other encodings with invalid_encoding. UTF-8 returns text; base64 reads raw bytes and encodes them. Both results contain path, content, encoding, and byte size.
A missing file yields not_found, a directory yields is_directory, and another filesystem failure yields read_error. There is no built-in maximum file size, streaming response, or redaction. Restrict paths and avoid reading unbounded files into a command result.
write_file
Requires string path and string content, with the same utf-8 or base64 encoding choice. It creates missing parent directories, overwrites the destination, and returns resolved path and resulting byte size. Failures become write_error.
The handler does not provide append, compare-and-swap, atomic replacement, backup, or rollback. Base64 decoding uses Node's buffer decoder; products needing strict content validation should validate before this handler or register a narrower action.
list_dir
Requires string path and returns resolved path, count, and entries. Each entry contains name, type (file, directory, symlink, or other), byte size, and ISO modified time. An entry that cannot be inspected is retained as other with zero size and an empty timestamp.
An absent directory yields not_found, a non-directory yields not_directory, and another enumeration problem yields list_error. The action lists one level; it does not recurse.
Execute a process
exec requires string command, with optional string cwd and numeric timeout_ms. The timeout defaults to 30,000 ms and must be finite and greater than zero. Node executes the command through the system shell and captures at most 1 MiB of output.
An applied result contains the original command, trimmed stdout, trimmed stderr, and exit_code. A nonzero child exit is still an applied Cheetah action because the handler successfully launched and observed the process; inspect exit_code for the program outcome. A killed timeout yields the Cheetah failure timeout, invalid timeout input yields invalid_timeout, and failure to establish the execution yields exec_error.
exec is not a portable structured process API. Shell parsing, quoting, environment variables, available commands, and working-directory semantics depend on the host. Prefer narrow product handlers over exposing a general shell when the machine has a defined operational role.
The child-process helper is not wired to the command abort signal. A Cheetah cancellation or lease loss can fence late evidence but does not reliably terminate an already launched child. Use a custom process handler when active cancellation and cleanup are requirements.
Download to the machine
Console download_files accepts one url or array urls, optional single filename or parallel filenames, and optional suggested_dir. The directory defaults to downloads under the process working directory and is created when absent.
Suggested filenames are reduced to their basename before joining the destination directory, and the resolved destination is checked to remain inside that directory. Without a supplied name, the handler uses the final URL path segment or a generated name. Redirects are followed, including relative locations, up to 10 hops.
The action returns one item per request with url, destination path, byte size, success, and optional error. At least one successful item produces an applied result with totals, partial, destination dir, and the item list. If all items fail, the action fails with download_failed and still includes the list.
The implementation chooses the Node HTTP module unless the URL string begins with https; it does not perform a separate strict URL-scheme allowlist check. Client-local policy should restrict allowed origins and require intended transport security. Cancellation and lease validity are checked between files, not while an active HTTP request is streaming. Use a custom downloader when in-flight cancellation, integrity verification, authentication, size limits, or atomic file publication is required.
Treat these actions as host authority
The descriptors make machine capabilities discoverable, but they do not limit the operating system. A central allow, advertised exec, or known path cannot override a client-local deny or the process account's permissions. Conversely, a permissive client running as an administrator can cause far more damage than the action names suggest.
Use least-privilege service accounts, narrow handler sets, explicit path and command constraints, auditable approval where appropriate, bounded payloads, and product-level idempotency. Disable the general built-ins and register role-specific modules when that yields a clearer contract.