Configuration

runtime.json, models.json, advanced integrations, and environment variables

Mycel uses split configuration files for runtime defaults, models, observation, and provider-specific infrastructure. Product runtime state is not loaded from workspace-local runtime.json files.

Config file overview

JSON config files:

File	Purpose
runtime.json	Tools, memory, advanced integrations, security
models.json	Providers, API keys, model mapping
observation.json	Langfuse / LangSmith tracing

Other config files:

File	Purpose
ENV_FILE	Optional explicit env file
$LEON_SANDBOXES_DIR/<name>.json	Per-provider sandbox config
.mcp.json	Advanced MCP servers for local runtime config

Runtime priority: explicit server/CLI overrides → built-in defaults.

Merge strategy per domain:

Domain	Strategy
runtime, memory, tools	Deep merge — explicit overrides replace built-in defaults by field
mcp	Explicit overrides replace built-in defaults
system_prompt	Explicit override
providers, mapping (models.json)	Deep merge per-key
pool (models.json)	Last wins — no list merging
catalog, virtual_models (models.json)	System-only — never overridden

First run

Export variables in the shell, or set ENV_FILE=/path/to/mycel.env before starting the service:

OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=claude-sonnet-4-5-20250929

runtime.json

Runtime fields

Field	Default	Description
temperature	null	Sampling temperature (0–2). null = model default
max_tokens	null	Max output tokens. null = model default
context_limit	0	Context window in tokens. 0 = auto-detect
enable_audit_log	true	Audit logging for file operations
allowed_extensions	null	Restrict file access by extension. null = all
block_dangerous_commands	true	Block rm -rf, sudo, etc.
block_network_commands	false	Block network commands

Memory — pruning and compaction

Pruning trims large tool results:

Field	Default	Description
soft_trim_chars	3,000	Trim results longer than this
hard_clear_threshold	10,000	Clear results longer than this
protect_recent	3	Keep last N tool messages untrimmed

Compaction summarizes old history via LLM when context fills:

Field	Default	Description
reserve_tokens	16,384	Reserve for new messages
keep_recent_tokens	20,000	Keep recent tokens verbatim
min_messages	20	Minimum messages before trigger

See Memory for full details.

Tool configuration

Each tool group has an enabled flag. Both the group and individual tool must be enabled.

{
  "tools": {
    "filesystem": { "enabled": true },
    "search": { "enabled": true },
    "web": {
      "enabled": true,
      "tools": {
        "web_search": { "enabled": true, "tavily_api_key": null },
        "fetch": { "enabled": true }
      }
    },
    "command": {
      "enabled": true,
      "tools": {
        "run_command": { "default_timeout": 120 }
      }
    }
  }
}

Complete tool catalog:

Tool	Group	Mode
Read, Write, Edit, list_dir	filesystem	inline
Grep, Glob	search	inline
Bash	command	inline
WebSearch, WebFetch	web	inline
Agent, SendMessage, TaskOutput, TaskStop	agent	inline
TaskCreate, TaskGet, TaskList, TaskUpdate	todo	deferred
load_skill	skills	inline
tool_search	system	inline

deferred tools are not injected into every request. The agent discovers them via tool_search when needed — saving tokens in conversations that don’t require task management.

Project-level example

explicit runtime overrides:

{
  "allowed_extensions": ["py", "js", "ts", "json", "yaml", "md"],
  "block_dangerous_commands": true,
  "tools": {
    "web": { "enabled": false },
    "command": {
      "tools": {
        "run_command": { "default_timeout": 300 }
      }
    }
  },
  "system_prompt": "You are a Python expert working on a FastAPI project."
}

models.json

Virtual model aliases

Mycel provides four leon:* aliases:

Alias	Model	Use case
leon:mini	claude-haiku-4-5-20250929	Fast, simple tasks
leon:medium	claude-sonnet-4-5-20250929	Balanced, daily work
leon:large	claude-opus-4-6	Complex reasoning
leon:max	claude-opus-4-6 + temp=0	Maximum precision

Set via Settings → Models in the Web UI:

{ "active": { "model": "leon:large" } }

Override a mapping through Settings-backed model configuration:

{
  "mapping": {
    "leon:medium": { "model": "gpt-4o", "provider": "openai" }
  }
}

Provider setup

{
  "active": {
    "model": "claude-sonnet-4-5-20250929",
    "provider": null
  },
  "providers": {
    "anthropic": {
      "api_key": "${ANTHROPIC_API_KEY}",
      "base_url": "https://api.anthropic.com"
    },
    "openai": {
      "api_key": "${OPENAI_API_KEY}",
      "base_url": "https://api.openai.com/v1"
    }
  }
}

Provider auto-detection (when no explicit provider is set):

• ANTHROPIC_API_KEY set → provider = anthropic
• OPENAI_API_KEY set → provider = openai
• OPENROUTER_API_KEY set → provider = openai (OpenRouter-compatible)

Custom models

{
  "pool": {
    "custom": ["deepseek-chat"],
    "custom_config": {
      "deepseek-chat": {
        "based_on": "gpt-4o",
        "context_limit": 65536
      }
    }
  }
}

based_on tells Mycel which tokenizer to use. context_limit overrides auto-detection.

Advanced MCP servers

Connect external services via the Model Context Protocol. MCP tools appear as mcp__{server_name}__{tool_name}.

stdio (local process)

{
  "mcp": {
    "enabled": true,
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

HTTP (remote server)

{
  "mcp": {
    "enabled": true,
    "servers": {
      "remote-service": {
        "url": "https://mcp.example.com/sse",
        "allowed_tools": ["search", "fetch"]
      }
    }
  }
}

Local .mcp.json

Local runtime config can also carry MCP server definitions:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": { "SUPABASE_URL": "..." }
    }
  }
}

Observation (tracing)

Langfuse

{
  "active": "langfuse",
  "langfuse": {
    "secret_key": "${LANGFUSE_SECRET_KEY}",
    "public_key": "${LANGFUSE_PUBLIC_KEY}",
    "host": "https://cloud.langfuse.com"
  }
}

LangSmith

{
  "active": "langsmith",
  "langsmith": {
    "api_key": "${LANGSMITH_API_KEY}",
    "project": "mycel"
  }
}

Disabled

{ "active": null }

Environment variables

All string values in JSON config files support ${VAR} expansion and ~ for home directory.

Variable	Purpose
ANTHROPIC_API_KEY	Anthropic API key
OPENAI_API_KEY	OpenAI-compatible API key
OPENAI_BASE_URL	API base URL
OPENROUTER_API_KEY	OpenRouter API key
MODEL_NAME	Override active model
LEON_SANDBOX	Default sandbox name
LEON_AVATAR_ROOT	Host-side avatar image storage root
LEON_FILE_CHANNEL_ROOT	Host-side staging root for thread file uploads
TAVILY_API_KEY	Tavily web search
EXA_API_KEY	Exa search
JINA_API_KEY	Jina AI fetch
E2B_API_KEY	E2B sandbox
DAYTONA_API_KEY	Daytona sandbox
AGENTBAY_API_KEY	AgentBay sandbox