Skip to content

Installation

Requirements

Requirement Version Purpose
Python 3.12+ Runtime
Docker 24+ Sandbox execution, local infrastructure
Dapr CLI 1.14+ Agent sidecar

Install Grampus

pip install grampus-ai

uv add grampus-ai

uv init my-agent
cd my-agent
uv add grampus-ai

Optional extras

# Anthropic Claude support
pip install "grampus-ai[anthropic]"

# OpenAI GPT support
pip install "grampus-ai[openai]"

# Both providers
pip install "grampus-ai[all]"

Verify the install

grampus --version
# grampus 0.1.0

Install the Dapr CLI

Dapr provides the infrastructure runtime (state, pub/sub, workflows). Grampus requires the Dapr sidecar to be running alongside your agent.

brew install dapr/tap/dapr-cli

wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash

powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"

Initialize Dapr (installs the runtime components locally):

dapr init

Verify:

dapr --version
# CLI version: 1.14.x
# Runtime version: 1.14.x

Start local infrastructure

Grampus requires PostgreSQL (with pgvector) and Redis. Use the provided docker-compose.yml:

# From your project directory (generated by grampus init)
docker compose up -d

# Verify all services are healthy
docker compose ps

Expected output:

NAME                STATUS
grampus-postgres      Up (healthy)
grampus-redis         Up (healthy)
grampus-placement     Up

Environment variables

Set your LLM provider API key:

# Anthropic
export GRAMPUS_MODEL__ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export GRAMPUS_MODEL__OPENAI_API_KEY="sk-..."

Using a .env file

Grampus reads .env files automatically. Create .env in your project root and add your keys there — they will not be committed to git if .env is in .gitignore.

Next steps