Marcus Configuration Reference

📖 See Also:

Local Development — first-time setup and directory structure

Development Workflow — daily development workflows

This is the comprehensive reference for all Marcus configuration options. For setup guides and workflows, see the linked documents above.

Marcus runs locally via ./marcus start. Docker is required only if you choose Planka as your kanban provider — it runs Planka + Postgres as infrastructure. Marcus itself does not run inside Docker in the current default workflow.

Quick Start

Basic Configuration

# 1. Copy the example config and edit it
cp config_marcus.example.json config_marcus.json

# 2. Set your LLM API key in .env
cp .env.example .env
echo "CLAUDE_API_KEY=sk-ant-..." >> .env

# 3. Start Marcus (SQLite kanban — zero external dependencies)
./marcus start

To use a non-default config file:

MARCUS_CONFIG=config_marcus.json.planka ./marcus start

To switch transports or ports:

./marcus start --port 5000           # custom HTTP port
./marcus start --stdio                # stdio transport
./marcus start --multi                # multi-endpoint mode

All Environment Variables

Core Configuration

Variable	Description	Default
`MARCUS_CONFIG`	Path to configuration JSON file	`config_marcus.json`
`MARCUS_PORT`	HTTP server port	`4298`
`MARCUS_DEBUG`	Enable debug logging	`false`
`MARCUS_TRANSPORT`	Transport type (`stdio` or `http`)	`stdio`
`MARCUS_DECOMPOSER`	Task decomposition strategy (`contract_first` or `feature_based`)	`contract_first`

Kanban Integration

Variable	Description	Default
`MARCUS_KANBAN_PROVIDER`	Provider: `sqlite`, `planka`, `github`, or `linear`	`sqlite`

Marcus uses SQLite by default. No environment variable is required for the default setup. The KANBAN_PROVIDER (without prefix) is also accepted as a legacy fallback.

SQLite Provider (default)

Field (config_marcus.json)	Description	Default
`kanban.sqlite_db_path`	Path to SQLite database	`./data/kanban.db`
`kanban.sqlite_attachments_dir`	Path for task attachments	`./data/attachments`

SQLite has no environment variables — it's configured via config_marcus.json only. Marcus creates the file on first project creation.

Planka Provider

Variable	Description	Required
`MARCUS_KANBAN_PLANKA_BASE_URL`	Planka server URL	Yes
`MARCUS_KANBAN_PLANKA_EMAIL`	Planka login email	Yes
`MARCUS_KANBAN_PLANKA_PASSWORD`	Planka password	Yes
`MARCUS_KANBAN_PLANKA_PROJECT_ID`	Project UUID	Optional (auto-discovered if omitted)
`MARCUS_KANBAN_PLANKA_BOARD_ID`	Board UUID	Optional (auto-discovered if omitted)

GitHub Provider (alpha — provider exists, end-to-end testing pending)

Variable	Description	Required
`MARCUS_KANBAN_GITHUB_TOKEN`	GitHub personal access token	Yes
`MARCUS_KANBAN_GITHUB_OWNER`	GitHub username/org	Yes
`MARCUS_KANBAN_GITHUB_REPO`	Repository name	Yes

Linear Provider (alpha — provider exists, end-to-end testing pending)

Variable	Description	Required
`MARCUS_KANBAN_LINEAR_API_KEY`	Linear API key	Yes
`MARCUS_KANBAN_LINEAR_TEAM_ID`	Linear team ID	Yes

AI Configuration

Variable	Description	Default
`MARCUS_AI_ENABLED`	Enable/disable AI features	`true`
`MARCUS_LLM_PROVIDER`	Provider: `anthropic`, `openai`, `local`	`anthropic`
`MARCUS_AI_MODEL`	Model name	`claude-haiku-4-5-20251001`

Anthropic (Claude)

Variable	Description	Required
`MARCUS_AI_ANTHROPIC_API_KEY`	Anthropic API key (canonical)	Yes if using Claude
`CLAUDE_API_KEY`	Alternative key name. Marcus prefers this so it doesn't collide with Claude Code's subscription auth (`ANTHROPIC_API_KEY`)	Fallback

OpenAI

Variable	Description	Required
`MARCUS_AI_OPENAI_API_KEY`	OpenAI API key	Yes if using GPT

Local LLM (Ollama)

Variable	Description	Required
`MARCUS_LOCAL_LLM_PATH`	Model name (e.g., `qwen2.5-coder:7b`) — maps to `ai.local_model` in the config file	Yes if using local
`MARCUS_LOCAL_LLM_URL`	Ollama server URL (e.g., `http://localhost:11434/v1`) — maps to `ai.local_url`	Optional
`MARCUS_LOCAL_LLM_KEY`	API key for the local server — maps to `ai.local_key`	Optional

Communication

Variable	Description	Default
`MARCUS_SLACK_ENABLED`	Enable Slack notifications	`false`
`MARCUS_SLACK_WEBHOOK_URL`	Slack webhook URL	—
`MARCUS_EMAIL_ENABLED`	Enable email notifications	`false`

Monitoring

Variable	Description	Default
`MARCUS_MONITORING_INTERVAL`	Monitoring interval (seconds)	`900` (15 min)

Configuration Priority

Marcus loads configuration in this order (later overrides earlier):

Default values (built into code)
Config file (path resolved by MARCUS_CONFIG env var, then current dir, then project root, then ~/.marcus/)
Environment variables (highest priority)

