# Local Installation

This guide installs the source checkout into an isolated virtual environment. It does not modify the system Python and does not store provider credentials in the repository.

## Supported baseline

- Python 3.11 or newer; CI and this installation use Python 3.11.
- macOS, Linux, or Windows for the cross-platform desktop UI.
- Windows-only integrations such as AppContainer, Windows Sandbox, Outlook COM, and Office COM conversion remain unavailable on macOS/Linux and degrade gracefully.

## Automated installation

From the repository root:

```bash
./scripts/install_local.sh
```

The installer:

1. selects `python3.11` when available;
2. creates `.venv/` inside the repository;
3. installs `requirements.txt` and `requirements-test.txt` with `uv` when available, otherwise `pip`;
4. creates `~/.local/bin/cowork-local` when that path is free;
5. never replaces an existing launcher or global Python package.

Override the interpreter when necessary:

```bash
COWORK_PYTHON=/path/to/python3.11 ./scripts/install_local.sh
```

## Run

Use the repository launcher:

```bash
./scripts/run_local.sh
```

If `~/.local/bin` is in `PATH`, use:

```bash
cowork-local
```

The launcher changes to the package's parent directory and runs `python -m cowork_local`, which is required by the current source layout.

## Configure credentials

Application state is stored outside Git under `~/.cowork_local/`. Export only the variables you need; `.env.example` documents the supported names. For example:

```bash
export OPENAI_API_KEY="..."
export OPENAI_BASE_URL="https://your-approved-gateway/v1"
export COWORK_SANDBOX_PASSWORD="..."
export COWORK_MS365_UNLOCK_CODE="..."
cowork-local
```

Do not put real values in `.env.example` or any tracked file.

## Verify

```bash
.venv/bin/python -m pytest tests -q
.venv/bin/python -c "import PySide6, pydantic, requests; print('runtime imports OK')"
```

A headless startup smoke test suitable for CI or remote shells is documented in the verification section below:

```bash
cd ..
QT_QPA_PLATFORM=offscreen cowork_local/.venv/bin/python -c \
  "from PySide6.QtCore import QTimer; from PySide6.QtWidgets import QApplication; app=QApplication([]); QTimer.singleShot(1000, app.quit); from cowork_local.app import run; raise SystemExit(run([]))"
```

## Optional document tooling

Install PDF extraction helpers when needed:

```bash
uv pip install --python .venv/bin/python -r requirements-optional.txt
```

LibreOffice is an external application, not a Python package. Install it separately if headless Office-to-PDF conversion is required. Microsoft Office/Outlook COM integration and `pywin32` are Windows-only.

## Update or repair

Pull the desired reviewed revision and rerun `./scripts/install_local.sh`. The operation is idempotent: it reuses `.venv`, reconciles declared packages, and keeps the existing launcher when it already points to this checkout.

The first verified macOS installation is recorded in [installation-log-2026-08-11.md](installation-log-2026-08-11.md).