Overview
OrcBot uses a hierarchical configuration system that reads settings from multiple sources in priority order:- Environment variables (highest priority)
- Local config (
./orcbot.config.yaml) - Home config (
~/orcbot.config.yaml) - Global config (
~/.orcbot/orcbot.config.yaml)
Configuration File Location
OrcBot searches for configuration files in this order:Environment variables always override configuration file values for API keys and credentials.
Core Settings
Agent Identity
string
default:"OrcBot"
The display name for your agent instance.
string
default:"~/.orcbot/.AI.md"
Path to the agent’s self-updating identity file containing personality and operating instructions.
LLM Configuration
string
default:"gpt-4o"
Primary LLM model to use. Examples:
gpt-4o, gpt-4-turbo, claude-3-5-sonnet-20241022, gemini-2.0-flash-exp.Policy: SAFE - Agent can modify autonomously to optimize for different tasks.enum
default:"openai"
Explicit LLM provider selection. Supported values:
openai- OpenAI (GPT-4, GPT-3.5, o1)google- Google Geminibedrock- AWS Bedrockopenrouter- OpenRouter (200+ models)nvidia- NVIDIA NIManthropic- Anthropic Claudeollama- Local Ollama models
object
Per-provider model preferences. Automatically persists the last model used for each provider.
object
Fallback models to use when primary provider is unavailable.
string
Fast model for lightweight operations (e.g.,
gpt-4o-mini, gemini-1.5-flash).Ollama (Local Models)
boolean
default:false
Enable local Ollama integration for running models locally.
string
default:"http://localhost:11434"
Ollama API endpoint URL.Policy: SAFE - Non-sensitive endpoint configuration.
Task Execution Limits
number
default:30
Maximum reasoning steps per action. Dynamically adjusted based on task complexity.Policy: SAFE - Agent can adjust complexity limits based on task needs.
number
default:10
Maximum user-facing messages per action to prevent spam.Policy: SAFE - Agent can adjust delivery budget for long-running tasks.
number
default:10
Maximum execution time for a single action in minutes.
number
default:30
Maximum time before an action is considered stale and terminated.
number
default:10
Window (in messages) for deduplicating similar user messages.
Memory System
Memory Limits
number
default:20
Number of recent short-term memories to include in context.Policy: SAFE - Agent can adjust to optimize performance (1-100).
number
default:5
Number of episodic summaries to include in context.Policy: SAFE - Agent can adjust for better context (1-20).
number
default:2000
Character limit for extended memory context.
number
default:500
Maximum length for individual memory entries (characters).
Memory File Paths
string
default:"~/.orcbot/memory.json"
Path to short-term memory storage (JSON).
string
default:"~/.orcbot/JOURNAL.md"
Path to daily journal file for long-term event logging.
string
default:"~/.orcbot/LEARNING.md"
Path to learning file where agent stores research findings.
string
default:"~/.orcbot/USER.md"
Path to user profile containing preferences and facts.
string
default:"~/.orcbot/world.md"
Path to world events log (GDELT, USGS earthquake data).
Memory Consolidation
number
default:30
Number of short-term memories before triggering consolidation to episodic.
number
default:20
Batch size for memory consolidation operations.
number
default:25
Soft threshold for flushing memories to disk.
number
default:30
Cooldown period between memory flush operations.
number
default:12
Batch size for scoped interaction consolidation.Policy: SAFE - Non-sensitive memory quality tuning (4-100).
number
default:10
Max minutes before pending interaction batch is consolidated.Policy: SAFE - Non-sensitive memory durability tuning (1-180).
number
default:5
Deduplication window for duplicate inbound memory events.Policy: SAFE - Non-sensitive reliability tuning (1-120).
Thread Context
number
default:8
Number of recent messages to include in thread context.
number
default:8
Number of relevant messages to include from semantic search.
number
default:420
Maximum line length for thread context entries.
number
default:5
Number of other memories to include in thread context.
Context Limits by Type
number
default:1500
Character limit for journal entries in context.
number
default:1500
Character limit for learning entries in context.
number
default:2000
Character limit for user profile data in context.
number
default:8
Scoped user exchange count injected into decisions.Policy: SAFE - Non-sensitive context sizing control (3-30).
Step Compaction
number
default:10
Number of steps before compaction is triggered.
number
default:2
Number of first steps to preserve during compaction.
number
default:5
Number of last steps to preserve during compaction.
boolean
default:true
Expand compacted middle step history for continuity-heavy tasks.Policy: SAFE - Non-sensitive context shaping behavior.
number
default:12
Maximum number of middle steps to expand on continuity intent.Policy: SAFE - Non-sensitive context sizing control (1-50).
number
default:2400
Maximum characters reserved for expanded middle-step context.Policy: SAFE - Non-sensitive context sizing control (400-20000).
Autonomy & Heartbeat
boolean
default:true
Enable autonomous operation mode where the agent can initiate tasks independently.Policy: APPROVAL - Autonomy mode should be explicitly approved.
number
default:15
Autonomous operation interval in minutes. Uses exponential backoff when unproductive.Policy: APPROVAL - Autonomy settings affect system behavior significantly.
number
default:90
Cooldown period after user interaction before autonomy resumes.
number
default:3
Maximum number of autonomous tasks in the queue.
array
default:[]
List of channels where the agent can send proactive messages.
Empty array means silent mode - agent will not send unsolicited messages. Direct responses are always allowed.
boolean
default:false
Allow autonomy lane to continue running while user lane is busy.Policy: APPROVAL - Parallel autonomy can increase throughput but may compete for resources.
Action Queue
string
default:"~/.orcbot/actions.json"
Path to the durable action queue file.
number
default:86400000
Time-to-live for completed actions in milliseconds (default: 24 hours).
number
default:259200000
Time-to-live for failed actions in milliseconds (default: 72 hours).
number
default:5000
Interval for flushing action queue to disk in milliseconds.
number
default:60000
Interval for action queue maintenance (cleanup) in milliseconds.
Command Execution
number
default:120000
Timeout for shell command execution in milliseconds (default: 2 minutes).
number
default:1
Number of retries for failed commands.
string
Working directory for command execution (defaults to current directory).
array
List of allowed commands. Default includes common development tools:
array
List of denied commands for security. Includes destructive operations:Policy: LOCKED - Security-critical configuration.
boolean
default:false
Automatically execute commands without confirmation (use with caution).
File Paths
string
default:"."
Root directory for source code operations. Auto-detected from
package.json location.string
default:"~/.orcbot/workspace"
Workspace directory for building and compiling code.
string
default:"~/.orcbot/SKILLS.md"
Path to skills documentation file.
string
default:"~/.orcbot/plugins"
Directory for hot-loadable TypeScript plugins.
string
default:"~/.orcbot/tools"
Directory for custom tool scripts.
Plugins
array
default:[]
Whitelist of allowed plugins. Empty means all plugins are allowed.
array
default:[]
Blacklist of denied plugins. Takes precedence over allow list.
number
default:15
Interval for checking plugin health and auto-repair.
Decision Pipeline
Skill Routing
array
default:[]
Intent-based skill selection rules for better tool matching.Policy: APPROVAL - Routing rules can affect which tools are used.
Tool Loop Protection
number
default:5
Maximum times a tool can be repeated in sequence.
number
default:15
Higher repeat limit for research tools (web_search, browser_navigate).
number
default:3
Maximum number of tool usage loops before intervention.
Autopilot Mode
boolean
default:false
Suppress clarification requests to keep agent moving autonomously.
array
default:[]
Skills allowed to ask questions even in autopilot mode.
array
default:[]
Skills explicitly denied from asking questions.
Reasoning & Simulation
boolean
default:false
Enable enhanced reasoning with deeper analysis.
boolean
default:false
Send the agent’s internal step-by-step checklist to the user before starting complex tasks.
number
default:5
Maximum number of checklist items to expose.
boolean
default:true
Skip pre-task simulation for simple/trivial tasks to reduce latency.
boolean
default:false
Use compact skill descriptions in prompts to reduce token usage.
Progress Feedback
boolean
default:true
Enable progress feedback messages during long-running tasks.Policy: SAFE - Agent can adjust feedback verbosity.
number
default:4
Send progress update every N steps.
boolean
default:true
Always send initial “working on it” message.
boolean
default:true
Use typing indicators instead of sending progress messages (reduces noise).Policy: SAFE - Agent can reduce channel noise while preserving feedback.
User Experience
enum
default:"per-channel-peer"
Conversation session scope:
main- Single global sessionper-peer- Separate session per userper-channel-peer- Separate session per channel-user combination
boolean
default:true
Prompt new users with onboarding questionnaire.
boolean
default:true
Send briefing to users who reconnect after inactivity.
number
default:3
Days of inactivity before triggering reconnect briefing.
number
default:5
Maximum completed tasks to include in briefing.
number
default:3
Maximum pending tasks to include in briefing.
boolean
default:false
Require explicit user request before send_file is allowed.Policy: SAFE - Agent can tune delivery strictness for file attachments.
Storage
number
default:5000
Maximum entries in vector memory index.
number
default:1000
Size of processed messages cache for deduplication.
string
default:"~/.orcbot/token-usage-summary.json"
Path to token usage summary file.
string
default:"~/.orcbot/token-usage.log"
Path to detailed token usage log.
Server Mode
boolean
default:false
Enable conservative defaults optimized for server/headless deployments.Applies reduced memory limits and more aggressive cleanup:
- Reduced memory context limits
- Shorter action TTLs
- More frequent maintenance cycles
- Compact skills prompt enabled
Web Gateway
number
default:3100
HTTP port for the web gateway.
string
default:"0.0.0.0"
Host address to bind the gateway server.
string
API key for authenticating gateway requests.
array
default:["*"]
CORS allowed origins for gateway API.
Image Generation
enum
Image generation provider:
openai- DALL-Egoogle- Imagen
string
Image generation model name.Policy: SAFE - Non-critical preference setting.
string
default:"1024x1024"
Default image generation size (e.g.,
1024x1024, 512x512).string
default:"medium"
Image generation quality (
low, medium, high).Agentic User
boolean
default:false
Enable agentic user simulation for testing and validation.
number
default:120
Simulated user response delay in seconds.
number
default:70
Confidence threshold (0-100) for agentic user interventions.
boolean
default:true
Enable proactive guidance from agentic user.
number
default:8
Steps before proactive guidance is triggered.
number
default:30
Interval for checking agentic user status in seconds.
number
default:3
Maximum interventions per task from agentic user.
boolean
default:true
Notify real user about agentic user interventions.
World Events
array
default:["gdelt","usgs"]
Data sources for world events tracking:
gdelt- GDELT Project (global events)usgs- USGS earthquake data
number
default:60
Interval for refreshing world events data.
number
default:60
Lookback window for fetching historical events.
number
default:250
Maximum number of event records to store.
number
default:10
Batch interval for event aggregation.
boolean
default:true
Store world events to memory.
boolean
default:true
Include world events in autonomy heartbeat.
string
default:"global"
GDELT query filter.
enum
default:"mapscii"
Globe visualization renderer:
ascii- ASCII artexternal- External commandmap- Simple mapmapscii- MapSCII terminal viewer
string
default:"mapscii"
Command for external globe renderer.
array
default:[]
Arguments for globe renderer command.
Guidance & Guardrails
enum
default:"balanced"
Completion guidance strictness:
strict- Enforce all delivery rules strictlybalanced- Moderate enforcementfluid- Flexible completion criteria
array
Regular expressions for detecting acknowledgement-only messages.
array
Regular expressions for detecting low-value status updates.
array
Keywords for detecting clarification questions.
array
Stop words to ignore when analyzing questions.
number
Similarity threshold for detecting repeated questions.
number
default:7
Maximum word count for short replies.
number
default:48
Maximum character count for short replies.
Time Signals
number
default:25
Seconds without message before triggering high-risk time signal.
number
default:4
Silent steps before medium-risk time signal.
number
default:45
Seconds since last delivery before medium-risk time signal.
Session Anchoring
boolean
default:true
Enable session anchoring for conversation continuity.
number
default:4
Maximum session anchor hints to include in context.
Task Deduplication
number
default:60000
Window for deduplicating similar tasks in milliseconds (default: 1 minute).
number
Similarity threshold (0-1) for detecting duplicate messages.
number
default:6
Deduplication window for recovery tasks in hours.
Time Capsule
number
default:500
Maximum steps to preserve in time capsule.
number
default:100
Maximum messages to preserve in time capsule.
OrcBot CLI Control
boolean
default:true
Allow agent to run orcbot CLI commands.
array
Allowed orcbot CLI commands:
array
Denied orcbot CLI commands:
number
default:45000
Timeout for orcbot CLI commands in milliseconds.
Termination Force (TForce)
boolean
default:true
Enable Termination Force incident tracking and prevention.
number
default:30
Maximum incidents tracked per action.
Usage Telemetry
boolean
default:true
Enable anonymous usage telemetry.
string
default:""
Telemetry endpoint URL.
number
default:4000
Timeout for telemetry requests in milliseconds.
string
default:""
Authentication token for telemetry.
Pi AI Integration
boolean
default:true
Enable Pi AI integration for enhanced reasoning.
Identity Links
object
Map user identities across channels:
Example Configuration
orcbot.config.yaml