Skip to content

configuration.mdx

Latest commit

 

History

History
338 lines (293 loc) · 9.42 KB

configuration.mdx

File metadata and controls

338 lines (293 loc) · 9.42 KB
title Configuration
sidebarTitle Configuration
description runtime.json, models.json, advanced integrations, and environment variables
icon sliders
keywords
runtime.json
models.json
MCP
configuration
environment variables
memory

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

| 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 | **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](/en/memory) for full details.
Each tool group has an `enabled` flag. Both the group and individual tool must be enabled. 
```json
{
  "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 |

<Note>
  `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.
</Note>
explicit runtime overrides: 
```json
{
  "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

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:

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

Override a mapping through Settings-backed model configuration:

```json
{
  "mapping": {
    "leon:medium": { "model": "gpt-4o", "provider": "openai" }
  }
}
```
```json { "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)
```json { "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}.

```json { "mcp": { "enabled": true, "servers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } } } } } ``` ```json { "mcp": { "enabled": true, "servers": { "remote-service": { "url": "https://mcp.example.com/sse", "allowed_tools": ["search", "fetch"] } } } } ``` Local runtime config can also carry MCP server definitions: 
```json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": { "SUPABASE_URL": "..." }
    }
  }
}
```

Observation (tracing)

```json { "active": "langfuse", "langfuse": { "secret_key": "${LANGFUSE_SECRET_KEY}", "public_key": "${LANGFUSE_PUBLIC_KEY}", "host": "https://cloud.langfuse.com" } } ``` ```json { "active": "langsmith", "langsmith": { "api_key": "${LANGSMITH_API_KEY}", "project": "mycel" } } ``` ```json { "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