Getting started with Cortex

Ce contenu n’est pas encore disponible dans votre langue.

This guide walks you through cloning the repository, configuring environment variables, starting all services and verifying the installation. No cloud account is needed.

To understand the terms used (atom, HYOS, bloc, etc.), see 03-concepts.

Prerequisites

Docker and Docker Compose (v2) installed on your machine
At least 4 CPU cores and 8 GB RAM available for the containers
A few GB of disk space (SurrealDB, PostgreSQL, MeiliSearch, MinIO, Ollama model weights)
Optionally, an API key from a GenAI provider (Google Gemini, OpenAI or Anthropic) if you plan to use provider features

Step 1 — Clone and configure

git clone https://github.com/arka-labs/arka-cortex.git
cd arka-cortex
cp .env.example .env

Open .env and set the required secrets. At minimum you need:

Variable	Purpose	Example
`SURREAL_USER`	SurrealDB root user	`root`
`SURREAL_PASS`	SurrealDB root password	a strong random password
`PG_PASSWORD`	PostgreSQL password	a strong random password
`MEILI_MASTER_KEY`	MeiliSearch master key	a random 32-character string
`S3_ACCESS_KEY`	MinIO access key	`minioadmin`
`S3_SECRET_KEY`	MinIO secret key	a strong random password
`ENCRYPTION_KEY`	AES-256-GCM key for provider credentials (base64, 32 bytes)	generate with `openssl rand -base64 32`

All other variables have sensible defaults. Ports, database names and model names can be adjusted but the defaults work out of the box.

Step 2 — Start the stack

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

Docker Compose brings up the following services:

Service	Port	Role
`surrealdb`	8000	Graph + relational database
`postgres`	5432	Audit trail, documents, auth tables
`meilisearch`	7700	Full-text search
`minio`	9000 / 9001	S3-compatible object storage
`ollama`	11434	Local embeddings (bge-m3) and optional LLM
`cortex_api`	9096	REST API
`cortex_mcp`	3001	MCP server
`cortex_ui`	8080	Web UI

Wait for all health checks to pass. You can monitor with:

docker compose -f docker-compose.example.yml logs -f cortex_api

Step 3 — Open the UI

Navigate to http://localhost:8080 in your browser.

The React interface shows the Cortex dashboard. From here you can:

Browse the atom catalogue (skills, expertises, methods, tools, scopes)
View and manage HYOS profiles
Navigate the taxonomy graph
Manage workspace projects
Consult memory entries

Step 4 — Verify the REST API

curl http://localhost:9096/health

Expected response:

{"ok": true}

If you set a CORTEX_API_KEY in your .env, include it in requests:

curl -H "X-API-Key: YOUR_KEY" http://localhost:9096/api/atoms

Step 5 — Connect an LLM client (optional)

If you use Claude, ChatGPT or Cursor, point them at the MCP server:

http://localhost:3001

The MCP server supports OAuth 2.0 for production clients and API key authentication for local development. See 06-rest-and-mcp for details.

Step 6 — Configure a provider (optional)

If you want Cortex to store and manage GenAI provider credentials:

Open the UI and go to My Account > Providers
Select a provider (Google Gemini, OpenAI or Anthropic)
Paste your API key
Choose default, fast and quality models
Test the connection

Keys are encrypted at rest with AES-256-GCM. They are never returned to the UI in cleartext. See 05-providers for details.

Stopping and restarting

# Stop all services (data persists in Docker volumes)
docker compose -f docker-compose.example.yml down

# Restart
docker compose -f docker-compose.example.yml up -d

All data is stored in named Docker volumes (surreal_data, pg_data, meili_data, minio_data, ollama_data). Stopping and restarting does not lose data.

What stays on your infrastructure

Data	Storage
Catalogue (atoms, blocs, profiles)	SurrealDB volume
Memory entries (decisions, patterns, errors)	SurrealDB volume
Documents and library	PostgreSQL + MinIO
Full-text index	MeiliSearch volume
Embedding model weights	Ollama volume
Provider credentials (encrypted)	PostgreSQL

Cortex sends no telemetry, no analytics and no machine identifier to any external service.

What next?

Understand the vocabulary: 03-concepts
Explore use cases: 04-use-cases
Harden for production: 08-deployment