Installation

Prerequisites

Before installing ContextOS, ensure you have the following:

• Python 3.10+
• PostgreSQL with the pgvector extension installed.
• Docker (optional, but recommended for running the database locally).
• uv (optional, but ContextOS uses it for fast dependency management).

1. Clone the Repository

ContextOS is currently installed from source.

git clone https://github.com/contextos/context-orchestrator.git
cd context-orchestrator

2. Install the Package

Install the library into your environment in editable mode:

pip install -e .

If you use uv, you can run uv pip install -e .

3. Database Setup (Docker)

ContextOS requires a PostgreSQL database with pgvector. A docker-compose.yml file is provided for immediate local development.

docker compose up -d

This starts a Postgres instance on port 5433 by default.

4. Configure Environment

Copy the example environment file:

cp .env.example .env

Ensure your DATABASE_URL points to the running PostgreSQL instance:

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5433/contextos

5. Run Migrations

ContextOS uses Alembic to manage database schemas. Initialize the schema by running:

alembic upgrade head

Next Steps

You're all set! Head over to the Quickstart guide to build your first context payload.