Skip to content

Installation

Requirements

Dependency Version Notes
Node.js 20+ Required
npm 10+ Included with Node.js
Python 3 3.10+ Only for Python SDK usage
PostgreSQL 14+ Only for Postgres-backed deployments

Install from npm

The fastest path for most users:

npm i @cognilabz/cognibrain
npx cognibrain init --yes
npx cognibrain doctor --fix
npx cognibrain status

What init --yes does

The --yes flag accepts all defaults for the solo-dev profile:

  • Local JSON storage
  • Local-only auth (no API key required)
  • Codex + Cursor harness files
  • GitHub connector stub
  • SQLite storage adapter stub

Install from Source

Use a checkout when developing Cognibrain or testing unpublished changes:

git clone https://github.com/cognilabz/cognibrain.git
cd cognibrain
npm install
./bin/cognibrain.mjs init --yes
./bin/cognibrain.mjs doctor --fix

Profiles

init supports multiple profiles for different deployment shapes:

npx cognibrain init --profile solo-dev --yes

Local coding-agent memory on one machine. Codex/Cursor harness, local storage, no auth.

npx cognibrain init --profile team --yes

Shared team setup with all harness files, more connector stubs, Postgres/intelligence adapter stubs.

npx cognibrain init --profile enterprise --yes --no-start

Enterprise pilot with Postgres, OIDC/SSO intent, service-oriented setup.

npx cognibrain init --benchmark --yes

Reproducible benchmark/proof lab with all harnesses and proof-oriented tooling.

Defaults Reference

These defaults come from the current CLI implementation:

Setting Default Meaning
Profile solo-dev Local coding-agent memory on one machine
Harness files codex, cursor Writes Codex and Cursor memory instructions/config
Storage local-json Local runtime storage under the project runtime root
Auth local-only No OIDC/API-key gate for the local solo runtime
Connector stub github Writes non-secret GitHub connector config
Adapter stub storage-sqlite Prepares a local SQLite storage adapter config
Runtime root Current project Override with --runtime-root or COGNIBRAIN_RUNTIME_ROOT
Dashboard Off Start only with --dashboard or cognibrain dashboard

Start and Stop

npx cognibrain start      # Start the local API daemon
npx cognibrain status     # Check runtime state
npx cognibrain stop       # Stop the daemon

Service Installation

For machines that should restart Cognibrain automatically:

npx cognibrain service plan           # Preview what will be installed
npx cognibrain service install --activate  # Install and start
npx cognibrain service status         # Verify the service
Supported service managers
Platform Manager
Linux systemd user service (default); system service with --system
macOS launchd LaunchAgent (default); LaunchDaemon with --system
Windows Task Scheduler startup task

Verify the Install

After setup, run these checks:

npx cognibrain status
npx cognibrain doctor --fix
npx cognibrain config doctor
npx cognibrain connections doctor

For package/release maintainers:

npm run release:check
npm pack --dry-run

Next Steps