# Installing the OpenPod companion

You are most likely reading this because someone pointed a coding agent at it.
Follow it exactly. Do not improvise an install: this software runs commands as
the user who starts it, so an install nobody intended is a real problem.

## What you are installing

The OpenPod companion is a small program that runs on this computer. It serves
the OpenPod web app on `http://127.0.0.1:8790/` and drives Pi coding sessions
on this machine. It is the only thing that needs installing; the app itself is
a page the companion serves.

## Steps

1. **Read the manifest.** Fetch `/downloads.json` from the same origin as this
   guide. It lists the current `version`, a `windows` entry, and `macos.arm64`
   and `macos.x64` entries. Any of them may be `null`.

2. **Pick the entry for this computer.** Windows x64 uses `windows`. An Apple
   Silicon Mac uses `macos.arm64`; an Intel Mac uses `macos.x64`.

   **If the entry for this platform is `null`, stop here.** Tell the person
   there is no published package for their platform yet. Do not build from
   source, do not install from a package manager, and do not substitute a
   different platform's package.

3. **Download it** to a temporary directory, resolving the `url` against this
   origin if it is relative.

4. **Verify the checksum before running anything.** Compare the file's SHA-256
   against the `sha256` field.

   - Windows: `Get-FileHash <file> -Algorithm SHA256`
   - macOS: `shasum -a 256 <file>`

   **If it does not match, stop and delete the file.** Do not run it, and do
   not retry more than once. Report the mismatch.

5. **Run the installer.**

   - Windows: run the `.exe`. It is unsigned, so SmartScreen will warn about an
     unknown publisher. Do not disable SmartScreen or any other security
     setting; if it blocks the install, tell the person and let them decide.
   - macOS: open the `.dmg` and copy `OpenPod.app` into `/Applications`. It is
     Developer ID signed and notarized by Apple, so it opens without any
     Gatekeeper prompt. If macOS still refuses it (the file came from a mirror
     rather than the published download), do not run
     `xattr -d com.apple.quarantine`, do not disable Gatekeeper, and do not use
     `sudo`; tell the person and let them decide.

6. **Start OpenPod** from the Start menu or Applications. A window opens onto
   the app.

7. **Confirm it works.** `http://127.0.0.1:8790/` should be answering. Then
   stop and hand back: pairing, choosing a workspace folder and enabling remote
   control are decisions for the person, not for you.

## What not to do

- Do not install Pi, Node or any other dependency separately. The companion
  bundles what it needs.
- Do not copy model-provider tokens anywhere. The companion reuses the Pi
  configuration already on this computer.
- Do not enable remote control on the person's behalf. It is off by default and
  that is deliberate.