Configuration Reference

Arcen splits its settings into two locations: non-secret behaviors live in config.yaml, while API keys and connection secrets live in .env.

1. File Locations & Profiles

By default, files are placed in the ~/.arcen directory. However, Arcen dynamically resolves paths through get_arcen_home(). You can change profiles using the ARCEN_PROFILE env variable to run isolated workspaces:

• Default Home: ~/.arcen
• Settings: ~/.arcen/config.yaml
• Secrets: ~/.arcen/.env
• Logs Directory: ~/.arcen/logs/ (stores agent.log, errors.log, and gateway.log)

2. Configuration Sections (config.yaml)

Below is the structure of ~/.arcen/config.yaml with explanations of key configuration parameters:

# Active model configuration
model:
  provider: openrouter
  model: anthropic/claude-3.5-sonnet
  temperature: 0.2
  max_tokens: 4096

# Agent execution options
agent:
  max_iterations: 90               # Max tool iterations per prompt
  quiet_mode: false
  save_trajectories: true          # Save conversation files under .system_generated/logs

# Terminal execution options
terminal:
  cwd: /Users/aditya/Coding/workspace # Default directory for tool execution
  backend: local                   # local, docker, ssh, modal, daytona, singularity
  timeout_seconds: 300             # Max duration for running child terminal scripts

# Visual CLI display themes
display:
  skin: default                    # default, ares, mono, slate, cyberpunk
  tool_progress_command: true

# Conversation context compression
compression:
  enabled: true
  trigger_threshold_tokens: 12000  # Compress context when history exceeds this limit

# Pluggable memory configuration
memory:
  provider: honcho                 # honcho, mem0, supermemory
  disable_context_files: false     # Skip loading project instruction context files

# Security & Approvals
security:
  approvals:
    write_file: ask                # ask, allow, deny
    command: ask
    unsandboxed: ask
    read_file: allow

# Background tasks & schedulers
cron:
  enabled: true
  check_interval_seconds: 60

# Curator configurations (Background maintenance)
curator:
  enabled: true
  interval_hours: 24
  min_idle_hours: 4
  stale_after_days: 30

3. Secrets & API Keys (.env)

Secrets must be declared in ~/.arcen/.env. Arcen parses this file during runtime and populates system environment variables.

To register a new secret for a custom tool or provider, add it to OPTIONAL_ENV_VARS in arcen_cli/config.py:

"OPENWEATHER_API_KEY": {
    "description": "API key for querying local weather data",
    "prompt": "OpenWeather API Token",
    "url": "https://openweathermap.org/api",
    "password": true,
    "category": "tool",
}

Common environment variables:

• OPENAI_API_KEY: OpenAI model execution.
• ANTHROPIC_API_KEY: Anthropic endpoint access.
• TELEGRAM_BOT_TOKEN: Connection token for Telegram gateway.
• SLACK_BOT_TOKEN: Token for Slack platform bot.

4. Working Directory Rules

Arcen resolves its working directory strictly using the following hierarchy:

1. CLI Mode: Uses the current terminal directory (os.getcwd()).
2. Messaging Gateway: Uses the terminal.cwd value defined in config.yaml. The gateway automatically bridges this value to the TERMINAL_CWD environment variable for all child processes and tool executions.

5. Adding & Migrating Configuration Keys

If you are developing a new feature and need to introduce a settings key:

1. Open arcen_cli/config.py and add the default settings configuration block into DEFAULT_CONFIG.
2. If you need to transform or rename old configurations, bump the integer _config_version at the top of the file to trigger migrations.
3. Adding new keys to existing dictionaries does not require a version bump; the configuration loader automatically performs a deep-merge at startup.