@dev-zero/mcp-agent — Zero_SERVER Agent
Android/Termux direct-Agent integration is available in the published package (see ANDROID.md). Native enrollment and direct-Agent readiness are verified on the authorized NX769J Android/arm64 Termux device with @dev-zero/mcp-agent v0.0.19: Device Code confirmation, saved-identity restore, direct Core connection, seven capability sync, authorization Ready, authenticated polling/heartbeat, and Device Ready all completed without a Windows/ADB transport. zero.mobile.devices and zero.mobile.screen_size are also live-verified; direct screenshot currently returns MOBILE_SCREENSHOT_FAILED and remains NOT VERIFIED.
Standalone Zero_SERVER Agent package. The published package does not depend on a developer checkout path.
Not a renamed or republished copy of @miruzero/zero-agent in Zero_HOME.
Android / Termux quick start
npm install -g @dev-zero/mcp-agent@latest
zero-agent remote
On first interactive run, remote displays a short XXXX-XXXX Device Code if this Termux
installation is not enrolled yet. The user explicitly confirms that code in ChatGPT;
Zero calls zero.mobile.confirm, the phone stores its identity under app-private
~/.zero-agent/identity.json, and startup continues. zero-agent enroll remains only as a
legacy explicit invitation/recovery path.
A direct Android Agent advertises mobile_android_devices,
mobile_android_screen_size, and mobile_android_screenshot under the public
zero.mobile.* route. The selected direct-device serial is currently local; callers
must still use the serial returned by the live tool. This path does not depend on a
Windows Agent or ADB transport. Android uses authenticated polling + heartbeat by
default; the long-lived realtime channel remains a desktop default and is Android
opt-in with ZERO_ANDROID_REALTIME_CHANNEL=1.
Windows quick start
Use the scoped package name to avoid the older global zero-agent binary:
npx -y @dev-zero/mcp-agent@latest remote
This Agent connects to the Zero_SERVER gateway and securely restores its per-user local identity when available. Run npx -y @dev-zero/mcp-agent@latest --help for the available commands.
On a brand-new Windows user/Chrome installation, select or create a Chrome profile
and sign in at https://chatgpt.com/ when the Agent reports a missing local
session. During first Device Code enrollment the Agent keeps polling and rechecks
the Chrome session without generating another code or requiring a restart; it
never claims successful authorization until real local ChatGPT proof passes.
If the Device Code expires, start a new enrollment. No Remote connection to the
new machine is needed for the local Chrome sign-in step.
For a source checkout:
Set-Location C:\path\to\zero-agent
npm install
npm start
npm start invokes this package's own bin/zero-agent.mjs CLI.
Normal startup hides internal telemetry (ZERO_AGENT_*) and the local pairing
URL; it only shows actionable connection status or the browser Device Code
when approval is actually required. Run npm start -- --debug to see the
internal Local UI address, protocol events and channel errors for diagnosis.
The local status UI is still bound to loopback and available even when its URL
is not printed. Channel failures remain visible as a plain-language warning;
they never produce a false Device ready message.
When an older Zero Agent is listening on the configured Local UI port (default
8054), startup verifies its Windows process owner and exact Agent entrypoint,
checks that the successor has a decryptable DPAPI identity, then stops the old
Agent process tree and starts the replacement. No manual PID kill is needed.
An unrelated listener is never stopped, and startup fails closed if ownership
or credentials cannot be verified. Tests use an isolated ephemeral port.
For an in-source Zero_SERVER checkout only, first startup may copy an existing
state/agent/worker-credential.dpapi into the user-local AppData vault, without
overwriting or removing the original file. Independently installed packages do
not read a sibling project tree.
If there is no enrollment identity, Agent starts its local MCP, contacts Core
and automatically requests a 15-minute Device Code. Confirm that code in the
registered ChatGPT OAuth page; after local ChatGPT session verification, Core
issues a distinct Device ID and the Agent securely persists its identity.
If %LOCALAPPDATA%\ZeroAgent\identity.dpapi exists, it restores that identity
without requesting a new code. The legacy enroll command remains optional.
npm run doctor prints CLI usage; npm run status queries the localhost Agent UI.
Code is self-contained under bin/ and src/ and uses only declared dependencies.
Core owns OAuth grant authority, registry, routing and global UI. The Agent owns
local credentials, ChatGPT-session proof, outbound channel, worker and local UI.
Status: Bundled defaults start the authenticated local MCP with platform-appropriate capabilities. Windows enables the verified PC/Computer Use surface and portable ADB mobile discovery when available. Android keeps destructive computer control disabled by default, exposes read-only filesystem/process compatibility tools, and advertises the direct zero.mobile.* device/size/screenshot route without host ADB. On NX769J, native Android enrollment, identity restore, seven-tool capability sync, authorization, polling/heartbeat, Device Ready, direct mobile discovery, and zero.mobile.screen_size were verified with v0.0.19. The live screen result is 1116x2480 with scale 2.23125. zero.mobile.screenshot remains NOT VERIFIED. Newer builds classify screenshot failures precisely and never escalate automatically; an explicitly authorized rooted Android can opt into the fixed root fallback with ZERO_ANDROID_ROOT_SCREENSHOT=1.
The frozen beta under packages/zero-agent is a separate historical runtime
that still supports system.info for existing live users. A real new-user
ChatGPT OAuth callback, production Agent replacement and reconnect remain
unverified acceptance gates.
Atlas subagent routing (Native only)
Zero Core's zero.subagent selects canonical Atlas identities and returns a native
spawn manifest. Host-native ChatGPT subagent tools carry out execution; Zero
Agent Local does not run Atlas workers. The old zero.subagent.execute →
zgpt_atlas_worker queue-and-dispatch path has been retired. The legacy
ZERO_AGENT_ATLAS_TOOLS and ZERO_AGENT_ZGPT_TOOLS switches no longer
advertise or enable an Atlas worker. Existing task records remain readable
for historical status and audit.
The separate src/tools/zero-chatgpt-client.mjs module remains in the source
tree, but it is not registered as a local Atlas worker.
Publishing with EOTP
The Agent's source-only release helper follows the validated Zero EOTP release workflow. It calls the installed zero eotp npm --json, passes the resulting 6-digit TOTP only to the child npm process through npm_config_otp, and never logs or stores the code. The helper is excluded from the published Agent tarball.
Set-Location C:\path\to\zero-agent
npm run release:eotp:check # Tests, pack audit, public-registry version check; NO publish
npm run release:eotp # Verify npm login, obtain new EOTP, publish, verify registry
This needs a normal online PowerShell session running as the Windows user who configured zero eotp npm. If the environment enforces npm_config_offline=true, the helper reports NPM_OFFLINE_ENV without attempting a false publish. The npm account token needs permission to publish @dev-zero/mcp-agent; possessing a valid OTP alone does not grant package permissions. An OTP error (EOTP) is distinct from Registry HTTP404 (version absent, permissions, or package access). A release is VERIFIED only when the registry serves the exact published version; no automatic version bump, process restart, or npm global install occurs.
Publish metadata: @dev-zero/mcp-agent is configured for public npm distribution with publishConfig.access=public. Packaging readiness is not proof of a successful registry publication. Project runtime and credentials remain on the local machine; do not include them in an npm archive.
Local Agent CLI (npm / npx)
The following commands use the installed package, not project-global state:
```powershell npx -y @dev-zero/mcp-agent@latest help npx -y @dev-zero/mcp-agent@latest kill npx -y @dev-zero/mcp-agent@latest remove ```
- help: print supported CLI commands.
- kill: stop an existing local Zero Agent only when Windows user, executable, process command, listening port, and Agent HTTP status can be verified. Unrelated processes are never terminated.
- remove: perform the same verified stop, then unregister the owned `zero-agent://` URL launcher in the current Windows user registry. It preserves DPAPI identity, sessions, profile, database, and npm cache. It does not revoke Core OAuth grants or uninstall the npm package.
- When no local Agent is running, `kill` returns `{"command":"kill","stopped":false}` and exit 0. `remove` reports whether the registered launcher was removed.
- If ownership is unverified, both commands refuse to stop the target.
Agent Startup Details
Running npx -y @dev-zero/mcp-agent@latest remote prints the installed
package version, resolved device name (Android model or desktop hostname), platform/architecture, Node.js runtime,
process ID, localhost UI port and startup timestamp before connecting.
After Core authorization, capability synchronization and a successful authenticated
heartbeat/poll cycle, the Agent prints its Core host, registered local MCP tool count,
verified authorization, transport mode and heartbeat state. Desktop normally reports
Transport: Realtime; Android direct normally reports Transport: Polling.
The console does not print saved identity tokens, Authorization headers, task arguments, file contents or API secrets. Task STARTED/COMPLETED/FAILED lines appear only when an authorized task actually reaches this Agent. Updating an npm package does not replace a running Agent process; restart it to load a new version once it is safe to interrupt any active work.
Linux quick start
Linux hosts use the headless Agent path and the MCP Device Code approval flow. The Agent stores its identity at ~/.zero-agent/identity.json; the directory must be owned by the Agent user and mode 0700, and the identity file must be mode 0600. Unsafe ownership or permissions fail closed.
The default Linux PC catalog is deliberately read-only:
- Linux system, CPU, memory and filesystem information
- Processes visible to the Agent user through
/proc - Directory listing and UTF-8 file reads under approved roots
- Multi-file reads with explicit byte and time budgets
The default Linux profile does not advertise Win32 Computer Use, PowerShell, Registry, desktop screenshots or clipboard tools. The default allowed root is the Agent user's home directory.
Sensitive Linux controls require separate explicit opt-ins:
- POSIX shell execution:
ZERO_PC_CONTROL_ENABLED=1andZERO_LINUX_SHELL_ENABLED=1 - File writes and allowed-root changes:
ZERO_PC_CONTROL_ENABLED=1andZERO_LINUX_FILE_WRITE_ENABLED=1
The Linux kill command stops only one verified same-UID Agent running from this exact package entrypoint. Linux remove does not run the Windows protocol uninstaller and preserves the identity file.
Linux Core profile
On Linux, npm start runs the Node Core service group on ports 8050, 8051, 8052, 8053, 8055. Nginx ingress and the local Agent service on 8054 are external Linux-managed services; the Windows Nginx validator, Windows process takeover and Windows Local Agent recovery are not invoked by the Linux profile. Use a separately managed Linux reverse proxy and service manager for deployment.