Install PandaNpc and PandaPaw

Updated

A remote coding-agent setup has two independent parts:

  • PandaNpc client — the interface you use to read sessions, send prompts, and approve tools. It runs on the web, iOS, Windows, macOS, and Linux.
  • PandaPaw host — the background service on the computer where Claude Code, Codex, or PandaCode actually executes.

Install only the client for PandaNpc chat and local desktop use. Install both parts when you want to reach a coding agent running on another machine.

See PandaNpc Desktop for what the Windows/macOS/Linux app adds beyond the installer steps below, including its release history.

Choose what to install

Scenario Client PandaPaw host
Use PandaNpc chat in a browser Open the web app Not required
Control an agent on this same desktop Desktop app Depends on the selected local/remote mode
Control a development machine from a phone or browser Install/open a client on the viewing device Required on the development machine
Run agents on a server with no graphical desktop Web, desktop, or iOS elsewhere Required on the server

For the shortest end-to-end path, use the Quick Start Guide.

Install a PandaNpc client

Use the PandaNpc download page as the source of truth for current installers. Avoid third-party download sites because they may serve old or modified packages.

Web

Open pandanpc.com/agent in a current browser. Nothing is installed. Browser storage keeps the local sign-in state, so private/incognito windows may require you to sign in again.

iOS

Follow the App Store link on the download page and install PandaNpc. iOS is useful for checking progress, answering questions, and approving tools while away from the host. The coding process still runs on the connected host machine. See PandaNpc for iOS for what the app covers, including its release history.

Windows

  1. Download the current Windows installer.
  2. Run it and follow the installer prompts.
  3. Launch PandaNpc from the Start menu.
  4. If Windows displays a publisher or reputation warning, verify that the file came from pandanpc.com before continuing.

macOS

  1. Download the macOS .dmg.
  2. Drag PandaNpc into Applications.
  3. Launch it from Applications and complete any macOS security prompt.

The macOS build is universal, so the same package supports Apple Silicon and Intel Macs.

Linux

Download the x86_64 AppImage, make it executable, and run it:

bash
chmod +x PandaNpc_*.AppImage
./PandaNpc_*.AppImage

If the AppImage does not start, run it from a terminal once and keep the exact error output. Older distributions may be missing a runtime library required by the desktop shell.

Install PandaPaw on the agent host

PandaPaw currently provides host installers for Windows x64, macOS universal, and Linux x86_64. Run the command on the computer that owns the project files and should execute the agent’s tools.

The recommended route is Connected Devices: choose Add a device, then copy the generated one-time command. It pairs the host with your account during installation.

macOS or Linux

Plain installer with browser authorization:

bash
curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh

Prepared one-time key form:

bash
curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh -s -- --mesh pnkey-xxxx

Windows PowerShell

Plain installer:

powershell
iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iex

Prepared one-time key form:

powershell
$env:PANDANET_KEY="pnkey-xxxx"; iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iex

PowerShell’s iwr | iex pipeline cannot pass normal script arguments, so the Windows installer reads the one-time key from PANDANET_KEY.

What the host installer changes

The installer:

  1. Adds PandaPaw to the current user’s application/bin directory and updates the user PATH when needed.
  2. Registers the appropriate background services to start automatically.
  3. Installs supported coding engines that are missing when the platform allows it.
  4. Supplies a private Node.js runtime when the system does not have a suitable version.
  5. Starts account authorization or redeems the prepared device key.
  6. Records which files it created so uninstall can preserve compatible tools that were already present.

Installing an engine does not automatically buy or authenticate a model subscription. Claude Code and Codex can still ask for their own provider login the first time they run.

Verify the installation

Open a new terminal after installation and run:

bash
pandapaw status

Then open PandaNpc Agent. The host should appear online. Start a session in a test project and ask it to report the current working directory without changing files. This verifies the binary, background service, account pairing, relay connection, engine, and selected directory—not only the download step.

Update

Desktop clients notify you when an update is available. iOS updates through the App Store.

Update PandaPaw and restart its managed services with:

bash
pandapaw update --restart

The updater verifies the downloaded binary against the published SHA-256 checksum before replacing the installed copy. Your account pairing and existing connection identity are preserved. Re-running the install command is also supported when the updater itself is unavailable.

Uninstall

  • Windows client: Settings → Apps → Installed apps → PandaNpc → Uninstall.
  • macOS client: quit PandaNpc, then move it from Applications to Trash.
  • Linux client: remove the AppImage and any launcher you created for it.
  • PandaPaw host: run pandapaw uninstall on the host.

PandaPaw’s uninstall manifest distinguishes tools the installer created from compatible tools that already existed. It is intentionally conservative rather than deleting a pre-existing Claude Code, Codex, PandaCode, or Node installation.

Installation problems

The command finished but the host is not connected

Run pandapaw login. A host install and an account authorization are separate stages, and the installer can complete even if browser authorization was deferred or interrupted.

The shell cannot find `pandapaw`

Open a new terminal. On macOS/Linux, check ~/.local/bin; on Windows, check %LOCALAPPDATA%\Programs\pandapaw. Do not repeatedly reinstall until you have confirmed whether the executable exists and only PATH is stale.

A coding engine failed to install

The host installer treats optional engine downloads as best effort so one provider outage does not remove a working PandaPaw installation. Install or repair that engine using its official installer, authenticate it normally, then run pandapaw status again.

The AppImage or desktop application will not open

Confirm you downloaded the package for the correct architecture, then launch it from a terminal to capture the first error. Include that error and your OS version when contacting support; screenshots of a closed window are usually not enough to diagnose a missing runtime library.

For host-specific connection checks, continue with the PandaPaw guide or the FAQ.