Getting Started

Get up and running with Morphik

Installation Options

Morphik Cloud (recommended)

1. Sign Up

   On a new tab, navigate to the Morphik website and click the sign up button on the top right.

2. Create a Project

   Once you have signed up, you will be redirected to the Morphik Cloud dashboard. Click the “Create Application” button to create a new application. Enter your app name and click “Create Application”. You should now see that application in your dashboard.

3. Obtain your URI

   Click on the “Copy” icon on the top right of the application card to copy your application URI.

That’s it! You’re ready to use Morphik now :)

1. Sign Up

   On a new tab, navigate to the Morphik website and click the sign up button on the top right.

2. Create a Project

   Once you have signed up, you will be redirected to the Morphik Cloud dashboard. Click the “Create Application” button to create a new application. Enter your app name and click “Create Application”. You should now see that application in your dashboard.

3. Obtain your URI

   Click on the “Copy” icon on the top right of the application card to copy your application URI.

That’s it! You’re ready to use Morphik now :)

Direct Installation

1. Prerequisites

   Python

   Please ensure that you have Python 3.12 installed on your machine. Guides for installing Python can be found on the Python website.

   PostgreSQL

   Morphik requires PostgreSQL with the pgvector extension for vector storage and similarity search capabilities. Follow the installation instructions for your operating system:

   macOS

   On macOS, you can use Homebrew to install PostgreSQL and pgvector:

   brew install postgresql@14
   brew install pgvector
   

   Start the PostgreSQL service:

   brew services start postgresql@14
   

   Create a database and user for Morphik:

   createdb morphik
   createuser -s postgres
   

   These commands create a database named “morphik” and a superuser named “postgres” that the application will use to connect.

   On macOS, you can use Homebrew to install PostgreSQL and pgvector:

   brew install postgresql@14
   brew install pgvector
   

   Start the PostgreSQL service:

   brew services start postgresql@14
   

   Create a database and user for Morphik:

   createdb morphik
   createuser -s postgres
   

   These commands create a database named “morphik” and a superuser named “postgres” that the application will use to connect.

   Install PostgreSQL from the official repositories.We recommend version 14 . Other versions may work, but haven’t been extensively tested!

   sudo apt update
   sudo apt install postgresql postgresql-contrib
   

   Install pgvector:

   sudo apt install postgresql-14-pgvector
   

   Start and enable the PostgreSQL service:

   sudo systemctl start postgresql
   sudo systemctl enable postgresql
   

   Create a database and user for Morphik:

   sudo -u postgres createdb morphik
   sudo -u postgres createuser -s postgres
   

   1. Download and install PostgreSQL from the official website.
   2. During installation, make note of the password you set for the postgres user.
   3. Install pgvector:
      • Open pgAdmin (installed with PostgreSQL)
      • Connect to your PostgreSQL server
      • Right-click on “Extensions” and select “Create > Extension”
      • Select “pgvector” from the dropdown and click “Save”
   4. Create a database for Morphik:
      • Right-click on “Databases” and select “Create > Database”
      • Name it “morphik” and click “Save”

   After installation, verify that PostgreSQL is running correctly:

   psql -U postgres -c "SELECT version();"
   

   You should see the following output:

    version                                                            
   ------------------------------------------------------------------------------------------------------------------------------
   <Your postgres version and some compilation details>
   

   Additional Dependencies

   Some system-level dependencies might be required for processing various document types:

   macOS

   # Install via Homebrew
   brew install poppler tesseract libmagic
   

   # Install via Homebrew
   brew install poppler tesseract libmagic
   

   # Install via apt
   sudo apt-get update
   sudo apt-get install -y poppler-utils tesseract-ocr libmagic-dev
   

   For Windows, you may need to install these dependencies manually:

   1. Poppler: Download from poppler for Windows
   2. Tesseract: Download the installer from UB Mannheim
   3. libmagic: This is included in the python-magic-bin package which will be installed with pip

   If you encounter database initialization issues within Docker, you may need to manually initialize the schema:

   psql -U postgres -d morphik -a -f init.sql
   

   Docker (required for background services)

   Docker is used to spin up auxiliary services automatically (e.g., a local Redis container for Morphik’s task queue). Install Docker Desktop (macOS/Windows) or the Docker engine (Linux) and make sure the daemon is running.

   Optional: Running Local Models with Ollama

   macOS

   If you want to run models locally instead of using cloud providers, first install Ollama using Homebrew:

   brew install ollama
   

   Start Ollama:

   ollama serve
   

   Pull a model to use with Morphik (in a new terminal):

   ollama pull llama3.2
   

   If you want to run models locally instead of using cloud providers, first install Ollama using Homebrew:

   brew install ollama
   

   Start Ollama:

   ollama serve
   

   Pull a model to use with Morphik (in a new terminal):

   ollama pull llama3.2
   

   Install Ollama using the official installation script:

   curl -fsSL https://ollama.com/install.sh | sh
   

   Start Ollama:

   ollama serve
   

   Pull a model to use with Morphik (in a new terminal):

   ollama pull llama3.2
   

   1. Download the Ollama installer from the official website.

   2. Run the installer and follow the on-screen instructions.

   3. After installation, Ollama will start automatically.

   4. Open Command Prompt or PowerShell and pull a model:

      ollama pull llama3.2
      

