Skip to main content

​
Quick Start

For the fastest setup, see the Quickstart Guide which covers installation, API setup, and connecting to your coding assistant in under 5 minutes.

​
Prerequisites

​
System Requirements

  • Node.js: ≥ 20.0.0 (specified in engines)
  • pnpm: ≥ 9.14.0 (npm is also supported)
  • Operating System: Linux, macOS, or Windows
  • Memory: Minimum 4GB RAM (8GB+ recommended for better performance)

​
Optional External Services

  • Neo4j: For advanced knowledge graph memory (optional)
  • Redis: For distributed caching (optional, defaults to in-memory)
  • Qdrant/Milvus: For external vector storage (optional, defaults to in-memory)
  • Ollama: For local LLM hosting (optional)

​
Installation Methods

# Install globally
npm install -g @byterover/cipher

# Or install locally in your project
npm install @byterover/cipher

# Clone repository
git clone https://github.com/campfirein/cipher.git
cd cipher

# Setup environment
cp .env.example .env
# Edit .env with your API keys (see Environment Setup below)

# Start with Docker Compose
docker-compose up -d

# Verify installation
curl http://localhost:3000/health

​
3. Build from Source (Development)

# Clone repository
git clone https://github.com/campfirein/cipher.git
cd cipher

# Install dependencies and build
pnpm install && pnpm run build && npm link

# Setup environment
cp .env.example .env
# Configure your API keys (see Environment Setup below)

# Verify installation
cipher --version

​
Environment Setup

​
Required Configuration

You need at least one API provider. For source builds, copy the environment template: 
# Source/Docker installations
cp .env.example .env

# Edit .env with at least one API provider:
OPENAI_API_KEY=your_openai_api_key_here          # For GPT models
ANTHROPIC_API_KEY=your_anthropic_api_key_here    # For Claude models  
OPENROUTER_API_KEY=your_openrouter_api_key_here  # For 200+ models
OLLAMA_BASE_URL=http://localhost:11434/v1        # For self-hosted models
Get API keys from: For advanced configuration options, see the Configuration Guide.

​
Verification

​
Basic Testing

cipher --version                 # Show version
cipher "Hello, how are you?"     # One-shot test
cipher --mode mcp                # Start as MCP server

​
Advanced Testing

For API mode testing and integration examples, see the Connections Guide.

​
Development Setup

​
For Contributors

# Development workflow
pnpm install                # Install dependencies
pnpm run build             # Build project
pnpm run typecheck         # Type checking
pnpm run lint:fix          # Lint and fix
pnpm run format            # Format code
pnpm run test              # Run tests

# Development mode with file watching
pnpm run dev               # TypeScript compilation with watch mode

​
Quality Assurance Commands

pnpm run precommit         # Full pre-commit checks
pnpm run test:unit         # Unit tests only
pnpm run test:integration  # Integration tests only

​
Architecture Overview

​
Runtime Modes

  • CLI Mode: Interactive command-line interface (default)
  • API Mode: REST server for programmatic access
  • MCP Mode: Model Context Protocol server for tool integration
  • One-shot Mode: Execute single commands and exit

​
Key Components

  • Memory System: Persistent storage with vector search and knowledge graphs
  • Multi-LLM Support: OpenAI, Anthropic, OpenRouter, Ollama integration
  • MCP Integration: Connect to external tools and development environments
For detailed architecture information, see the Overview and Memory Overview pages.

​
Troubleshooting

​
Common Issues

  1. Node.js Version: Ensure Node.js ≥20.0.0
  2. API Keys: At least one LLM provider API key required
  3. Build Errors (source builds): Run pnpm run typecheck to identify issues
  4. Port Conflicts: Use --port flag to change default port (3000)

​
Getting Help

⌘I