Deployment

Deployment

cortex-engine can run locally as an MCP stdio subprocess, as a shared local server over MCP Streamable HTTP (1.8.0+), or as a hosted service on Cloud Run or Railway.

Local (MCP stdio)

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

npm install @fozikio/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

Shared local server (MCP over Streamable HTTP)

One SQLite store may only be opened by one process (docs/concurrency.md), so a main checkout and its worktrees cannot each spawn their own stdio server. Since 1.8.0 they don't have to: run one server and have every client connect to it over MCP.

CORTEX_API_TOKEN=<token> npx fozikio serve --agent <name> --rest --port 3111   # binds 127.0.0.1

Each client's .mcp.json points at http://127.0.0.1:3111/mcp with "type": "http" — see MCP Integration.

Pros: Many sessions, one store; same tool list as stdio Cons: A server to keep running

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

Serve the REST API

cortex-engine ships its own REST server — there is nothing to wrap. The same EngineContext that backs the MCP tools is exposed over HTTP, so tool behaviour is identical across both transports:

npx fozikio serve --rest --port 8080 --host 0.0.0.0

The server refuses to start without CORTEX_API_TOKEN (or an explicit --allow-unauthenticated), and destructive tools — forget, dream, evolve, resolve, thread_resolve — are blocked from the generic REST endpoint; they stay available over MCP for direct agent access.

To embed it in a larger Node service instead, use the exported starter:

// index.ts
import { createContext, startRestServer } from '@fozikio/cortex-engine';

const engine = await createContext(config);
await startRestServer(engine, {
  port: Number(process.env.PORT ?? 8080),
  host: '0.0.0.0',
  token: process.env.CORTEX_API_TOKEN,
});

There is no CortexEngine class, and the package is scoped — @fozikio/cortex-engine, never bare cortex-engine. Earlier revisions of this page showed a hand-rolled Hono wrapper around both; neither has ever existed.

For a container, the published image already does this: ghcr.io/fozikio/cortex-engine:latest reads PORT and HOST and serves on 8080.

Deploy

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)

Same server wrapper as above, just run it directly:

# Build
npm install && npm run build

# Set env vars
export GCP_PROJECT_ID="your-project-id"
export CORTEX_API_TOKEN="your-secret-token"

# 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