Documentation

Quick Start

Get Cortex+Forge running in three steps. The platform deploys entirely into your GCP or AWS account — we never see your data.

Sign up at the portal

Create your account at cortex.aicloud.so/signup. The 4-step wizard collects your org name, cloud choice, and region. No credit card required for the trial.

During signup you choose your org slug (e.g. acme). A license key (lk_…) is auto-generated when you complete step 4. Both are pre-filled in your bootstrap command.

Copy your bootstrap command from the dashboard

After signup, go to cortex.aicloud.so/dashboard. Your Deployment Kit card shows a ready-to-run command with your real license key and org slug already filled in. The only value you replace is your cloud project ID:

Your license key and org slug are pre-filled automatically — copy the command from /dashboard, then replace <YOUR_GCP_PROJECT> with your project ID.

GCP — example (values are pre-filled in your dashboard)

curl -sSL https://cortex.aicloud.so/install/gcp.sh \
  | bash -s -- \
      --license-key lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
      --org-slug    acme \
      --project-id  <YOUR_GCP_PROJECT> \
      --region      us-central1 \
      --runtime     firecracker

AWS — example (values are pre-filled in your dashboard)

curl -sSL https://cortex.aicloud.so/install/aws.sh \
  | bash -s -- \
      --license-key lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
      --org-slug    acme \
      --account-id  <YOUR_AWS_ACCOUNT> \
      --aws-region  us-east-1 \
      --runtime     firecracker

License key

Auto-generated at signup step 4. Shown at /dashboard → Deployment Kit.

Org slug

You chose this in signup step 2 (e.g. acme). Pre-filled in the command.

GCP project ID

Your own GCP project. Find it at console.cloud.google.com or run gcloud config get-value project.

AWS account ID

12-digit account number. Find it at console.aws.amazon.com or run aws sts get-caller-identity.

Install forge-connect on each dev machine

Once the cloud deployment is running, team members install the CLI to create and manage agent workspaces.

macOS / Linux

curl -fsSL https://cortex.aicloud.so/install-cli.sh | bash
forge-connect login --instance https://cortex.aicloud.so

Installation

Where to find your license key & org slug

Both values are generated during the signup wizard and always visible in your dashboard. You never need to manually copy them into the install command — they are pre-filled.

Value	Where it comes from	Where to find it
License key `lk_…`	Auto-generated at signup step 4 (Billing)	/dashboard → Deployment Kit card · /signup/done
Org slug	You chose it at signup step 2 (Organization)	/dashboard → Deployment Kit card · /signup/org
GCP Project ID	Your existing GCP project	GCP Console or `gcloud config get-value project`
AWS Account ID	Your existing AWS account	AWS Console or `aws sts get-caller-identity --query Account`

forge-connect CLI (developer laptops)

Install the forge-connect CLI to create and manage isolated agent workspaces (beams) from your terminal.

macOS & Linux

curl -fsSL https://cortex.aicloud.so/install-cli.sh | bash

This places forge-connect in ~/.local/bin. Add it to your PATH if not already:

export PATH="$HOME/.local/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc

Full macOS installer (local forge stack)

For developers who want a local forge stack alongside Docker and Ollama for offline use:

macOS only

