Skip to content

Workspace Initialization

The karenina init command creates a ready-to-use workspace with configuration files and directory structure. This is the fastest way to get started with Karenina.

Quick Setup

Run karenina init with no flags for a quick setup using sensible defaults:

karenina init

This creates the following workspace structure:

your-project/
├── defaults.json       # Default LLM provider and model settings
├── .env                # Environment variables (paths, async, API keys)
├── dbs/                # SQLAlchemy database files
├── presets/            # Verification preset files
├── mcp_presets/        # MCP-specific preset files
└── checkpoints/        # Checkpoint (.jsonld) files

The quick setup uses these defaults:

Setting Default Value
Provider anthropic
Model claude-haiku-4-5
Interface langchain
Async enabled true
Async workers 2

Created Files

defaults.json

Stores default LLM configuration used by the GUI and server:

{
  "default_interface": "langchain",
  "default_provider": "anthropic",
  "default_model": "claude-haiku-4-5",
  "default_endpoint_base_url": ""
}

.env

Stores environment variables for directory paths, async settings, and API key placeholders:

# Karenina Configuration (generated by karenina init)
DB_PATH=./dbs
KARENINA_PRESETS_DIR=./presets
MCP_PRESETS_DIR=./mcp_presets
KARENINA_ASYNC_ENABLED=true
KARENINA_ASYNC_MAX_WORKERS=2

# API Keys
# OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# GOOGLE_API_KEY=

The .env file is created with restricted permissions (chmod 600) to protect API keys.

Tip

Add your API keys to .env before running verification. See Environment Variables for all available settings.

Created Directories

Directory Purpose Related Env Var
dbs/ SQLAlchemy database files for storing verification results DB_PATH
presets/ Verification preset JSON files KARENINA_PRESETS_DIR
mcp_presets/ MCP-specific preset files MCP_PRESETS_DIR
checkpoints/ Checkpoint (.jsonld) benchmark files —

If a directory already exists, karenina init skips it without error.

Advanced Setup

Use --advanced (or -a) for a guided setup that lets you customize every setting:

karenina init --advanced

The advanced setup prompts for:

  1. Directory configuration — Custom paths for databases, presets, MCP presets, and checkpoints
  2. Default LLM configuration — Provider (openai, anthropic, google_genai, openrouter) and model name
  3. Performance configuration — Enable/disable async processing and set worker count
  4. API keys — Optionally enter API keys during setup (stored in .env)

Command Options

Option Short Description
--dir PATH -d Working directory for Karenina data (default: current directory)
--advanced -a Run advanced setup with all options
--force -f Overwrite existing configuration

Overwriting Existing Configuration

If defaults.json already exists, karenina init asks for confirmation before overwriting. Use --force to skip this prompt:

karenina init --force           # Reset with defaults
karenina init --advanced --force  # Reset with guided setup

Custom Working Directory

By default, files are created in the current directory. Use --dir to specify a different location:

karenina init --dir ~/karenina-workspace

Next Steps