Skip to main content

Overview

OrcBot uses a hierarchical configuration system that reads settings from multiple sources in priority order:
  1. Environment variables (highest priority)
  2. Local config (./orcbot.config.yaml)
  3. Home config (~/orcbot.config.yaml)
  4. 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 Gemini
  • bedrock - AWS Bedrock
  • openrouter - OpenRouter (200+ models)
  • nvidia - NVIDIA NIM
  • anthropic - Anthropic Claude
  • ollama - Local Ollama models
Policy: SAFE - Agent can switch providers based on availability.
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 session
  • per-peer - Separate session per user
  • per-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-E
  • google - Imagen
Policy: SAFE - Non-critical preference setting.
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 art
  • external - External command
  • map - Simple map
  • mapscii - 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 strictly
  • balanced - Moderate enforcement
  • fluid - 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
default:0.65
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
default:0.7
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.
object
default:{}
Map user identities across channels:

Example Configuration

orcbot.config.yaml