2. Cloning the Repository

   To get started with Morphik, we need to first setup the server. This involves cloning the repository, installing the dependencies, and the running the server. You are just a few steps away from accurate, agentic RAG over your multi-modal data!

   First, let’s clone the repository from GitHub.

   git clone https://github.com/morphik-org/morphik-core.git
   

   After cloning the repository, you will notice a morphik-core folder in your current directory.

   ls morphik-core
   

   If you see an error like ls: morphik-core: No such file or directory, it means that the repository is not cloned properly. Please try again.

   Once you have cloned the repository, navigate into the morphik-core folder.

   cd morphik-core
   

3. Setting Up the Environment

   Installing Python Dependencies

   While it is not required, we highly recommend using a virtual environment to ensure dependencies from other projects do not conflict with Morphik. You may use managers like uv or poetry, but for this guide, we will use the built-in venv module.

   Morphik currently supports Python 3.12 as the latest version. We recommend using Python 3.12 for optimal compatibility.

   You don’t need to create a virtual-env or run uv sync yourself—the installer script will handle everything, including installing uv if it’s missing. If you prefer a manual setup at some point, install uv globally (pip install --upgrade uv) and run uv sync to recreate the environment, but this is entirely optional.

   uv reads the pyproject.toml / uv.lock files, so all dependencies (including optional ones like unstructured) are declared in one place.

   If you need additional NLTK data you can still download it afterwards:

   python -m nltk.downloader averaged_perceptron_tagger punkt
   

   ---

4. Run the Installer Script

   From the project root, run the one-liner below – it auto-detects your platform (macOS or Linux), sets any required build flags, installs dependencies, and starts the server:

   # Make the script executable
   chmod +x install_and_start.sh
   
   # Run the installer
   ./install_and_start.sh
   

   The script will:

   1. Create & activate a .venv with uv
   2. Install colpali-engine (knowledge-graph generation)
   3. Build llama-cpp-python (Metal acceleration on Apple Silicon)
   4. Launch the server via uv run start_server.py

   You only need to run ./install_and_start.sh the first time to set up the environment. For future sessions, activate your project directory and simply start the server with:

   uv run start_server.py
   

5. Setting up the Server Parameters

   At this point, you may want to customize the server - such as use a different model, enable or disable certain features, etc. - you can do so by editing the morphik.toml file.

   Morphik now uses a registered models approach, which allows you to define hundreds of different models in one place and reference them throughout your configuration. This makes it easy to mix and match models based on your needs (e.g., smaller models for simpler tasks). You can find more details about configuration here.

   The installer copies .env.example to .env automatically if it’s missing. After the script finishes, open .env to add any API keys (e.g. OPENAI_API_KEY) or secrets you need. You can tweak morphik.toml anytime to switch completion/embedding models, adjust chunking, or enable advanced features.

