# Installation & Setup

Source: https://inspectorlab.dev/installation

> For the complete documentation index, see [llms.txt](https://inspectorlab.dev/llms.txt).

# Installation & Setup

Inspector Lab installs in one click from the Chrome Web Store on desktop Chrome, Chromium browsers, and Orion — including iPadOS and iOS. Installing from source remains available for development and for sideloading a local build.

<Callout type="success">
Inspector Lab is live on the [Chrome Web Store](https://chromewebstore.google.com/detail/inspector-lab-devtools/jhpgckgieinonbibmjdgejephdmdogle). This is the primary install path on every supported browser, including Orion on iPad and iPhone — one click, no build step, automatic updates.
</Callout>

## Install from the Chrome Web Store

<Steps>
  <Step title="Open the listing">
    Go to [Inspector Lab - DevTools on the Chrome Web Store](https://chromewebstore.google.com/detail/inspector-lab-devtools/jhpgckgieinonbibmjdgejephdmdogle). On iPad or iPhone, follow [Orion on iPadOS and iOS](#orion-on-ipados-and-ios) below instead.
  </Step>
  <Step title="Add the extension">
    Click **Add to Chrome** (Orion shows its own install prompt) and confirm. The extension appears in your toolbar, ready to use. Store installs update automatically as new versions are published.
  </Step>
</Steps>

That is the whole install for desktop. Everything below covers Orion on iOS/iPadOS, macOS, and building from source — only needed for sideloading or development.

---

## Orion on iPadOS and iOS

<Callout type="info">
[Orion by Kagi](https://orionbrowser.com/) is the only iPad browser that runs Chrome extensions and is [free for iPhone and iPad](https://apps.apple.com/app/id1484498200). Install Orion first if you have not already.
</Callout>

### Step 1 — Enable Chrome extensions (once)

<Steps>
  <Step title="Open the Extensions screen">
    Tap the **three dots** (**⋯**) in the toolbar and choose **Extensions**.
  </Step>
  <Step title="Turn on Chrome extensions">
    Turn on **Chrome extensions**.
  </Step>
</Steps>

### Step 2 — Install Inspector Lab from the store

<Steps>
  <Step title="Open the Extensions screen">
    Tap **⋯ → Extensions** (you are already there if you just enabled Chrome extensions).
  </Step>
  <Step title="Open the Web Store">
    Tap the **+** button in the bottom right, then choose **Install from the Chrome Web Store**.
  </Step>
  <Step title="Install Inspector Lab">
    Search for **Inspector Lab - DevTools** or open [the listing](https://chromewebstore.google.com/detail/inspector-lab-devtools/jhpgckgieinonbibmjdgejephdmdogle) directly and confirm. It appears in your extensions list.
  </Step>
</Steps>

<Callout type="note">
Orion may warn about compatibility during install — the warning is informational and expected. The extension is built for iOS's reduced API surface and works as designed.
</Callout>

### Step 3 — Use the inspector

<Steps>
  <Step title="Enable the extension">
    Check that **Inspector Lab - DevTools** is enabled in the Extensions list.
  </Step>
  <Step title="Open a website">
    Navigate to any normal website (`http://` or `https://`).
  </Step>
  <Step title="Launch the inspector">
    Tap the extension icon in the toolbar, then tap **Inspector Lab - DevTools**, then tap **Open page inspector**.
  </Step>
  <Step title="Grant site access">
    **Allow site access** when Orion asks. The Cookies panel stays empty without it, and console capture from page load also needs it.
  </Step>
</Steps>

The inspector docks to the bottom of the page. Drag the toolbar to tear it off into a floating window, or use the dock buttons to pin it to another edge. It survives page reloads until you close it with the **X**.

---

## What to expect on iOS and iPadOS

Kagi documents iOS and iPadOS extension support as **beta with a reduced API surface**, because Apple caps what any iOS browser may expose. Inspector Lab is built for that: wherever the extension background cannot be reached, panels fall back to in-page sources instead of going dark, and each one says on screen which source it is using.

**Verified on a real iPad:**

| Panel | Status | Notes |
|-------|--------|-------|
| **Elements** | <Icon name="check" size={16} color="green" /> Works | Fully in-page; no extension APIs needed. |
| **Console** | <Icon name="check" size={16} color="green" /> Works | Captures logs and evaluates expressions. Falls back to in-page scripts when the extension does not answer. Corrects iOS Smart Punctuation automatically — type `console.log("log")` and the keyboard's curly quotes and em-dashes are fixed if they blocked parsing. Sites whose Content Security Policy forbids inline scripts or `eval` block the fallback — the error says so. |
| **Sources** | <Icon name="check" size={16} color="green" /> Works | Fully in-page; no extension APIs needed. |
| **Cookies** | <Icon name="check" size={16} color="green" /> Works | Lists, adds, edits, and deletes cookies. Falls back to `document.cookie` when extension is unreachable; cannot see HttpOnly cookies in fallback mode. |
| **Storage** | <Icon name="check" size={16} color="green" /> Works | Fully in-page; no extension APIs needed. |
| **Network** | <Icon name="triangle-alert" size={16} color="orange" /> Partial | Captures fetch/XHR live with headers and bodies. Static resources (documents, stylesheets, images, fonts) come from the Performance timeline without header details, because `chrome.webRequest` is not available on iOS. |

If a panel reports a specific error instead of data, that message is the ground truth — it names the API or policy that refused, rather than a generic connection failure.

---

## Orion on macOS

Orion on macOS installs Chrome Web Store extensions directly and exposes the fuller desktop API surface. Open [the Chrome Web Store listing](https://chromewebstore.google.com/detail/inspector-lab-devtools/jhpgckgieinonbibmjdgejephdmdogle) in Orion and install. For the current extension settings menu (which moves between Orion releases), see [Kagi's extension documentation](https://help.kagi.com/orion/browser-extensions/browser-extensions.html).

---

## Build and sideload from source

Clone the repository and build the unpacked extension:

<Steps>
  <Step title="Clone and install">
    ```bash
    git clone git@github.com:luangjokaj/inspector-lab.git
    cd inspector-lab
    pnpm install
    ```
  </Step>
  <Step title="Build the extension">
    ```bash
    pnpm build
    ```
    
    This writes the unpacked extension to `apps/extension/build/chrome-mv3-prod/`. That folder **is** the extension — `manifest.json` sits at its top level.
  </Step>
  <Step title="(iPad only) Create a zip package">
    If you are installing on iPad or iPhone, create a 1.2 MB zip to transfer:
    
    ```bash
    pnpm package
    ```
    
    This generates `apps/extension/build/chrome-mv3-prod.zip`.
  </Step>
</Steps>

---

## Desktop Chrome, Edge, Brave, and Chromium (local build)

Once you have built the extension:

<Steps>
  <Step title="Open the extensions page">
    Navigate to `chrome://extensions` in your browser.
  </Step>
  <Step title="Enable Developer mode">
    Toggle **Developer mode** in the top right corner.
  </Step>
  <Step title="Load the unpacked extension">
    Click **Load unpacked** and select `apps/extension/build/chrome-mv3-prod`.
  </Step>
</Steps>

The extension is now installed and ready to use. For development, run `pnpm dev` instead of `pnpm build` — this writes to `apps/extension/build/chrome-mv3-dev` and reloads as you edit. Load that folder the same way.

---

## Orion on iPadOS and iOS (sideloaded build)

<Callout type="info">
Store installs are strongly recommended — they update automatically. Sideload only when testing unreleased changes. Sideloaded extensions never auto-update.
</Callout>

Orion's file installer only lists folders that are already in its own Extensions directory, so the folder must be moved there before you open Orion's extension screen.

### Get the folder onto the iPad

<Steps>
  <Step title="Transfer the zip to iPad">
    Move `chrome-mv3-prod.zip` to your iPad via AirDrop, iCloud Drive, or browser download. It normally lands in the **Downloads** folder in the Files app.
  </Step>
  <Step title="Uncompress the zip">
    Open the **Files** app, find the zip, long-press it, and tap **Uncompress**. You get a folder named `chrome-mv3-prod`.
  </Step>
  <Step title="Navigate to Orion's Extensions folder">
    In Files, go to **Browse → On My iPad → Orion → Extensions**.
    
    <Callout type="note">
    If no **Orion** folder exists, open the Orion app once — it creates the folder on first launch — then look again. Orion's own file picker calls this location **On This iPad** instead of **On My iPad**, but it is the same place.
    </Callout>
  </Step>
  <Step title="Move the folder into Extensions">
    Long-press the `chrome-mv3-prod` folder, tap **Move**, and pick `Orion/Extensions`. Dragging it across in Split View also works.
  </Step>
</Steps>

At this point, `On My iPad → Orion → Extensions → chrome-mv3-prod` exists and contains `manifest.json`. The extension is not yet installed in Orion.

### Install in Orion

<Steps>
  <Step title="Open Orion and access extensions">
    Open **Orion**, tap the **three dots** (**⋯**) in the toolbar, then tap **Extensions**.
  </Step>
  <Step title="Open the file picker">
    Tap the **+** button in the bottom right and choose **Install from File**.
  </Step>
  <Step title="Select the folder">
    The folder picker opens. Select the **`chrome-mv3-prod`** folder you moved in the previous step — pick the _folder itself_, not a file inside it.
  </Step>
  <Step title="Confirm installation">
    Confirm. Orion installs it, and **Inspector Lab - DevTools** appears in the extensions list.
  </Step>
</Steps>

### Updating a sideloaded build

Sideloaded extensions never auto-update. To move to a newer build:

1. Delete the old `chrome-mv3-prod` folder from **On My iPad → Orion → Extensions**.
2. Drop the new one in its place using the steps above.
3. Install it again using the **+ → Install from File** flow.

Removing the old folder first matters — two folders with the same manifest name make the picker ambiguous.

---

## Troubleshooting

<Accordion title="The picker does not show my folder.">
The picker only browses Orion's own Extensions directory. The folder must be at **On My iPad → Orion → Extensions**, not in Downloads or iCloud Drive.
</Accordion>

<Accordion title="I moved the zip instead of the folder.">
Orion needs the unpacked folder. Long-press the zip, tap **Uncompress** first, then move the resulting folder.
</Accordion>

<Accordion title="I picked a file and it failed.">
Select the `chrome-mv3-prod` folder itself, not a file inside it. The installer reads `manifest.json` from the folder's top level.
</Accordion>

<Accordion title="No Orion folder in Files.">
Launch Orion once. The folder is created on first run.
</Accordion>

<Accordion title="Nothing happens when I tap Open page inspector.">
The inspector only runs on `http://`, `https://`, and `file://` pages. Browser settings pages and other internal URLs are protected and out of reach for any extension.
</Accordion>

<Accordion title="The Cookies panel is empty.">
Site access was not granted. Relaunch from the popup and allow it when asked.
</Accordion>

---

## Next steps

Once the extension is installed and running, explore its capabilities:

<Columns cols={2}>
  <Card title="Features & Capabilities" icon="sparkles" href="/features">Learn what each panel does and how to use it.</Card>
  <Card title="Elements Panel" icon="code" href="/panels-elements">Start inspecting and editing the DOM.</Card>
</Columns>