# How to Deploy Semantica AGI: Production Docker Setup Guide

> Deploy Semantica AGI quickly with Docker. Follow this guide to set up FalkorDB and Semantica Explorer containers, secure your API with SEMANTICA_API_KEY, and get your AGI running in production.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-13

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.

```bash
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`](https://github.com/semantica-agi/semantica/blob/main/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.

```bash
docker compose up -d

```

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

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

```

### Verify the Installation

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

```bash
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py). The library discovers the API endpoint using the `SEMANTICA_API_KEY` environment variable.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/registry.py). To switch backends, replace the FalkorDB service in [`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.yml) and update the connection URL.

For example, to use Neo4j:

```yaml
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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py) to reload automatically when you modify Python files, and includes a bundled UI for rapid iteration without rebuilding the image.