Getting Started

Get Amprealize running locally in under 5 minutes. This guide covers the OSS edition; see Editions for enterprise features.

Prerequisites

Python 3.11+
Git
One of: PostgreSQL 15+, SQLite 3, or Neon cloud account

1. Clone and install

git clone https://github.com/amprealize/amprealize.git
cd amprealize
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

2. Configure a context

Choose your storage backend:

SQLite (simplest)

amprealize context add dev-sqlite --storage sqlite --path ~/.amprealize/data/dev.db
amprealize context use dev-sqlite

Local PostgreSQL

amprealize context add local --storage postgres \
  --host localhost --port 5432 --database amprealize \
  --user postgres --password postgres
amprealize context use local

Neon cloud

amprealize context add neon --storage postgres \
  --dsn "postgresql://user:pass@host/db?sslmode=require"
amprealize context use neon

Verify connectivity:

amprealize context validate
amprealize context list

See Context System for full reference.

3. Set up environment

cp .env.example .env
# Edit .env — set DATABASE_URL if not using context system

Install pre-commit hooks:

./scripts/install_hooks.sh

4. Run database migrations

alembic upgrade head

5. Start the server

uvicorn amprealize.api:app --reload --port 8000

The API is now available at http://localhost:8000/docs.

6. Initialize MCP

amprealize mcp init
amprealize mcp doctor  # Verify MCP health

MCP tools are now available in VS Code Copilot Chat.

7. Try it out

# Create a behavior
amprealize behaviors create --name "behavior_hello_world" \
  --description "Demo behavior"

# List behaviors
amprealize behaviors list

# Run a health check
amprealize compliance validate

Next Steps

Environment Setup — detailed dev environment configuration
Running Tests — run the test suite
Surfaces — explore all 5 access surfaces
MCP Tool Families — browse 64+ MCP tools