bash <(curl -fsSL https://raw.githubusercontent.com/lm-space/cortex/main/forge/install-mac.sh)

This installs Homebrew, gcloud CLI, Docker Desktop (optional), Ollama (optional), and the local forge docker-compose stack.

Prerequisites

Tool	Version	Required for
`curl`	any	Install scripts
`gcloud`	≥ 400	GCP cloud install
`aws`	≥ 2.x	AWS cloud install
Docker Desktop	≥ 24	Local forge stack
Node.js	≥ 20	DB migration runner

Post-install forge-connect setup

First-time authentication

forge-connect login --instance https://cortex.aicloud.so
# Opens browser for OAuth or prompts for email+password
# Token stored at ~/.forge/config

Platform URLs & Endpoints

Public endpoints

Service	URL	Purpose
Cortex portal	`https://cortex.aicloud.so`	Main web app — login, KB, workflows
Health API	`https://cortex.aicloud.so/api/v1/status`	Service health check (DB + Redis)
Prometheus metrics	`https://cortex.aicloud.so/api/metrics`	Scrape target for monitoring
forge-control API	`http://34.31.55.70:3112`	Beam orchestration (HMAC-authenticated)

Internal VPC addresses (forge mesh)

VM	Internal IP	Role
forge-control	`10.100.0.3`	Orchestration API, beam scheduler
forge-beams	`10.100.0.4`	Beam compute host (Docker / Firecracker)
forge-data	`10.100.0.2`	PostgreSQL (beam state) + artifact store

Quick health check

curl https://cortex.aicloud.so/api/v1/status | python3 -m json.tool

Expected response

{
  "success": true,
  "data": {
    "service": "cortex",
    "status": "ok",
    "checks": { "db": "ok", "redis": "ok" }
  }
}

curl http://34.31.55.70:3112/api/forge/health

Demo Users

The demo org comes pre-seeded with four users covering all role levels. Use these to explore the platform without setting up real accounts.

First time? Run the seed command once to create these users, then log in at cortex.aicloud.so/login.

Role	Name	Email	Password
org-admin	Alice Johnson	`alice@demo.cortex.local`	`Alice@Demo2026!`
knowledge-steward	Bob Chen	`bob@demo.cortex.local`	`Bob@Demo2026!`
contributor	Carol Williams	`carol@demo.cortex.local`	`Carol@Demo2026!`
viewer	Dave Kumar	`dave@demo.cortex.local`	`Dave@Demo2026!`

Seed command (run once)

curl -X POST https://cortex.aicloud.so/api/admin/seed-demo \
  -H "Authorization: Bearer <FORGE_SHARED_SECRET>" \
  | python3 -m json.tool

What each role can do

Alice — org-admin

Manage all users and roles
Approve / reject KB proposals
Access system health dashboard
Configure org settings and beam isolation
Trigger any workflow

Bob — knowledge-steward

Review and approve KB proposals
Edit and merge KB pages
Cannot manage users or system settings

Carol — contributor

Create and edit KB pages
Submit proposals for review
Cannot approve proposals

Dave — viewer

Browse and search KB only
All write actions are blocked
Good for testing access controls

Using Cortex

Knowledge Base (KB)

Cortex KB is an AI-assisted, review-gated knowledge store. Pages go through a proposal → review → publish lifecycle.

URL	What you can do
`/kb`	Browse all KB pages, search, filter by sensitivity
`/kb/candidates`	Review pending AI-extracted proposals (stewards/admins)
`/kb/new`	Create a manual KB page

Workflows

Workflows are multi-step agent tasks. Each step runs in an isolated beam.

Trigger a Repo Onboard workflow

1. Go to https://cortex.aicloud.so/workflows
2. Click New Run → select "Repo Onboard"
3. Enter any public GitHub repo URL
4. Watch the beam spawn on forge-beams
5. On completion, proposals appear in /kb/candidates
6. Approve → they become searchable KB pages

Admin pages

URL	Purpose
`/admin/health`	System health — DB, Redis, beam counts
`/admin/org-setup`	Org config, beam isolation toggle
`/admin/users`	User management, role assignment
`/admin/audit`	Immutable audit log viewer
`/admin/monitor`	Live beam and agent monitor
`/admin/vault`	Secret management (break-glass access)

Seed workflow templates

curl -X POST https://cortex.aicloud.so/api/admin/seed-workflows \
  -H "Authorization: Bearer <FORGE_SHARED_SECRET>"

Forge CLI Reference

forge-connect is the developer CLI for creating and managing agent workspaces (beams).

Authentication

forge-connect login                                   # browser OAuth
forge-connect login --instance https://cortex.aicloud.so  # specify instance
forge-connect logout

Beam lifecycle

forge-connect create <task-name>    # boot a new isolated beam
forge-connect status               # list running beams
forge-connect                      # SSH into the most recent beam
forge-connect ssh <beam-name>      # SSH into a specific beam
forge-connect stop <beam-name>     # stop a beam (artifacts uploaded)
forge-connect rm <beam-name>       # destroy beam and free resources

Working inside a beam

forge-connect exec -- docker ps              # run a command in the beam
forge-connect exec -- claude "fix the auth bug"  # run an agent task
forge-connect logs <beam-name>              # tail beam logs
forge-connect logs <beam-name> --follow     # stream logs live

Local forge stack

# Start the local forge stack (from full macOS install)
docker compose -f ~/.forge/local/docker-compose.yml up -d

# Verify forge-control is running
curl http://localhost:3112/api/forge/health

# Connect to local beam database
psql -h localhost -p 5434 -U forge -d forge

# Stop local stack
docker compose -f ~/.forge/local/docker-compose.yml down

Example end-to-end session

Terminal

$ forge-connect create fix-auth-bug
✓ beam booted in 187ms (docker, 2 vCPU, 4 GB)
✓ KB context loaded — 3 pages relevant to auth/
✓ agent identity: cert-eng-alice-3a92.crt (1h TTL)

$ forge-connect exec -- claude "find and fix the session cookie bug"
[agent] reading src/auth/session.ts ...
[agent] found: cookie expiry off by 1000x
[agent] patching + running tests ...
[agent] all 42 tests pass — opening PR #1247

✓ artifacts: 1 PR, 3 audit events, 1 KB candidate

API Reference

Authentication

All API requests (except public endpoints) require a session cookie or API token.

API token header

Authorization: Bearer <your-api-token>

Generate tokens at /admin/vault or via POST /api/v1/tokens.

Core endpoints

Method	Path	Description
GET	`/api/v1/status`	Platform health (public)
GET	`/api/metrics`	Prometheus metrics (public)
GET	`/api/v1/search?q=<query>`	Semantic KB search
GET	`/api/v1/pages`	List KB pages
POST	`/api/v1/pages`	Create KB page
GET	`/api/v1/workflows`	List workflow templates
POST	`/api/v1/workflows/:id/runs`	Trigger a workflow run
GET	`/api/v1/audit`	Query audit log
POST	`/api/v1/agents`	Dispatch an agent beam
GET	`/api/v1/agents/:id`	Get beam status + artifacts

Admin-only endpoints

Method	Path	Description
POST	`/api/admin/seed-demo`	Seed demo org + 4 users
POST	`/api/admin/seed-workflows`	Seed workflow templates
GET	`/api/admin/health`	Detailed system health

forge-control API (HMAC-authenticated)

forge-control health check

curl http://34.31.55.70:3112/api/forge/health

All other forge-control calls require an X-Forge-Signature HMAC-SHA256 header computed from your FORGE_SHARED_SECRET.

Response format

All API responses use the same envelope:

{
  "success": true | false,
  "data":    { ... },    // present on success
  "error":   "message"  // present on failure
}

Architecture

Overview

┌─────────────────────────────────────────────────────────────┐
│                    Developer / Browser                       │
│                         (HTTPS)                             │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
          ┌────────────────────────────────┐
          │   cortex.aicloud.so            │
          │   (Google Cloud Run)           │
          │                                │
          │  • SvelteKit 2 + Svelte 5      │
          │  • Drizzle ORM → Cloud SQL     │
          │  • Redis (Memorystore)         │
          │  • Auth.js v5 (sessions)       │
          └──────────────┬─────────────────┘
                         │ HMAC-signed request
                         │ (X-Forge-Signature)
                         ▼
          ┌─────────────────────────────────┐
          │   forge-control                  │
          │   10.100.0.3 │ 34.31.55.70:3112  │
          │                                  │
          │  • Beam scheduler                │
          │  • Policy enforcement            │
          │  • Certificate authority         │
          └──────────────┬──────────────────┘
                         │ docker run / firecracker boot
                         ▼
          ┌─────────────────────────────────┐
          │   forge-beams                    │
          │   10.100.0.4                     │
          │                                  │
          │  • Firecracker microVMs          │
          │  • One VM per beam               │
          │  • Deny-by-default egress        │
          │  • 1-hour cert per agent         │
          └──────────────┬──────────────────┘
                         │ results webhook
                         ▼
          ┌─────────────────────────────────┐
          │   cortex.aicloud.so             │
          │   /api/forge/webhook            │
          │                                  │
          │  KB proposals → review → pages  │
          └─────────────────────────────────┘

Data flow

Trigger — user triggers a workflow or forge-connect beam from their terminal or the Cortex web app.

Dispatch — Cortex sends an HMAC-signed request to forge-control with the beam spec and callback token.

Boot — forge-control boots a Firecracker microVM on forge-beams in ~125 ms. The agent gets a 1-hour cert, no API keys.

Execute — the agent works with your code, KB context, and explicitly allowed integrations.

Artifacts — on completion, PRs, KB candidates, and audit events are posted back to Cortex via signed webhook.

Review — KB proposals enter review. Human approval required before anything is published to the knowledge base.

Tech stack

Layer	Technology
Frontend	SvelteKit 2 + Svelte 5 (runes)
Database	PostgreSQL 16 + pgvector + pg_trgm (Cloud SQL)
Cache / Sessions	Redis 7 (Memorystore)
ORM	Drizzle ORM
Auth	Auth.js v5, cookie sessions
LLM	Ollama (Qwen 2.5) via OpenAI-compat API
Agent isolation	Firecracker microVMs (Phase 1: Docker)
Hosting	Google Cloud Run (Cortex) + GCE (forge VMs)
Monitoring	Prometheus metrics endpoint

Roles & Access Control

Access is role-based with org-scoped assignments. Roles are granted by an org-admin and stored in the immutable audit log.

Role	KB browse	KB create	KB approve	Manage users	System admin
org-admin	✓	✓	✓	✓	✓
knowledge-steward	✓	✓	✓	—	—
contributor	✓	✓	—	—	—
viewer	✓	—	—	—	—
`secret-keeper`	✓	✓	—	—	Vault access
`auditor`	✓	—	—	—	Audit log access

Grant a role via API

curl -X POST https://cortex.aicloud.so/api/roles/grant \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"userId":"usr_...", "roleName":"contributor", "scope":"team-id"}'

Troubleshooting

`forge-connect: command not found`

Run source ~/.zshrc or open a new terminal. Or manually add ~/.local/bin to your PATH.

Login fails with "invalid credentials"

Ensure demo users are seeded: POST /api/admin/seed-demo. If already seeded, check the email + password match exactly.

Health shows `redis: degraded`

Memorystore instance may be unreachable. Check the VPC peering between Cloud Run and Memorystore. Cortex falls back to in-memory sessions automatically.

Beam step hangs in workflow

Check forge-control is reachable: curl http://34.31.55.70:3112/api/forge/health. VPC peering between Cloud Run and forge-mesh VPC may be needed.

Migration errors on startup

Check startup logs in Cloud Run. The migration runner skips "already exists" errors — if it fails, check the __drizzle_migrations table in Cloud SQL.

`relation "orgs" does not exist`

The schema uses teams and team_members, not orgs. Ensure you're running the latest version of Cortex (post v1.0.30).

Local docker-compose not found

Run the full macOS installer to set up the local forge stack: ~/.forge/local/docker-compose.yml.

HMAC signature errors from forge-control

Ensure FORGE_SHARED_SECRET matches in both Cortex and forge-control. Check the Cloud Run env vars and forge-control config.

Useful diagnostic commands

# Platform health
curl https://cortex.aicloud.so/api/v1/status | python3 -m json.tool

# forge-control health
curl http://34.31.55.70:3112/api/forge/health

# Cloud Run logs (last 50 lines)
gcloud logging read \
  'resource.type="cloud_run_revision" resource.labels.service_name="cortex"' \
  --limit 50 --project cortex-493817 --format json \
  | python3 -m json.tool

# PostgreSQL connection check (requires Cloud SQL Auth Proxy or VPC)
psql "postgresql://cortex:cortex_dev@localhost:5433/cortex" -c "SELECT NOW();"

Still stuck? Email support@cortex.ai with your org slug and the output of the health check above.

Quick Start

Sign up at the portal

Copy your bootstrap command from the dashboard

Install forge-connect on each dev machine

Installation

Where to find your license key & org slug

forge-connect CLI (developer laptops)

Full macOS installer (local forge stack)

Prerequisites

Post-install forge-connect setup

Platform URLs & Endpoints

Public endpoints

Internal VPC addresses (forge mesh)

Quick health check

Demo Users

Seed command (run once)

What each role can do

Using Cortex

Knowledge Base (KB)

Workflows

Admin pages

Seed workflow templates

Forge CLI Reference

Authentication

Beam lifecycle

Working inside a beam

Local forge stack

Example end-to-end session

API Reference

Authentication

Core endpoints

Admin-only endpoints

forge-control API (HMAC-authenticated)

Response format

Architecture

Overview

Data flow

Tech stack

Roles & Access Control

Grant a role via API

Troubleshooting

forge-connect: command not found

Login fails with "invalid credentials"

Health shows redis: degraded

Beam step hangs in workflow

Migration errors on startup

relation "orgs" does not exist

Local docker-compose not found

HMAC signature errors from forge-control

Useful diagnostic commands

`forge-connect: command not found`

Health shows `redis: degraded`

`relation "orgs" does not exist`