Quick Start Guide

Get Qinematos running in 5 minutes. This guide walks you through setup, running the server, and making your first API calls.

Prerequisites

Java 25 (with Foreign Function & Memory API support)
Maven 3.9+
Python 3.11+ (optional, for agent examples)
Docker (optional, for containerized deployment)

Verify Java Version

Terminal

java -version
# Should show: openjdk version "25" or higher

Step 1: Clone and Build

Terminal

# Clone the repository
git clone https://github.com/qinematos.git
cd qinematos/qinematos-java25-quarkus

# Build the project (skip tests for faster build)
mvn clean package -DskipTests

Step 2: Run the Server

Development Mode (Hot Reload)

Terminal

mvn quarkus:dev

The server starts with:

REST API on http://localhost:8080
gRPC Service on localhost:9000
MCP Server on http://localhost:8080/mcp

Production Mode

Terminal

java -jar target/quarkus-app/quarkus-run.jar

Step 3: Verify Installation

Health Check

Terminal

curl http://localhost:8080/api/v1/health

Expected response:

Response

{
  "status": "UP",
  "checks": [
    {"name": "IPC Engine", "status": "UP"},
    {"name": "Topic Manager", "status": "UP"},
    {"name": "Xodus Store", "status": "UP"}
  ]
}

System Status

Terminal

curl http://localhost:8080/demo/status

Step 4: Create Your First Topic

Terminal

curl -X POST http://localhost:8080/api/v1/topics \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo.context",
    "description": "My first context topic",
    "schemaType": "generic.keyvalue"
  }'

Step 5: Publish Data

Terminal

curl -X POST http://localhost:8080/api/v1/topics/demo.context/publish \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"key": "user_preference", "value": "dark_mode"},
      {"key": "language", "value": "en-US"}
    ]
  }'

Response includes the IPC handle and lineage ID:

Response

{
  "success": true,
  "version": 1,
  "ipcHandle": {
    "handleId": "demo.context_1_abc123",
    "filePath": "/dev/shm/qinematos/contexts/demo.context/1.arrow",
    "payloadSize": 256
  },
  "lineageId": "lin_abc123-def456"
}

Step 6: Try the Zero-Copy Demo

See zero-copy IPC in action:

Terminal

curl -X POST "http://localhost:8080/demo/zero-copy?records=1000"

This demonstrates:

Arrow serialization of 1000 records
Memory-mapped file creation
IPC handle generation
Lineage tracking

Step 7: Read Data from Python (Zero-Copy)

Install PyArrow:

Terminal

pip install pyarrow

Read context data with true zero-copy:

Python

import pyarrow as pa

# Use the file path from the IPC handle
ipc_file = "/dev/shm/qinematos/contexts/demo.context/1.arrow"

# Memory-map the file (zero-copy!)
source = pa.memory_map(ipc_file, 'r')

# Skip the 32-byte Qinematos header
source.seek(32)

# Read the Arrow table
reader = pa.ipc.open_stream(source)
table = reader.read_all()

# Print the data
print(f"Read {table.num_rows} rows")
print(table.to_pandas())

Available Schema Types

Qinematos provides pre-defined Arrow schemas:

Schema Type	Fields	Use Case
`generic.keyvalue`	key, value, metadata, timestamp	General purpose context
`agent.context`	agent_id, context_type, payload, created_at	Agent state and context
`lineage.trace`	trace_id, parent_id, operation, timestamp	Audit and lineage tracking
`finance.market_data`	symbol, price, volume, timestamp	Financial market data

Configuration

Key settings in src/main/resources/application.properties:

application.properties

# Server ports
quarkus.http.port=8080
quarkus.grpc.server.port=9000

# IPC Configuration
qinematos.ipc.base-path=/dev/shm/qinematos  # Linux
# qinematos.ipc.base-path=${java.io.tmpdir}/qinematos  # Windows
qinematos.ipc.max-segment-size=1073741824  # 1GB

# Persistence
qinematos.xodus.data-dir=./data/xodus

# Enable lineage tracking
qinematos.ipc.enable-lineage=true

Next Steps

Architecture

Understand the three-layer architecture and core components.

API Reference

Complete REST, gRPC, and MCP API documentation.

Troubleshooting

Java Version Error

If you see "Unsupported class file major version", ensure you're using Java 25:

Terminal

export JAVA_HOME=/path/to/java25
mvn clean package -DskipTests

IPC Path on Windows

Windows doesn't have /dev/shm. Qinematos automatically uses the temp directory, but you can configure it explicitly:

application.properties

qinematos.ipc.base-path=${java.io.tmpdir}/qinematos

Port Already in Use

If port 8080 or 9000 is occupied:

application.properties

quarkus.http.port=8081
quarkus.grpc.server.port=9001