PandaPaw turns a Windows, macOS, or Linux machine you control into a PandaNpc agent host. The coding engine, project files, shell, and tools remain on that host; PandaNpc clients give you a synchronized interface from a phone, browser, or another desktop.
Use PandaPaw when the machine doing the work is different from the device you are holding, when you want a host to survive client disconnects, or when several coding engines should share the same account-based setup and Agent Center configuration.
What PandaPaw manages
- Remote agent connections for Claude Code, OpenAI Codex, and PandaCode.
- Background services and autostart so the host can return after a normal reboot.
- Account-based machine authorization without manually copying a long-lived Bridge ID, token, or signing key.
- Engine installation assistance when a supported coding engine is missing.
- Agent Center projections that render each engine’s guidance, skills, memory, and agent definitions in its native layout.
- Private device networking for machines joined through the Connected Devices flow.
- Update and uninstall bookkeeping so tools that existed before PandaPaw are preserved.
PandaPaw does not provide a model subscription by itself. Claude Code, Codex, and PandaCode still use the provider credentials and limits configured for their engine.
How remote execution works
Both sides initiate outbound connections, so a normal home or office setup does not require an inbound firewall rule, public IP address, router port forwarding, or a publicly exposed SSH server. The relay transports messages, status, and approvals; tool execution happens on the host.
If the host sleeps, powers off, or loses its outbound network path, the saved connection remains in your account but cannot execute work until the host returns.
Supported host platforms
| Host platform | Package | Notes |
|---|---|---|
| Windows x64 | Native executable and user-level services | Run the installer in PowerShell |
| macOS, Apple Silicon or Intel | Universal PandaPaw application/binary | The same package supports both architectures |
| Linux x86_64 | Native binary and user service | Intended for common glibc-based distributions |
The PandaNpc viewing client has a broader platform matrix. See Install PandaNpc and PandaPaw when choosing client and host packages.
Recommended installation
- Sign in to PandaNpc.
- Open Connected Devices.
- Choose Add a device. A one-time key is issued and the dialog shows one command for the detected operating system.
- Copy that command to the host and run it there.
- Leave the dialog open if you want it to detect the new machine automatically.
The prepared key is single-use. Copy the entire command, keep it private, and generate a new one if it expires or was already redeemed.
Plain macOS/Linux installer
Use this form when you want browser authorization instead of a prepared key:
curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | shPlain Windows PowerShell installer
iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iexThe plain installer runs pandapaw login. Approve the machine in the browser page it opens. If authorization is interrupted, the binary and services can still be installed; run pandapaw login later to finish the account connection.
Verify the host
First check the host itself:
pandapaw statusThen open PandaNpc Agent and confirm that the machine has a green online indicator. Start a session in a disposable or read-only test directory and ask:
Test prompt: Print the current working directory and list the top-level files. Do not modify anything.
A successful reply proves more than a green status light: it verifies account pairing, relay connectivity, the selected engine, provider authentication, and the working-directory mapping.
For an Agent Center project, run:
pandapaw agent status --root /absolute/path/to/projectThis shows whether the project is bound and whether managed configuration is available locally. A stable Git remote helps PandaPaw identify the same project across machines.
Account authorization and connection identity
pandapaw login uses a browser device-authorization session. After you approve it, the host receives device-scoped credentials and an Agent Center verification key over TLS, writes its machine configuration under ~/.pandapaw/, registers the supported engine connections, and binds recognizable Git projects.
Run pandapaw login --force only when intentionally switching accounts or replacing an expired host credential. Reauthorizing a healthy machine without a reason can create confusing duplicate or replaced identities.
pandapaw qr still creates a short-lived manual connection link for compatibility and special cases. It is not the primary flow for a new host; Connected Devices is easier to audit and does not require users to understand Bridge IDs.
Agent Center synchronization
Agent Center is event-driven in steady state:
- Local managed-file changes are detected and published to the bound project.
- Signed releases arrive through an event stream.
- Unchanged manifests and content blobs are reused rather than downloaded again.
- A periodic recovery check catches events missed during a temporary disconnect.
Claude Code, Codex, and PandaCode receive separate projections because they expect different directories and instruction formats. PandaCode prepares the latest verified release before assembling a new session prompt, so configuration pulled at startup can affect that same session.
If Agent Center is temporarily unavailable, the engine continues with the last verified local release. A network failure should not silently replace signed configuration with unverified content.
Useful commands
pandapaw login
pandapaw status
pandapaw agent status --root /absolute/path/to/project
pandapaw update --restart
pandapaw uninstall| Command | Use it for |
|---|---|
pandapaw login |
Authorize an installed machine that is not yet connected to an account |
pandapaw status |
Check installed services, machine connection, and basic health |
pandapaw agent status --root … |
Inspect Agent Center state for one project |
pandapaw update --restart |
Verify, install, and activate the newest PandaPaw release |
pandapaw uninstall |
Remove PandaPaw-managed services and files conservatively |
Check the PandaPaw version history when a command or UI differs from an older screenshot or tutorial.
Security boundaries
- A remote operator can exercise whatever tools and working directory the selected agent session permits. Remote access is not automatically read-only.
- Keep one-time device commands, manual connection links, provider keys, and account tokens out of logs and screenshots.
- Do not open inbound router ports just to make PandaPaw reachable.
- Remove hosts you no longer own from Connected Devices.
- Review tool approvals and verify the working directory before allowing edits or shell commands.
- When sharing a live connection, the recipient consumes the host owner’s engine quota and can act on the host. Read Connection Sharing first.
Troubleshooting
`pandapaw` is not found after installation
Open a new terminal so it reloads the user PATH. The normal locations are ~/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\pandapaw on Windows. Confirm the file exists before rerunning the installer.
Installation succeeded, but no machine appears
Run pandapaw status. If the machine has no account authorization, run pandapaw login. If a prepared one-time key was used, create a new key rather than retrying a consumed command.
The machine appears but stays offline
Confirm the host is awake and has internet access. Check the PandaPaw status locally. A corporate proxy or firewall must allow the outbound HTTPS/WebSocket path; an inbound port does not solve a blocked outbound connection.
The host is online, but Claude Code or Codex will not answer
Pairing the host does not authenticate every model provider. Open the engine locally or follow the login prompt shown in the remote session. Also confirm that the selected model exists for that account and its usage limit is not exhausted.
The session opens in the wrong project
End the test, select the intended absolute working directory, and ask the agent to print it before approving tools. PandaPaw does not guess which repository you meant and does not add a filesystem sandbox beyond the engine’s own permission model.
Agent Center changes do not appear
Run pandapaw agent status --root /path/to/project from the correct Git root. Confirm the project is bound, the host is logged in, and the local file is part of a managed projection. Keep the last verified release in place while investigating instead of deleting managed directories.
Update and uninstall
pandapaw update --restart downloads the current binary, verifies its SHA-256 checksum, replaces the installed copy, and restarts the managed services so the version becomes active. Existing account pairing is preserved.
pandapaw uninstall uses the install manifest to remove items PandaPaw created. Compatible Claude Code, Codex, PandaCode, or Node installations that were already present are intentionally preserved. After uninstalling, remove the host from Connected Devices if it should no longer be trusted.