6. Launching the Server

   You are now ready to launch the Morphik server! Just run the following command to start the server.

   uv run start_server.py
   

   You should see the following output:

   INFO:     Started server process [15169]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://localhost:8000 (Press CTRL+C to quit)
   

   This means that the server is running on http://localhost:8000. You can now interact with the server using the API or the Python SDK.

Using Docker

Morphik provides a streamlined Docker-based setup that includes all necessary components: the core API, PostgreSQL with pgvector, and Ollama for AI models.

Prerequisites

• Docker and Docker Compose installed on your system
• At least 10GB of free disk space (for models and data)
• 8GB+ RAM recommended

Quick Start

1. Clone the repository and navigate to the project directory:

git clone https://github.com/morphik-org/morphik-core.git
cd morphik-core

2. Before first-time setup, check the configuration:

Ensure your morphik.toml file has the correct settings for running in Docker:

# For Redis configuration when using Docker
[redis]
host = "redis"  # use "redis" when running in Docker (not "localhost")
port = 6379

(If using local models with Ollama) Also ensure the Ollama configuration matches your deployment setup by modifying the api_base in your morphik.toml:

# Modify the api_base based on your deployment:
# - Local Ollama: "http://localhost:11434" (default)
# - Morphik in Docker, Ollama local: "http://host.docker.internal:11434"  
# - Both in Docker: "http://ollama:11434"

[registered_models]
ollama_qwen_vision = { model_name = "ollama_chat/qwen2.5vl:latest", api_base = "http://localhost:11434", vision = true }
ollama_llama_vision = { model_name = "ollama_chat/llama3.2-vision", api_base = "http://localhost:11434", vision = true }
ollama_embedding = { model_name = "ollama/nomic-embed-text", api_base = "http://localhost:11434" }

For example, if running both Morphik and Ollama in Docker, change all api_base values to "http://ollama:11434".

If you want to use Ollama for AI capabilities:

docker compose --profile ollama up --build -d

This will build docker with an Ollama container.

Or if you’re using OpenAI, Anthropic, or other models (configure the API key in .env):

docker compose up --build

This will build docker without the Ollama container.

These commands will:

• Build all required containers
• Download necessary AI models (nomic-embed-text and qwen2.5vl if using Ollama)
• Initialize the PostgreSQL database with pgvector
• Start all services

The initial setup may take 5-10 minutes depending on your internet speed, as it needs to download the AI models.

Note: When using Ollama, ensure your system has sufficient memory. The qwen2.5vl model requires at least 4GB of available RAM. If you encounter memory issues, you can increase Docker’s memory allocation in Docker Desktop settings (Resources > Advanced > Memory), modify the morphik.toml file to use a smaller model, or switch to using OpenAI API.

docker compose up    # Start all services
docker compose down  # Stop all services

1. To completely reset (will delete all data and models):

docker compose down -v

Configuration

The default configuration works out of the box and includes:

• PostgreSQL with pgvector for document storage
• Ollama for AI models (embeddings and completions)
• Local file storage
• Basic authentication

You can customize your setup by creating a .env file:

JWT_SECRET_KEY=your-secure-key-here  # Important: Change in production
OPENAI_API_KEY=sk-...                # Only if using OpenAI
HOST=0.0.0.0                         # Leave as is for Docker
PORT=8000                            # Change if needed

Accessing Services

• Morphik API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Troubleshooting

1. Service Won’t Start

   # View all logs
   docker compose logs
   
   # View specific service logs
   docker compose logs morphik
   docker compose logs postgres
   docker compose logs ollama
   

2. Database Issues

   • Check PostgreSQL is healthy: docker compose ps
   • Verify database connection: docker compose exec postgres psql -U morphik -d morphik

3. Model Download Issues

   • Check Ollama logs: docker compose logs ollama
   • Ensure enough disk space for models
   • Try restarting Ollama: docker compose restart ollama
   • Verify that your Redis and Ollama configuration in morphik.toml matches your deployment:
     • For Redis in Docker, use host = "redis" (not “localhost”)
     • If running Ollama in Docker, use http://ollama:11434 endpoint
     • If running Ollama locally but Morphik in Docker, use http://host.docker.internal:11434

