Skip to content

Deployment

Jump to bottom
idapixl edited this page Mar 15, 2026 · 3 revisions

Deployment

cortex-engine can run locally (MCP stdio), or as a hosted service on Cloud Run.

Local (MCP stdio)

The simplest setup. cortex-engine runs as a subprocess of your AI client:

npm install cortex-engine
# Configure via .mcp.json — see [[MCP Integration]]

Pros: No server to manage, works offline (with Ollama for embeddings) Cons: Only accessible from the local machine

Cloud Run (Hosted)

Run cortex as an HTTP service for remote access, multi-agent setups, or shared memory.

Prerequisites

  • Google Cloud project with:
    • Cloud Run enabled
    • Firestore enabled
    • Artifact Registry (for container images)
  • gcloud CLI authenticated

Deploy

The idapixl-cortex wrapper provides the HTTP layer:

git clone https://github.com/idapixl/idapixl-cortex.git
cd idapixl-cortex
npm install && npm run build

Set environment variables:

export GCP_PROJECT_ID="your-project-id"
export CORTEX_API_TOKEN="your-secret-token"  # for auth

Deploy:

gcloud run deploy cortex \
  --source . \
  --region us-central1 \
  --update-env-vars "GCP_PROJECT_ID=$GCP_PROJECT_ID,CORTEX_API_TOKEN=$CORTEX_API_TOKEN"

Warning: Always use --update-env-vars, never --set-env-vars (which replaces all existing vars).

Authentication

All requests require the x-cortex-token header:

curl https://your-service.run.app/api/query \
  -H "x-cortex-token: your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"query": "what do I know?"}'

Self-Hosted (VPS)

Run cortex on any Linux server:

# Clone and build
git clone https://github.com/idapixl/idapixl-cortex.git
cd idapixl-cortex && npm install && npm run build

# Set env vars
cp .env.example .env
# Edit .env with your values

# Run with PM2 or systemd
pm2 start dist/index.js --name cortex

Multi-Agent Topologies

cortex supports several connection patterns:

Topology Description
1:1 One agent, one cortex (default)
1:N One agent, multiple cortex instances (multi-self)
N:1 Multiple agents sharing one cortex (shared memory)
N:N Federated agents with separate cortex instances

Configure in your agent.yaml:

cortex:
  self:
    url: https://my-cortex.run.app
    auth: CORTEX_API_TOKEN
    primary: true
  shared:
    url: https://team-cortex.run.app
    auth: TEAM_CORTEX_TOKEN
    primary: false

Clone this wiki locally