Skip to main content

Trust boundaries

QZX security model

QZX is a local command interface, not a sandbox. It runs with the permissions of the current user, and several documented commands can change files, processes, repositories, remote targets, or other system state.

Four-step trust-boundary diagram showing a user or AI agent calling QZX, QZX asking the operating system to act, and the operating system accessing files, network and processes under the current user's permissions.
  1. 1 · CallerA person, script or agent chooses the operation and arguments.
  2. 2 · QZXQZX validates its documented interface and invokes the implementation.
  3. 3 · Operating systemThe host enforces the current account's permissions and native constraints.
  4. 4 · ResourcesFiles, processes, repositories, network targets and other state may be read or changed.
QZX improves consistency, reporting and safeguards for documented commands; it does not create a separate security boundary around the caller or the operating system.

The central rule

Treat every agent-selected command and argument as an operation that still needs normal authorization. Structured output improves observability; it does not make a dangerous action safe.

Read-only and mutating commands

Each command reference page declares the current classification. Mutating examples include file creation, deletion, permission changes, formatting, scaffolding, process termination, deployment, and release workflows. Check the exact page before execution.

Dry-run and apply

Dry-run is command-specific, not a universal QZX guarantee. repairWorkspace is dry-run by default and requires both --dry_run False and --apply True to modify files. Other commands have different defaults or no dry-run parameter.

Native execution

QZX exposes purpose-built commands instead of a generic command bridge. runDiagnosticCommand accepts a bounded diagnostic allow-list, disables shell expansion, limits output, and stops commands after 30 seconds. High-risk filesystem mutations create a recovery archive first; --dangerously-bypass-approvals-and-sandbox/--yolo skips that QZX safeguard. Actions such as runScript that lack a restorable path require the flag. These safeguards complement, but do not replace, operating-system permissions.

Network behavior

Network commands can perform DNS, TLS, URL, speed, configuration, download, health-check, or deployment requests. In addition, unless telemetry is disabled, the CLI uses low-frequency pseudonymous telemetry for version activation and closed 10-day usage summaries.

Paths, links, and permissions

Path normalization, recursive traversal, symlink handling, overwrite behavior, and privilege requirements vary by command. QZX does not currently publish one blanket guarantee for every operation. Review the command parameters, source, and dry-run output.

Threat model

The expected caller is a trusted local user or automation acting within that user's authority. QZX does not isolate an untrusted model, validate the business intent of an action, or replace operating-system access controls, backups, code review, or explicit approval.

Website analytics

The public QZX website records pageviews, session engagement, browser performance signals, and selected product interactions so the project can distinguish useful acquisition paths from vanity traffic. Requests can include ordinary server-observed metadata such as IP address and user agent.

Selected product interactions use short action/target labels such as copy_install_command, copy_project_workflow, copy_agent_instructions, or start_professional_services_form plus the selected route. The services-form signal is emitted only on the first focus and contains no field value. For copy buttons, QZX records the conversion only after the browser confirms a successful copy. These events do not contain form contents, copied commands, clipboard contents, terminal input, project data, or file contents.

Optional workflow feedback

The project and website guides let you choose whether a workflow helped, installation blocked you, execution blocked you, or the result was unclear. Only your chosen category and workflow label are added to the existing website analytics session; no terminal output, destination, clipboard content, free text or new identifier is collected.

Help links work without answering. The immediate recommendation confirms your choice, not server receipt, and remains useful offline. Reporting uses your latest received choice per browser session and workflow. It is a voluntary assessment, not proof of execution, a representative satisfaction score, a lead or a payment. Test traffic stays separate.

Pseudonymous CLI telemetry

By default, QZX sends at most one version_first_run event per QZX version and may send one previously unsent, globally aligned 10-day usage_window after that block closes. Usage is aggregated locally by day before transmission. The closed window contains canonical command names with invocation counts, accumulated/max execution time, active-day counts, and coarse TTY/foreground/recent-OS-input evidence. It never sends command arguments, terminal input or output, paths, environment values, usernames, hostnames, file contents, key values, pointer coordinates, trajectories, clicks, or raw HID events. The server also observes the request IP and receipt time. Recent OS input is only one weak evidence dimension and is never treated as proof by itself.

QZX_TELEMETRY=0 qzx welcome
DO_NOT_TRACK=1 qzx welcome

QZX_TELEMETRY=0 or DO_NOT_TRACK=1 disables collection; an explicit QZX_TELEMETRY=1 takes precedence over DNT. Network or storage failures never change a command result, and an unsent event can retry later. Raw IP addresses are retained for 1,825 days; deletion requires the random installation UUID from local state and must be requested privately. Local state can be redirected with QZX_TELEMETRY_STATE_DIR. Read the complete telemetry and deletion policy or inspect the implementation.

Reporting a vulnerability

Use the private contact route for sensitive reports. Do not paste credentials, exploit material, private paths, or installation identifiers into a public issue.