Installation

Requirements

Valcore supports Python 3.11 or newer and is tested natively on Windows as well as Unix systems. The visual workbench is bundled with the Python package, so a separate Node.js installation is not required to use it.

Model-backed generation and runs need a model route: either a Pydantic AI Gateway key, or an already-installed and logged-in claude, codex, or cursor-agent CLI on your PATH. Logfire support is optional and can be added independently.

Homebrew install

Recommended on macOS and available on Linux. The tap provides the valcore command and keeps upgrades simple.

brew install duncankmckinnon/tap/valcore
valcore --help

uv tool install

Use uv on macOS, Linux, or Windows to install Valcore in an isolated environment without adding it to a project's dependencies.

uv tool install valcore
valcore --help

To send Valcore's own traces to Logfire, install the optional integration:

uv tool install 'valcore[logfire]'

Windows

Run the uv commands above in PowerShell, then launch the same bundled workbench:

uv tool install valcore
valcore serve

Valcore stores its workspace at $HOME\.valcore, normally C:\Users\<name>\.valcore. Set VALCORE_HOME if you want it elsewhere. Windows protects the workspace through the current user's filesystem ACLs.

pip install

Install with pip when you manage Python tools in a dedicated virtual environment.

python -m venv .venv
source .venv/bin/activate
pip install valcore
valcore --help

Upgrading

# Homebrew
brew update && brew upgrade valcore

# uv tool
uv tool upgrade valcore

# pip, inside the environment where Valcore is installed
python -m pip install --upgrade valcore

Upgrading the package does not replace the local workspace under ~/.valcore. Valcore applies compatible database migrations when it opens the workspace.

Launch the workbench

valcore serve

This starts Valcore locally and opens the visual workbench. Your workspace is stored locally and shared with the CLI.