Skip to content

Installation

Cayu requires Python 3.11 or newer. Use a virtual environment for each application. The examples below use uv; ordinary Python virtual environments and pip work too.

Generate a project with uv

Section titled “Generate a project with uv”

Run this from the directory that should contain your application:

Terminal window
uvx cayu new myagent
cd myagent
uv sync --extra dev
uv run --no-sync cayu --version

The final command reports the installed Cayu version; the release manifest names the release these docs describe. The generator declares the application factory and supplies test and eval seams. The project’s dev extra includes the local developer control plane.

Install with pip

Section titled “Install with pip”
Terminal window
python -m venv .venv
source .venv/bin/activate
python -m pip install cayu
cayu new myagent
cd myagent
python -m pip install -e '.[dev]'
cayu --version

On Windows, activate the environment with .venv\Scripts\Activate.ps1 in PowerShell. Keep every command in the same environment; a global cayu command can otherwise select a different release.

Optional integrations

Section titled “Optional integrations”

Install the extras used by your application. The base package provides the core runtime and provider-neutral contracts.

Extra Capability
cayu[server] HTTP control plane and packaged dashboard
cayu[server-settings] Server plus typed environment and dotenv configuration
cayu[postgres] PostgreSQL stores
cayu[oidc] OIDC bearer authentication for operators
cayu[aws] AWS integrations including Bedrock and Lambda MicroVM
cayu[vertex] Anthropic models through Google Cloud Vertex AI
cayu[e2b] E2B runner and workspace
cayu[browser] Browser integrations
cayu[files] Image and PDF tooling
cayu[console] Interactive Python console
cayu[egress] Credential and network egress integrations

For example, python -m pip install 'cayu[server,postgres]' installs the latest release with both integrations. Declare dependencies in the generated project’s configuration and lock them with uv sync for reproducible deployments.

Credentials and the first checks

Section titled “Credentials and the first checks”

Project generation, deterministic tests and the starter eval need no model credentials. A live run does. Configure the provider through the generated settings and provider guide; keep credential values in environment or secret configuration.

Continue with the quickstart.