Example:

# Config file has: "ai.model": "claude-haiku-4-5-20251001"
# Environment variable overrides it:
MARCUS_AI_MODEL=claude-sonnet-4-6 ./marcus start
# Result: Uses claude-sonnet-4-6

Configuration File Format

The actual schema uses flat keys with prefixes under each section (matches config_marcus.example.json):

{
  "kanban": {
    "provider": "sqlite",
    "sqlite_db_path": "./data/kanban.db",
    "sqlite_attachments_dir": "./data/attachments",
    "planka_base_url": "http://localhost:3333",
    "planka_email": "demo@demo.demo",
    "planka_password": "demo",  // pragma: allowlist secret
    "github_token": "${GITHUB_TOKEN}",
    "github_owner": "${GITHUB_OWNER}",
    "github_repo": "${GITHUB_REPO}",
    "linear_api_key": "${LINEAR_API_KEY}",
    "linear_team_id": "${LINEAR_TEAM_ID}"
  },
  "ai": {
    "provider": "anthropic",
    "anthropic_api_key": "${CLAUDE_API_KEY}",
    "openai_api_key": "${OPENAI_API_KEY}",
    "local_model": "qwen2.5-coder:7b",
    "local_url": "http://localhost:11434/v1",
    "local_key": "none",
    "model": "claude-haiku-4-5-20251001",
    "temperature": 0.1,
    "max_tokens": 4096,
    "enabled": true
  },
  "features": {
    "events": true,
    "context": true,
    "memory": false,
    "visibility": false
  },
  "monitoring": {
    "interval": 900,
    "stall_threshold_hours": 24
  },
  "communication": {
    "slack_enabled": false,
    "email_enabled": false
  }
}

Provider-specific keys live alongside provider (flat), not nested. ${VAR} references are interpolated from the environment at load time.

Common Configuration Patterns

Switching between providers

# Default — SQLite, zero setup
./marcus start

# Use Planka instead (requires Docker for Planka + Postgres)
MARCUS_KANBAN_PROVIDER=planka ./marcus start

Or maintain multiple config files:

MARCUS_CONFIG=config_marcus.json.planka ./marcus start
MARCUS_CONFIG=config_marcus.json.github ./marcus start

Using different AI models

# Higher-tier Claude
MARCUS_AI_MODEL=claude-sonnet-4-6 ./marcus start
MARCUS_AI_MODEL=claude-opus-4-7 ./marcus start

# Free local Ollama model
MARCUS_LLM_PROVIDER=local \
MARCUS_LOCAL_LLM_PATH=qwen2.5-coder:7b \
./marcus start

Multiple Marcus Instances (parallel experiments)

As of v0.4.0-dev (parallel experiment platform), multiple Marcus instances can run side by side, each with its own SQLite kanban DB:

# Instance 1 on port 4298 (default), DB ./data/kanban-A.db
MARCUS_CONFIG=config_a.json ./marcus start

# Instance 2 on port 5000, DB ./data/kanban-B.db
MARCUS_CONFIG=config_b.json ./marcus start --port 5000

Each agent connects via the MARCUS_URL environment variable (http://localhost:4298/mcp or http://localhost:5000/mcp). Posidonius automates this for batch experiments.

Selecting the decomposer

# Default: contract_first (works on tightly-coupled and loosely-coupled projects)
./marcus start

# Legacy feature-based decomposition
MARCUS_DECOMPOSER=feature_based ./marcus start

# Per-call override (passed to create_project as options["decomposer"])

See Contract-First Decomposition for the trade-offs.

Configuration Best Practices

Use environment variables for secrets (API keys, tokens). Reference them in config_marcus.json via ${VAR_NAME}.
Use config files for structure (board IDs, model names, feature flags).
Create a .env file for persistent local settings — Marcus reads it automatically.
Keep multiple config files per environment (config_marcus.json.dev, config_marcus.json.prod).
Never commit API keys to version control. .env is gitignored by default.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Marcus Configuration Reference

Quick Start

Basic Configuration

All Environment Variables

Core Configuration

Kanban Integration

SQLite Provider (default)

Planka Provider

GitHub Provider (alpha — provider exists, end-to-end testing pending)

Linear Provider (alpha — provider exists, end-to-end testing pending)

AI Configuration

Anthropic (Claude)

OpenAI

Local LLM (Ollama)

Communication

Monitoring

Configuration Priority

Configuration File Format

Common Configuration Patterns

Switching between providers

Using different AI models

Multiple Marcus Instances (parallel experiments)

Selecting the decomposer

Configuration Best Practices

See Also

FilesExpand file tree

configuration.md

Latest commit

History

configuration.md

File metadata and controls

Marcus Configuration Reference

Quick Start

Basic Configuration

All Environment Variables

Core Configuration

Kanban Integration

SQLite Provider (default)

Planka Provider

GitHub Provider (alpha — provider exists, end-to-end testing pending)

Linear Provider (alpha — provider exists, end-to-end testing pending)

AI Configuration

Anthropic (Claude)

OpenAI

Local LLM (Ollama)

Communication

Monitoring

Configuration Priority

Configuration File Format

Common Configuration Patterns

Switching between providers

Using different AI models

Multiple Marcus Instances (parallel experiments)

Selecting the decomposer

Configuration Best Practices

See Also