Installation¶
Requirements¶
Use Python 3.11 or newer. Source discovery and the native background service are designed primarily for macOS. The Python package includes the CLI, Textual terminal dashboard, and prebuilt browser interface. It does not include the optional compiled Tauri desktop executable.
One-Command Setup¶
Use this for a new installation. With Python 3.11+ available as python3:
You can also download and inspect the setup script, then run bash install.sh locally. The script installs the current PyPI release. To choose a version or interpreter:
Setup creates an isolated environment at ~/.local/share/aesop-agentic/venv, adds a command at ~/.local/bin/aesop, and creates ~/.config/aesop-agentic/config.toml if it does not exist. New configurations use ~/Aesop for the workspace and select the browser interface. Existing configuration, source selections, and interface preferences are preserved.
The script prints a ready-to-run browser command and any required PATH adjustment. It does not edit shell startup files, collect data, request browser logins, install a service, or enable notifications. Keep the environment in place while using its commands or any service you later install from it.
Review the Default Backup Destination
New configurations include a required iCloud Drive mirror at ~/Library/Mobile Documents/com~apple~CloudDocs/AgentData. Edit or remove that destination before running aesop run if you use another backup location. See Configuration.
Install From Source¶
From the root of a checkout or unpacked source distribution:
This installs a packaged copy into the same managed environment; it does not create an editable developer installation. Rerun it after changing source code. The source distribution includes the browser assets. Building the optional native desktop component is a separate step.
GitHub access is required to clone the private repository. Public source releases can be downloaded from PyPI. The setup script is included in source releases made after its introduction; with an older source release, download the script above and run bash /path/to/install.sh --source ..
Setup Options¶
Run bash docs/install.sh --help for all options. Each path can be customized:
| Option | Default or Behavior |
|---|---|
--source PATH |
Install a local source directory instead of PyPI. |
--version VALUE |
Select a PyPI version; cannot be combined with --source. |
--python PATH |
Use a particular Python 3.11+ interpreter. |
--venv PATH |
Defaults to ~/.local/share/aesop-agentic/venv. |
--workspace PATH |
Defaults to ~/Aesop; used only for a new configuration. |
--config PATH |
Defaults to AESOP_CONFIG, if set, or the usual Aesop configuration path. |
--bin-dir PATH |
Defaults to ~/.local/bin. |
The installer refuses to replace an unrelated environment or an existing command. Choose different paths if you maintain another Aesop installation. Repeating setup preserves existing configuration and upgrades the package in the managed environment.
Install With pip¶
If you already have an appropriate Python environment:
Initialize a permanent archive workspace in one command, then open the interface:
aesop setup records the current directory as the workspace and refuses to overwrite an existing configuration. When upgrading an existing installation, skip initialization. Neither opening the browser nor running setup starts collection.
If your Python is externally managed, use the setup script rather than modifying the system environment. For editable installation and manual virtual-environment setup, see Contributing.
Continue with First Archive.
Optional Browser Capture¶
For script-managed installations, use the environment’s Python directly:
~/.local/share/aesop-agentic/venv/bin/python -m pip install 'aesop-agentic[browser]'
~/.local/share/aesop-agentic/venv/bin/python -m playwright install chromium
aesop login chatgpt
For pip-managed installations, substitute python from the same environment for the explicit interpreter path above.
Complete sign-in in the dedicated window. Profiles live under ~/.local/state/aesop-agentic/browser-profiles/ and are excluded from the archive. Do not reuse your everyday browser profile. Official exports are preferable when available; browser collection remains partial.
Optional macOS App and Service¶
For scheduled collection and native notifications, see macOS Service. For a Tauri window, follow the desktop build instructions. The service requires Apple's Command Line Tools to compile its native launcher; a Tauri build also needs Node.js/npm and Rust/Cargo.
Upgrade or Uninstall¶
For script-managed installations, rerun the same setup command, including any custom path options. It upgrades the package while preserving existing configuration. For a pip-managed installation, run python -m pip install --upgrade aesop-agentic in its Python environment.
If installed, rerun aesop service install after upgrading so the managed app uses the current launcher and resources. Do this while no collection is running.
To uninstall the scheduled service, run aesop service uninstall before removing the Python environment. For a pip-managed installation, python -m pip uninstall aesop-agentic removes the package. For script-managed installations, remove the ~/.local/bin/aesop symlink and ~/.local/share/aesop-agentic/venv after uninstalling any service, adjusting paths if customized. Configuration, archives, browser profiles, and logs are retained; remove those separately only when you no longer need them.