Skip to main content

​
Requirements

Before installing Grip, ensure you have:
  • Python 3.12 or higher
  • uv package manager (recommended) or pip
  • An API key from one of the supported providers:
    • Anthropic (for Claude Agent SDK)
    • OpenAI, DeepSeek, Groq, etc. (for LiteLLM engine)
The uv package manager is strongly recommended for faster installation and dependency resolution. Install it with:
curl -LsSf https://astral.sh/uv/install.sh | sh

​
Installation Methods

​
Optional Extras

Grip supports optional dependencies for additional features: 
# Add Discord bot support
uv sync --extra discord
Extras only work when installing from source. When using PyPI installation, install extras with:
pip install grip-ai[discord,slack,mcp]

​
Package Details

Grip is published to PyPI as grip-ai:
  • Package name: grip-ai
  • Command: grip
  • Version: 1.0.0
  • License: MIT
  • Python support: 3.12+
View the package on PyPI: https://pypi.org/project/grip-ai/

​
Development Installation

If you’re contributing to Grip or want to run tests:
1

Clone and enter directory

git clone https://github.com/5unnykum4r/grip-ai.git
cd grip-ai
2

Install with dev dependencies

uv sync --group dev
This installs additional tools:
  • ruff — Fast Python linter and formatter
  • pytest — Testing framework
  • pytest-asyncio — Async test support
3

Run linter

uv run ruff check grip/ tests/
4

Run tests

uv run pytest
Grip includes 770 tests across 50+ test files covering:
  • Tool execution and validation
  • Memory and session management
  • API endpoints and auth
  • Workflow DAG execution
  • MCP server integration
  • Security guards (trust model, shell deny-list)
5

Run tests with coverage

uv run pytest --cov=grip

​
Docker Installation

Grip is Docker-ready and can be configured entirely via environment variables: 
# Clone repository
git clone https://github.com/5unnykum4r/grip-ai.git
cd grip-ai

# Build Docker image
docker build -t grip .

​
Environment Variable Format

Grip supports GRIP_ prefixed environment variables for any config value. Use double underscores (__) for nested keys:
  • GRIP_AGENTS__DEFAULTS__MODEL → agents.defaults.model
  • GRIP_PROVIDERS__ANTHROPIC__API_KEY → providers.anthropic.api_key
  • GRIP_GATEWAY__PORT → gateway.port
  • GRIP_CHANNELS__TELEGRAM__TOKEN → channels.telegram.token
See the Environment Variables page for a complete reference.

​
Verify Installation

After installation, verify everything is working: 
# Check version and help
grip --help

# Run diagnostics
grip status

# View current configuration
grip config show
Expected output: 
Grip AI v1.0.0
Workspace: /home/user/.grip/workspace
Config: /home/user/.grip/config.json
Engine: claude_sdk

​
Troubleshooting

If grip is not found after installation:Via uv tool install:
# Ensure uv bin directory is in PATH
export PATH="$HOME/.cargo/bin:$PATH"
Via pip:
# Check if pip bin directory is in PATH
python -m pip show grip-ai

# If not in PATH, use:
python -m grip --help
Grip requires Python 3.12+. Check your version:
python --version
If you have an older version, install Python 3.12 using:
  • macOS: brew install [email protected]
  • Ubuntu/Debian: sudo apt install python3.12
  • Arch: sudo pacman -S python
  • Windows: Download from python.org
Install the uv package manager:
curl -LsSf https://astral.sh/uv/install.sh | sh
Alternatively, use pip instead of uv:
pip install grip-ai
If you encounter permission errors:Don’t use sudo with uv or pip — this can cause permission issues.Instead, install in user space:
pip install --user grip-ai
Or use uv tool install (already user-scoped):
uv tool install grip-ai

​
Next Steps

Quickstart

Run the onboarding wizard and chat with your first agent

Configuration

Set up API keys, choose your engine, and configure tools

Architecture

Understand Grip’s dual-engine architecture and component design

Deployment

Deploy Grip to production with Docker

Build docs developers (and LLMs) love

Get started for freeTalk to us