Installation

Get Karen running locally with this comprehensive setup guide.

Prerequisites

Node.js

Karen requires Node.js 20.0.0 or higher.

node --version
# Should output: v20.x.x or higher

From package.json:

"engines": {
  "node": ">=20.0.0"
}

LLM API Key

Karen supports multiple LLM providers. You need at least one API key:

OpenAI
Anthropic
xAI (Grok)
Google (Gemini)

Recommended for beginners. Best balance of cost and performance.

Sign up at platform.openai.com
Navigate to API Keys
Create new key with name “Karen”
Copy key (starts with sk-)

Models supported:

gpt-4o (default, most capable)
gpt-4o-mini (faster, cheaper)
gpt-3.5-turbo (legacy)

Cost: ~$0.005 per agent cycle (30 seconds)

Best for complex reasoning. Excellent for sophisticated strategies.

Sign up at console.anthropic.com
Navigate to API Keys
Create new key
Copy key (starts with sk-ant-)

Models supported:

claude-sonnet-4-20250514 (default, most capable)
claude-3-haiku (faster, cheaper)

Cost: ~$0.003 per agent cycle

Fastest responses. Good for high-frequency trading.

Sign up at console.x.ai
Generate API key
Copy key (starts with xai-)

Models supported:

grok-3-latest (default)

Cost: Varies by usage

Most cost-effective. Great for testing.

Sign up at aistudio.google.com
Get API key
Copy key

Models supported:

gemini-2.0-flash (default)

Cost: Free tier available

Git

For cloning the repository:

git --version
# If not installed: https://git-scm.com/downloads

Installation Steps

1. Clone Repository

git clone https://github.com/Don-Vicks/karen.git
cd karen

The official repository is at https://github.com/Don-Vicks/karen

2. Install Dependencies

Karen uses standard npm packages. Choose your preferred package manager:

npm install

Key dependencies (from package.json):

"dependencies": {
  "@anthropic-ai/sdk": "^0.39.0",
  "@google/genai": "^1.43.0",
  "@solana/web3.js": "^1.98.0",
  "@solana/spl-token": "^0.4.9",
  "openai": "^4.77.0",
  "commander": "^13.0.0",
  "chalk": "^5.4.1",
  "dotenv": "^16.4.7"
}

Installation takes ~2-3 minutes depending on connection speed.

3. Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env with your settings:

.env

# ============================================
# Karen Configuration
# ============================================

# Solana
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_NETWORK=devnet

# LLM Providers (at least one required)
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
XAI_API_KEY=xai-your-grok-key
GEMINI_API_KEY=your-gemini-key

# Keystore encryption
KEYSTORE_PASSWORD=your-secure-password-here

# API Server
API_PORT=3001
API_SECRET=your-api-secret-for-external-agents

# MCP Server
MCP_ENABLED=true

# Agent defaults
DEFAULT_LLM_PROVIDER=openai
DEFAULT_LLM_MODEL=gpt-4o
AGENT_LOOP_INTERVAL_MS=30000
MAX_TX_PER_MINUTE=5
MAX_SOL_PER_TX=2.0
DAILY_SPENDING_LIMIT_SOL=10.0

# Telegram Integration (optional)
TELEGRAM_BOT_TOKEN=
TELEGRAM_ALLOWED_USERS=

Configuration Reference

Solana Settings

Variable	Description	Default
`SOLANA_RPC_URL`	Solana RPC endpoint	`https://api.devnet.solana.com`
`SOLANA_NETWORK`	Network (`devnet`, `testnet`, `mainnet-beta`)	`devnet`

Alternative RPC providers:

Helius: https://devnet.helius-rpc.com/?api-key=YOUR_KEY
Alchemy: https://solana-devnet.g.alchemy.com/v2/YOUR_KEY
QuickNode: https://your-endpoint.solana-devnet.quiknode.pro/YOUR_KEY/

LLM Provider Keys

Add at least one API key:

Variable	Format	Get Key
`OPENAI_API_KEY`	`sk-...`	platform.openai.com
`ANTHROPIC_API_KEY`	`sk-ant-...`	console.anthropic.com
`XAI_API_KEY`	`xai-...`	console.x.ai
`GEMINI_API_KEY`	Any string	aistudio.google.com

Keys are loaded in src/agent/runtime.ts:75-89:

private getLlm(): LLMProvider {
  if (this.llm) return this.llm

  if (this.config.llmProvider === 'anthropic') {
    this.llm = new AnthropicProvider()
  } else if (this.config.llmProvider === 'grok') {
    this.llm = new GrokProvider()
  } else if (this.config.llmProvider === 'gemini') {
    this.llm = new GeminiProvider()
  } else {
    this.llm = new OpenAIProvider()
  }

  return this.llm
}

Keystore Security

Variable	Description	Recommendation
`KEYSTORE_PASSWORD`	Master password for wallet encryption	Use 32+ random characters

Generate secure password:

openssl rand -base64 32

Keystores are encrypted with AES-256-GCM and scrypt key derivation (N=16384, r=8, p=1).

Never commit .env to version control. The .gitignore already excludes it.

API Server

Variable	Description	Default
`API_PORT`	REST API server port	`3001`
`API_SECRET`	Bearer token for admin endpoints	`karen-dev-secret`

Used by external agents to create wallets and execute transactions:

// src/api/server.ts:55
this.apiSecret = process.env.API_SECRET || 'karen-dev-secret'

Agent Defaults

Variable	Description	Default
`DEFAULT_LLM_PROVIDER`	Default LLM (`openai`, `anthropic`, `grok`, `gemini`)	`openai`
`DEFAULT_LLM_MODEL`	Default model per provider	`gpt-4o`
`AGENT_LOOP_INTERVAL_MS`	Milliseconds between agent cycles	`30000` (30s)
`MAX_TX_PER_MINUTE`	Rate limit for transactions	`5`
`MAX_SOL_PER_TX`	Max SOL per transaction	`2.0`
`DAILY_SPENDING_LIMIT_SOL`	Daily spending cap	`10.0`

