93 lines
3.0 KiB
Markdown
93 lines
3.0 KiB
Markdown
# 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).
|