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.