4. Ollama Memory Issues

   • If you see errors like “model requires more system memory than is available” in the logs:

     • Increase Docker memory allocation in Docker Desktop:
       1. Open Docker Desktop application
       2. Click on Settings (gear icon)
       3. Go to “Resources” section
       4. Increase memory allocation to at least 6GB (8GB recommended)
       5. Click “Apply & Restart”
     • Alternatively, modify morphik.toml to use a smaller model
     • Or switch to OpenAI API by uncommenting the OpenAI sections in morphik.toml

   • For knowledge graph creation specifically, you can switch from Ollama to OpenAI:

     # Change this section in morphik.toml
     [graph]
     provider = "openai"
     model_name = "gpt-4o-mini"
     enable_entity_resolution = true
     

5. Performance Issues

   • Monitor resources: docker stats
   • Ensure sufficient RAM (8GB+ recommended)
   • Check disk space: df -h

Using Morphik

You can use Morphik via our Python SDK, our Rest API, via Morphik Console, or via MCP.

Python SDK

1. Create a virtual environment

   python3.12 -m venv .venv
   

2. Activate the virtual environment

   source .venv/bin/activate
   

3. Install the SDK

   pip install morphik
   

4. Ingest and Query your first file

   from morphik import Morphik
   
   # Initialize the Morphik client
   morphik = Morphik(uri="your-morphik-uri")
   # Ingest a file
   doc = morphik.ingest_file(file_path="super/complex/file.pdf")
   doc.wait_for_completion()
   
   # Query the file
   response = morphik.query(query="What percentage of Morphik users are building something cool?")
   print(response) # Responds with 100% :)
   

You can find our entire SDK documentation here.

1. Create a virtual environment

   python3.12 -m venv .venv
   

2. Activate the virtual environment

   source .venv/bin/activate
   

3. Install the SDK

   pip install morphik
   

4. Ingest and Query your first file

   from morphik import Morphik
   
   # Initialize the Morphik client
   morphik = Morphik(uri="your-morphik-uri")
   # Ingest a file
   doc = morphik.ingest_file(file_path="super/complex/file.pdf")
   doc.wait_for_completion()
   
   # Query the file
   response = morphik.query(query="What percentage of Morphik users are building something cool?")
   print(response) # Responds with 100% :)
   

You can find our entire SDK documentation here.

1. Extract your bearer token

   The bearer token can be extracted directly from your Morphik URI. The URI has the following format:

   morphik://<app_name>:<bearer_token>@<host>

   The middle part between the colon and the @ symbol is your bearer token.

2. Make API requests

   When making requests to the Morphik API, include your bearer token in the Authorization header:

     curl -X 'POST' 'https://api.morphik.ai/documents?skip=0&limit=10000' \
     -H "Authorization: Bearer <your_bearer_token>"
     -H 'accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '{}'
   

   You can find our complete API reference here.

1. Open Morphik Console for your App

   Click on the card with your app name on it. This should open the Morphik Console for your app.

2. Ingest a file

   To ingest a file, click the “Upload Document” button and select the file you want to ingest. You can choose to batch ingest files or also ingest text if you prefer. Once ingested, you can see the status of your document ingestion in the console. (If you didn’t not put in a folder, you’ll find it in the “All Documents” section.)

3. Using Morphk Agent

   Once your documents are ingested, you can navigate to the “Agent” tab in the sidebar, and start asking questions about your documents! The agent will show you the tool calls that it makes, alongside the results and a final response. You can use for long-lived tasks, or for more complex queries that require multiple steps to complete.

You can find more information about MCP here.

Community Support

We have an open community with lots of discussion where you can get help, report bugs, and share your experiences with Morphik. If you need assistance or want to contribute, please join our community!

Join our Discord

Get help, report bugs, and connect with other Morphik users.

Next Steps

Now that you have the server running, you can explore the different ways to interact with the server.

Configure Morphik

Configure Morphik using the morphik.toml file.

API

Use the API to interact with the server.

Python SDK

Use the Python SDK to interact with the server.

Morphik UI and CLI

Use the Morphik UI or CLI to interact with the server.