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:

./scripts/install_local.sh

The installer:

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

Override the interpreter when necessary:

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

Run

Use the repository launcher:

./scripts/run_local.sh

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

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:

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

.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:

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:

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.

3.0 KiB Raw Permalink Blame History