These can be overridden per-agent:

karen agent create \
  --name "HighFreqBot" \
  --strategy "..." \
  --interval 10000 \
  --max-per-tx 0.5 \
  --daily-limit 5

4. Build Project

Compile TypeScript to JavaScript:

npm run build

Build script (from package.json):

"scripts": {
  "build": "tsc",
  "dev": "tsx watch src/cli/index.ts",
  "start": "node dist/cli/index.js"
}

Output is written to dist/ directory.

5. Verify Installation

Run the info command to check system health:

npm run cli -- info

Expected output:

╔═══════════════════════════════════════════╗
║  ⚡ Karen — Autonomous Wallet Infrastructure  ║
║     for Solana AI Agents                    ║  
╚═══════════════════════════════════════════╝

  System Info:

    Solana:    Connected (devnet)
    Slot:      123456789
    Wallets:   0
    Agents:    0

If Solana shows “Disconnected”, check your SOLANA_RPC_URL and internet connection.

Project Structure

After installation, your directory should look like:

karen/
├── src/                      # TypeScript source code
│   ├── core/                 # Core wallet and transaction logic
│   ├── agent/                # Agent runtime and skills
│   ├── protocols/            # DeFi protocol adapters
│   ├── api/                  # REST API server
│   ├── mcp/                  # MCP server
│   └── cli/                  # CLI interface
├── dist/                     # Compiled JavaScript (after build)
├── data/                     # Runtime data (created on first run)
│   ├── keystores/            # Encrypted wallets
│   ├── agents.json           # Agent configurations
│   ├── transactions.json     # Transaction logs
│   └── memory/               # Agent memory files
├── dashboard/                # Optional Next.js dashboard
├── .env                      # Your configuration (not in git)
├── .env.example              # Configuration template
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # Project documentation

Development Mode

For active development with auto-reload:

npm run dev

Uses tsx watch to recompile on file changes.

Optional: Dashboard Setup

Karen includes a Next.js dashboard for visual monitoring:

cd dashboard
npm install
npm run dev

Dashboard runs at http://localhost:3000 and connects to the API server at http://localhost:3001.

Optional: MCP Server Setup

To use Karen as an MCP server for Claude Desktop or OpenClaw:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "karen": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/karen/src/mcp/server.ts"]
    }
  }
}

OpenClaw

Add to your OpenClaw MCP configuration:

{
  "mcpServers": {
    "karen": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/karen/src/mcp/server.ts"]
    }
  }
}

Restart Claude/OpenClaw. You should see 17 new karen_* tools available.

Troubleshooting

Error: Cannot find module

Dependencies not installed. Run:

rm -rf node_modules package-lock.json
npm install

Error: OPENAI_API_KEY not set

Missing LLM API key. Check .env file:

cat .env | grep OPENAI_API_KEY

Should show:

OPENAI_API_KEY=sk-...

Error: connect ECONNREFUSED

Solana RPC endpoint unreachable. Try alternative:

.env

SOLANA_RPC_URL=https://api.devnet.solana.com

TypeScript errors during build

Ensure TypeScript version matches:

npm list typescript
# Should show: [email protected]

If different, reinstall:

npm install [email protected] --save-dev
npm run build

Error: EACCES permission denied

Node modules installed with wrong permissions. Fix:

sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) node_modules
npm install

Next Steps

Quickstart

Create your first agent in 5 minutes

CLI Reference

Complete command-line interface documentation

API Reference

REST API and MCP integration guide

Security Guide

Best practices for production deployment

System Requirements

Minimum

OS: macOS 10.15+, Ubuntu 20.04+, Windows 10+ (WSL2)
Node.js: 20.0.0+
RAM: 2 GB
Storage: 500 MB
Network: Stable internet connection

License

Karen is open source under the MIT License. Free for commercial and personal use.

Get Started

Core Concepts

Integration

Agent Skills

Development

Installation

Installation

Prerequisites

Node.js

LLM API Key

Git

Installation Steps

1. Clone Repository

2. Install Dependencies

3. Configure Environment

Configuration Reference

4. Build Project

5. Verify Installation

Project Structure

Development Mode

Optional: Dashboard Setup

Optional: MCP Server Setup

Claude Desktop

OpenClaw

Troubleshooting

Next Steps

Quickstart

CLI Reference

API Reference

Security Guide

System Requirements

Minimum

Recommended

License

Build docs developers (and LLMs) love

Get Started

Core Concepts

Integration

Agent Skills

Development

​Installation

​Prerequisites

​Node.js

​LLM API Key

​Git

​Installation Steps

​1. Clone Repository

​2. Install Dependencies

​3. Configure Environment

​Configuration Reference

​4. Build Project

​5. Verify Installation

​Project Structure

​Development Mode

​Optional: Dashboard Setup

​Optional: MCP Server Setup

​Claude Desktop

​OpenClaw

​Troubleshooting

​Next Steps

Quickstart

CLI Reference

API Reference

Security Guide

​System Requirements

​Minimum

​Recommended

​License

Build docs developers (and LLMs) love

Installation

Prerequisites

Node.js

LLM API Key

Git

Installation Steps

1. Clone Repository

2. Install Dependencies

3. Configure Environment

Configuration Reference

4. Build Project

5. Verify Installation

Project Structure

Development Mode

Optional: Dashboard Setup

Optional: MCP Server Setup

Claude Desktop

OpenClaw

Troubleshooting

Next Steps

System Requirements

Minimum

Recommended

License