# Installation Guide

## Requirements

- **macOS**: 14 (Sonoma) or higher
- **Messages.app**: Signed in with an Apple ID
- **imsg**: Installed and accessible on `$PATH`
- **Python**: 3.10 or higher
- **Permissions**:
  - Full Disk Access for your terminal (to read `~/Library/Messages/chat.db`)
  - Automation permission for Messages.app (for sending)

### Install imsg

```bash
brew install steipete/tap/imsg
```

Or build from source — see [imsg README](imsg/README.md).

## Install pimsg

### From PyPI (Recommended)

```bash
pip install pimsg
```

### From Source

```bash
git clone https://github.com/dynacylabs/pimsg.git
cd pimsg
pip install .
```

### Development Installation

```bash
git clone https://github.com/dynacylabs/pimsg.git
cd pimsg
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
```

## Verification

```bash
python -c "import pimsg; print(pimsg.__version__)"
```

To verify imsg is reachable:

```bash
imsg chats --limit 1 --json
```

You should see a JSON object. If you see "unable to open database file", grant Full Disk Access to your terminal in System Settings → Privacy & Security → Full Disk Access.

## Docker (HTTP server only)

The HTTP server can be run on the Mac and accessed from a Docker container via `host.docker.internal`.

```yaml
# docker-compose.yml (web frontend container)
services:
  web:
    image: your-web-image
    environment:
      PIMSG_URL: "http://host.docker.internal:8765"
```

The pimsg server on the Mac must bind to `0.0.0.0` for this to work:

```bash
pimsg-server --host 0.0.0.0 --port 8765
```

> **Warning**: Binding to `0.0.0.0` exposes the API on your local network without authentication. Ensure this is firewalled or tunneled appropriately.

### Remote Docker host (Docker on a different machine)

If your web container runs on a different machine than the Mac, `host.docker.internal` won't reach the Mac. Two options:

**Option A — Tailscale (recommended)**

Join both machines to a Tailscale network. Point `PIMSG_URL` at the Mac's Tailscale IP:

```yaml
environment:
  PIMSG_URL: "http://100.x.y.z:8765"
```

pimsg stays bound to `127.0.0.1` if Tailscale routes through the loopback interface, or bind to the Tailscale interface IP specifically.

**Option B — SSH reverse tunnel**

On the Mac, forward the pimsg port to the remote Docker host:

```bash
ssh -R 8765:127.0.0.1:8765 user@docker-host
```

The container can then reach pimsg at `http://localhost:8765`. pimsg stays bound to `127.0.0.1` — nothing is publicly exposed.

## Troubleshooting

### `ModuleNotFoundError: No module named 'pimsg'`
Run `pip install pimsg` or activate the correct virtual environment.

### `FileNotFoundError: imsg not found`
Ensure `imsg` is on your `$PATH`: `which imsg`. If not found, reinstall via Homebrew or add it to your PATH.

### `unable to open database file`
Grant Full Disk Access to your terminal in System Settings → Privacy & Security → Full Disk Access.

### Getting Help
Open an issue at [github.com/dynacylabs/pimsg/issues](https://github.com/dynacylabs/pimsg/issues).
