ZBack CLI

ZBack is an opt-in remote administration agent for systems you own or are authorized to manage. The package uses Node.js 20 or later, uses the ws WebSocket dependency and runs no installation scripts.

Security: ZBack grants remote shell access with your local user privileges to anyone who possesses its private session ID. Treat that ID as a password. Do not publish it, paste it in issue reports, or share screenshots containing it. Do not run ZBack as root or as an account with unnecessary permissions.

Install and start

Use Node.js 20 or later. Install dependencies before running node bin/zback.js directly from a source archive.

npm install -g .
zback

On the first run in a terminal, ZBack presents a [Y]/[N] shell authorization question once. It stores the decision locally, then creates a private agent credential. There are no prompts for each command.

Workspace file protection (CLI 1.3.1): Every time you start a new agent interactively, ZBack asks whether to restrict MCP file operations to --cwd. Answer Y (default) to keep file paths inside the working directory, or N to permit relative traversal and absolute filesystem paths for MCP file tools. Your choice applies for the current agent run and remains in effect across its reconnects; it is not requested per command. Existing running agents keep their mode until stopped. The shell-execution tools are not restricted by the workspace option; they run with your OS account permissions in either mode.

For explicitly authorized non-interactive runs (such as GitHub Actions or containers), add --accept-shell-access on the first start. This flag grants the same persistent local authorization without needing a TTY. Without previous authorization or that flag, non-interactive startup fails safely. Never add the flag to scripts executed by untrusted contributors, and avoid running ZBack as root.

zback --accept-shell-access --workspace-protection on --url wss://your-domain.example/ws

For environments without a terminal, workspace file protection is on by default. You may explicitly choose --workspace-protection off, but only use this with trusted agent credentials and an appropriate least-privilege account. This flag changes file tools; it does not disable server authentication, consent, file-size limits or resource safeguards.

When using CI, remember that remote execution access lasts for the duration of the workflow job and any person holding the session ID can execute commands with the process privileges. Use trusted workflows and keep the ID private.

Terminal status markers are colored on supported interactive terminals: yellow [+] for progress, red [×] for errors and gray > for contextual hints. Plain text is used when output is redirected. The command history updates as commands complete and shows each command's exit code and cumulative successes/errors. Connection problems are summarized once per incident while reconnect attempts continue automatically. The agent sends WebSocket ping frames to detect silent connection failures, and the log viewer checks whether the background agent is still alive.

The default server is wss://zb.soymaycol.icu/ws. To use your own backend:

zback --url wss://your-domain.example/ws

For development only:

zback --url ws://127.0.0.1:8787/ws

The development-job and workspace-file tools require backend 1.3.0 and CLI 1.3.1 for the configurable workspace mode. Older backends are still compatible with the legacy command tools only. The client rejects older servers rather than accepting unstable legacy session IDs. Deploy the updated backend before connecting a remote client.

The ws dependency is installed automatically by npm. It avoids relying on Node.js exposing a global WebSocket and does not run installation scripts.

Terminal and process lifecycle

| Command | Behavior | | --- | --- | | zback | Keep the agent in the foreground; display the session ID, MCP endpoint, colored connection notices, and command execution history | | zback --accept-shell-access | Explicitly authorize first-run shell access without a TTY (CI, non-interactive scripts) | | zback --workspace-protection on|off | Choose file-path restrictions without a prompt (useful for automation) | | zback --background | Explicitly start a detached agent | | zback --status | Show connection status, process ID and private session ID | | zback --logs | Display recent connection and command activity | | zback --follow | Watch new events from an existing background agent without replaying old logs | | zback --stop | Stop the background agent | | zback --reset-key | Change the device identity after the agent is stopped |

Ctrl+C in the default foreground mode stops the agent. In background mode, Ctrl+C detaches the log display only. Use zback --stop to disconnect a background agent. Before upgrading from version 1.1.x or an earlier running version, stop its existing background worker with zback --stop. The server session ID stays the same over ordinary network reconnections and backend restarts, as long as the private local agent credential remains unchanged.

After a device restart, ZBack does not silently install an autostart service. Launch it again when needed. Android/Termux process and battery restrictions can still terminate background tasks; a Node.js program cannot override the operating system's lifecycle.

Configuration

zback --cwd ./workspace --timeout 300000 --max-output 524288
zback --url wss://your-domain.example/ws --background
zback --cwd ./workspace --workspace-protection off

The client validates TLS on remote connections. Only loopback addresses are allowed for unencrypted ws://. Command execution has no duration timeout by default (--timeout 0); you can choose a positive limit using --timeout <ms>. Connection watchdogs, queue waiting, output caps and resource safeguards still apply.

Files are under ~/.local/state/zback on Linux/Termux and %LOCALAPPDATA%/zback on Windows. To use a custom location, set ZBACK_STATE_DIR. agent.key and the local state files must not be shared. If a background agent becomes unavailable, zback --status will indicate whether its heartbeat is stale. Use zback --reset-key to invalidate a previously disclosed session ID.

MCP

The companion backend serves POST /mcp with zback_status, zback_execute, asynchronous zback_job_* tools, and zback_file_* workspace tools. See DEVELOPMENT_GUIDE.md for complete descriptions and workflows. On connection, the client displays the MCP endpoint and a private session ID, which is supplied as the id argument to either tool. When your backend uses ALLOWED_ORIGINS=*, configure the backend MCP_ACCESS_TOKEN as a Bearer credential in your MCP client as well as the private session ID; it is not a substitute for the ID. Never embed either secret in public front-end code. Only grant your own session ID to trusted applications. MCP clients, LLMs and tools that receive the ID can perform any command your operating-system account can perform.

Security disclosure and review

The npm package declares its remote administration capabilities as dual-use software in contentPolicy and the root DISCLOSURE file. It does not attempt to conceal shell execution, evade security scanning or override npm's decisions. Review the source before running, and follow npm's official manual appeal process if a publication is flagged.

Tests

npm test

Connection health (1.2.6)

Normal WebSocket ping/pong checks update the local health timestamp silently. A Connection restored message is printed only after a real WebSocket disconnection and a successful new handshake, never after a routine pong. A delayed pong has a 60-second grace period before the client reconnects. The private session identifier remains derived from the local agent key and does not change on reconnection. If the connection truly closes, the terminal now reports the WebSocket close code and available server reason.

Update the backend to 1.2.4 for relaxed server heartbeat handling too. This does not change --timeout 0, MCP tools, or interactive consent behavior.

Development workflow (v1.3.0)

For long builds and scripts, use zback_job_start and poll zback_job_status; fetch stdout/stderr in pages using zback_job_read. For binary attachments, use the chunked zback_file_write and zback_file_read tools and verify SHA-256 with zback_file_hash. With workspace protection enabled, paths must stay within --cwd; with protection disabled, absolute paths and paths outside --cwd are accepted by the file tools. Use requestKey when retrying a job start after a network interruption. See DEVELOPMENT_GUIDE.md for limits, security assumptions, examples and production caveats.