How to Deploy Semantica AGI: Production Docker Setup Guide

Deploy Semantica AGI by running two Docker containers—FalkorDB for graph storage and the Semantica Explorer for the HTTP API—using the provided docker-compose.yml file, then configure the SEMANTICA_API_KEY environment variable to secure the endpoints.

Semantica AGI is an open-source, modular Python framework for contextual decision intelligence that runs on top of a polyglot graph store. According to the semantica-agi/semantica source code, production deployments rely on a containerized architecture separating the FalkorDB database from the FastAPI-based MCP server. This guide walks through the exact steps to deploy the stack, verify connectivity, and integrate client applications.

Architecture Overview

The deployment consists of two primary services defined in docker-compose.yml:

• FalkorDB: A native Labeled-Property-Graph (LPG) database that stores the Context Graph, decisions, provenance, and temporal facts. It exposes port 6379 internally.
• Semantica Explorer: The HTTP API and interactive UI (the "MCP server") that exposes ingestion, knowledge graph construction, reasoning, and vector-store retrieval endpoints. It maps host port 8000 to the container.

Docker Compose creates a private bridge network (semantica) allowing the Explorer to reach FalkorDB on falkordb:6379 via the FALKORDB_HOST and FALKORDB_PORT variables.

Step-by-Step Production Deployment

Clone the Repository

Start by pulling the latest source code to access the Docker configuration files.

git clone https://github.com/semantica-agi/semantica.git
cd semantica

Configure Environment Variables

The Explorer reads three critical environment variables defined at lines 7-15 of docker-compose.yml:

Variable	Purpose	Production Value
SEMANTICA_API_KEY	Secret token required for all protected endpoints. Generate with openssl rand -hex 32.	Secure random string
SEMANTICA_ALLOW_ANONYMOUS	When true, API key checks are bypassed.	false
ALLOWED_ORIGINS	CORS whitelist for the UI. Defaults to http://localhost:8000.	Your domain

Export these locally or place them in a .env file in the repository root; Docker Compose picks up the file automatically.

Launch the Stack

Run the production configuration with detached mode. The Dockerfile at the repository root builds the Explorer image automatically on first launch.

docker compose up -d

For development with hot-reload and source-code volume mounts, use the alternative configuration:

docker compose -f docker-compose.dev.yml up -d

Verify the Installation

Run the built-in health check to ensure all components are reachable:

semantica doctor

The command executes a self-test of the Python package and should end with "pass" for all components. Once verified, the API is available at http://localhost:8000 and the interactive UI loads at the same address.

Connecting with the Python Client

With the containers running, client code connects via the ContextGraph facade implemented in semantica/context.py. The library discovers the API endpoint using the SEMANTICA_API_KEY environment variable.

import os
from semantica.context import ContextGraph

os.environ["SEMANTICA_API_KEY"] = "my-secret"

graph = ContextGraph(advanced_analytics=True)

decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature tooling, and team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

chain = graph.trace_decision_chain(decision_id)
print("Causal chain:", chain)

Swapping the Graph Backend

Semantica supports multiple RDF and LPG stores (Blazegraph, Jena, Neo4j) through the unified graph store registry located at semantica/graph_store/registry.py. To switch backends, replace the FalkorDB service in docker-compose.yml and update the connection URL.

For example, to use Neo4j:

services:
  neo4j:
    image: neo4j:5
    ports:
      - "7687:7687"
    environment:
      NEO4J_AUTH: neo4j/secret
  
  explorer:
    environment:
      NEO4J_URI: bolt://neo4j:7687

No Python code changes are required because all data access routes through the registry abstraction.

Summary

• Deploy Semantica AGI using two containers defined in docker-compose.yml: FalkorDB for storage and the Explorer for the API.
• Secure the deployment by setting SEMANTICA_API_KEY and disabling SEMANTICA_ALLOW_ANONYMOUS in production.
• Verify connectivity using the semantica doctor command before running client code.
• Use docker-compose.dev.yml for local development with hot-reload capabilities.
• Swap graph databases by modifying the Docker Compose services and connection strings without changing application logic.

Frequently Asked Questions

What are the minimum system requirements for deploying Semantica AGI?

The stack requires Docker Engine 20.10+ and Docker Compose 2.0+. FalkorDB performs best with at least 4GB of RAM allocated to the container for moderate-sized knowledge graphs, while the Explorer service requires minimal resources (512MB RAM) as it delegates heavy computation to the graph store.

How do I secure the Semantica AGI API in production?

Set SEMANTICA_ALLOW_ANONYMOUS to false and generate a cryptographically secure SEMANTICA_API_KEY using openssl rand -hex 32. Expose the Explorer container only through a reverse proxy with TLS termination, and restrict ALLOWED_ORIGINS to your specific domain to prevent CORS attacks.

Can I use a different graph database instead of FalkorDB?

Yes. The architecture abstracts storage through semantica/graph_store/registry.py, allowing you to substitute FalkorDB with Neo4j, Amazon Neptune, or other LPG stores. Update the Docker Compose file to reference the new database image and provide the appropriate connection URI to the Explorer service.

How do I enable hot-reload for local development?

Run docker compose -f docker-compose.dev.yml up -d instead of the default command. This mounts the local source code into the container, allowing the FastAPI server in semantica/mcp/server.py to reload automatically when you modify Python files, and includes a bundled UI for rapid iteration without rebuilding the image.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}