# Install Polymorfa Inspector

> Install and authorize the desktop app that opens your Numbers as linked devices.

Polymorfa Inspector is a desktop app that opens the WhatsApp Numbers your
Polymorfa account can access. Use it to see the other side of a conversation
with [test numbers](https://docs.polymorfa.com/testing), or to inspect and use a real Number.

> **Note**
>
> **Before you begin.** Inspector requires access. You need a Polymorfa account
> that is a member of the team, and a macOS, Windows or Linux computer.

Real Numbers are interactive: actions in Inspector act as the real WhatsApp
number, including sending messages. Inspector asks you to confirm that before
opening a real Number for the first time.

When Hosted Message Storage is enabled for a real Number, Inspector loads its
retained chats, contacts and messages before continuing with live updates. A
temporary retained-history outage does not stop the live connection; Inspector
marks the history as unavailable instead. Without Hosted Message Storage, the
Number still opens and no retained history is shown.

## Download Nightly

Polymorfa Inspector's development channel is called **Nightly**. Open
[polymorfa.com/inspector/install](https://www.polymorfa.com/inspector/install) to
get the latest Nightly semantic patch. The canonical install page and every
download link resolve to that same release.

Each Nightly publication advances only the patch component of its semantic
version, such as `0.1.1` to `0.1.2`.

The install page reads the Nightly release manifest and offers only the
validated artifacts for the latest release. On macOS, it uses browser
architecture information when available to show the matching download. If the
browser cannot distinguish Apple Silicon from Intel, the page presents both
choices instead of guessing.

| Platform | Architecture | Artifact |
| --- | --- | --- |
| macOS | Apple Silicon | `Polymorfa-Inspector-arm64.dmg` |
| macOS | Intel | `Polymorfa-Inspector-x64.dmg` |
| Windows | x64 | `Polymorfa-Inspector-x64.exe` |
| Linux | x64 | `Polymorfa-Inspector-x64.AppImage` |

Every download has a `SHA256SUMS` sidecar. If the manifest cannot be fetched or validated, the install page shows downloads as temporarily unavailable instead of guessing a release URL.

## Verify and install

**macOS**

Compare the downloaded file's SHA-256 digest with its sidecar, open the DMG, and drag **Polymorfa Inspector** into Applications.

```bash
shasum -a 256 Polymorfa-Inspector-arm64.dmg
# On an Intel Mac:
shasum -a 256 Polymorfa-Inspector-x64.dmg
```

**Windows**

Compare the digest, then run the installer.

```powershell
Get-FileHash .\Polymorfa-Inspector-x64.exe -Algorithm SHA256
```

**Linux**

Compare the digest, mark the AppImage executable, and launch it.

```bash
sha256sum Polymorfa-Inspector-x64.AppImage
chmod +x Polymorfa-Inspector-x64.AppImage
./Polymorfa-Inspector-x64.AppImage
```

Use the Inspector install page to download the current release. Verify the
download against the checksum in the latest release manifest before opening it.

## Update macOS Nightly

Packaged macOS Inspector checks its architecture-specific Nightly feed
automatically. Apple Silicon installations receive only Apple Silicon updates,
and Intel installations receive only Intel updates. When an update is available
and verified, Inspector downloads it and asks you to choose **Relaunch** to
install it or **Later** to keep working. A failed update check does not block
Inspector sessions.

If automatic download or relaunch does not finish, use the latest Nightly DMG
from this page as the recovery path. Verify its checksum, quit Inspector, and
replace the existing app in Applications before reopening it.

## Authorize Inspector

Inspector displays an eight-character device code and does not open your
browser until you ask. Choose **Continue in browser**: Inspector copies the
code to your clipboard, then opens the Console device page. If the copy fails,
Inspector says so and still opens the page; enter the code manually. After the
page opens, the button becomes **Open browser again**, which reopens the page
without copying again. Above the buttons, Inspector shows the full device page
address. Select the address to open the page without copying the code, choose
**Copy sign-in link** to copy the address, or type it on another device.
Copying the address replaces the code on your clipboard, so Inspector asks you
to copy the code again before you approve. If your browser does not open,
open the address manually. Inspector waits for approval either way until the
code expires.

On the device page, complete these checks:

1. Confirm the signed-in account, or choose **Use a different account**.
2. Choose **Paste** to read the copied code from your clipboard, or enter the
   code shown by Inspector. If clipboard access is blocked or contains no
   device code, enter the code manually.
3. Check that the code shown under **Code from Inspector** matches Inspector
   and that you are approving with the right account.
4. Check the requesting app, signed-in account, request time, and available
   city and IP information in the request details.
5. Select the projects Inspector should access. A team checkbox selects its
   current projects. To include all teams and projects you can access now or
   gain access to later, choose **Grant access to all**.
6. Choose **Authorize Inspector**, or **Decline** if you did not start this
   sign-in.

After approval, the browser asks to open Inspector. If Inspector does not open,
choose **Return to Inspector** or switch to it manually. If you approved on
another device, such as your phone, return to the computer running Inspector.
Inspector completes sign-in by itself even when the browser cannot open it.
After you decline, Inspector does not get access and you can close the tab.

If the requested access changes while you retry an unconfirmed approval or
decline, the Console shows the updated request. Review it and select access
again before authorizing Inspector.

Codes are normalized to uppercase letters and digits and cannot be reused after
expiry or a completed decision. Approval creates an Inspector session for the
selected projects without exposing the browser session. A project selection
does not include projects created later. **Grant access to all** follows your
current access, including future teams and projects; it never creates membership
or raises your role. You can review, change or revoke that access under **Account settings → Authentication → Active
sessions** in the Console.

A selected snapshot supports up to 1,000 projects across 100 teams. For a
larger selection, remove projects or choose **Grant access to all** explicitly.

> **Warning**
>
> Approve only when the code exactly matches Inspector. A device code is
> temporary authorization material; do not send it through chat or support.

## Navigate teams and projects

If Inspector reports that your workspace access needs to be renewed, choose
**Sign in again**. Cached numbers stay hidden until a successful access check.
A later connection error does not restore a denied list. Temporary connection
problems on their own keep the last loaded list and offer **Retry now** without
signing you out.

If Inspector cannot confirm access to every team, Home shows a temporary
loading problem instead of an incomplete team or number list. Choose **Retry
now** after the service recovers. A temporary loading failure does not stop
existing connections or mean that your team access was removed. Confirmed
permission changes still take effect.

Opening another tab or the number launcher dismisses an earlier failed-open
panel. A successful open also dismisses it while that open is still your latest
selection. A delayed result from an earlier open does not replace a newer choice.

If another Number is still connecting, switching tabs or opening the launcher
keeps your new selection. The other Number can finish connecting in the background.

On first sign-in, Inspector shows a short setup path: **Sign in**, **Choose
team**, **Open a number** and **Connecting**. The team step appears only when
you authorized more than one team. The last step stays **Connecting** until
WhatsApp reports that the Number is ready.

The team switcher lists only the teams you authorized. It uses each team's
display name and profile image from your Polymorfa account. Teams without a
profile image receive the same generated Glass avatar used in the Console. You
find it at the top of the **Open a number** screen and at the top of the
sidebar.

**Open a number** lists every Number in the selected team, grouped by project.
Teams with more than 10 Numbers also see your recent Numbers first. Each row
shows the Number's name and phone. A row adds **Production** for a real Number,
a status only when it needs attention (for example **Connecting**, **Paused**,
**Stopped** or **Not running**), and **In use by _name_** when another member
uses it. Test Numbers carry no label. Type in the search field to
find a Number by name, phone, project or Customer. Use the arrow keys to move
between rows and Enter to open the selected one. A Number that is already open
shows **Switch to tab**. A Number in use by another member shows **In use by
_name_** and can't be opened. A claimed Number shows its claimant's avatar
before the action; hover it to see **Claimed by you** or **Claimed by
_name_**. An unclaimed Number shows no avatar.

Open the screen at any time with **Open a number** in the title bar, or with
⌘T on macOS and Ctrl+T on Windows and Linux. The shortcut works while WhatsApp
has focus; ⌘K and Ctrl+K stay with WhatsApp. Press Escape to clear a search and return focus to the search field.
With an empty search, Escape returns to your previous tab if one is available.

Each project has a **Test key** button for its test key. Project owners and
administrators also see **Add test number**, which opens the project's test
number setup in the Console. If a team has no projects, **Open Console**
takes you to create one; **Check again** reloads the list.

Open Numbers appear as tabs. Each tab shows the Number's name, its project and
**Production** for real Numbers, so two Numbers with the same name stay
distinct. The status dot is green only after WhatsApp reports the Number is
ready. Hover or focus a tab to see its name, phone, project and status. In the list, **Not running** means the Number
isn't running on Polymorfa right now. Use the arrow keys to move between tabs, Enter to switch, and Delete to
close the focused tab. Tabs that don't fit move into a **+_n_** menu.

A Production Number keeps a thin bar above WhatsApp with **Production**, its
phone and its project. Test Numbers have no bar, so WhatsApp gets the full
height. To copy a Number's phone or ID, right-click its tab or its sidebar row,
or focus it and press Shift+F10, then choose **Copy phone number** or **Copy
UID**. Tabs also show an actions button (three dots) on hover and focus. The title bar confirms the copy.

While a Number is open, the sidebar lists the team's projects and Numbers with
the same **Production** and status labels. Resize it by dragging
its right edge, or hide it from the title bar or with ⌘S on macOS and Ctrl+S
on Windows and Linux. The sidebar stays hidden while **Open a number** is on
screen and returns as you left it. Menus, settings and dialogs remain above
WhatsApp while open.

The account that first completes native pairing claims that Number through
Inspector. The Console shows the claimant's name and account photo when
available. Inspector shows the claimant's avatar; hover it to see **Claimed by
you** or **Claimed by _name_**. A Number used by another member also shows
**In use by _name_**. Other authorized project members can see the claimant but
cannot silently take over the Number.

Closing Inspector, retrying a failed connection, restarting the app, or signing
out of the dashboard keeps the native linked device. Reopening the number on
the same computer restores its chats and reconnects without pairing again.
Removing the number or transferring its Inspector ownership invalidates the
retained device.

## Theme and language

These instructions apply when your installed Inspector release shows **Theme**
and **Language** in the account menu. Earlier releases have an appearance
control in the top bar instead and show Inspector in English. Downloading an
older release does not add these options.

Open the account menu at the top right of Inspector. The menu offers the same
options whether or not you are signed in, and a choice applies immediately.

Under **Theme**, choose **System**, **Light** or **Dark**. Inspector passes the
resolved preference to WhatsApp. When Inspector's theme is **System**, Inspector
follows operating-system changes.
Changing the theme doesn't reload open Numbers.

Under **Language**, choose one of these options:

| Option | Inspector language |
| --- | --- |
| **Match account** | The language saved on your Polymorfa account. This is the default. |
| **Automatic** | The first supported language in your operating system's language list, English or Portuguese. If neither appears, English. |
| **English** | English. |
| **Português (Brasil)** | Brazilian Portuguese. |

**Match account** behaves like **Automatic** when you are signed out, when your
account language is set to **Automatic**, or when Inspector cannot read your
account. Inspector rereads your account language when it reloads your Numbers. It
never changes the language saved on your account; set that in the Console
under [Language](https://docs.polymorfa.com/teams/language).

Changing the language does not reload or disconnect open WhatsApp tabs.
WhatsApp keeps its own language.

## Diagnostic error reports

These instructions apply when your installed Inspector release shows **Share
diagnostic error reports**. Availability depends on the installed release;
downloading an older release does not add the preference.

In releases with **Theme** and **Language** in the account menu, open the
account menu and select **Diagnostic reports**. In earlier releases, open the
appearance control in the top bar.

Reporting starts off. Turn it on to share error categories, application source
positions, and the app version with Polymorfa. Turn it off to stop new reports. This is a
local preference, separate from permission to open real Numbers.

Reports exclude message text, account details, credentials, request bodies, and
local file paths. Reporting pauses during sign-in and device authorization and
does not collect errors from embedded WhatsApp pages. Error reporting does not
enable Hosted Message Storage or upload your chats.

If Inspector says reporting is not configured in this build, leave it off and
use [the support instructions](https://docs.polymorfa.com/testing/inspector/troubleshooting#get-help).

## Next steps

- **[Open a Number in Inspector](https://docs.polymorfa.com/testing/inspector/devices)**
Open a test number as a linked device.

- **[Send your first test message](https://docs.polymorfa.com/testing/quickstart)**
Create two test numbers and message between them.

- **[Troubleshooting](https://docs.polymorfa.com/testing/inspector/troubleshooting)**
Diagnose Inspector and connection issues.
