Agent Configuration

The [[agents]] array defines individual agents. Each agent inherits settings from [defaults] but can override any value.

Agent Definition

string

required

Unique identifier for the agent. Used in bindings and API calls.

[[agents]]
id = "support"

default

boolean

default:"false"

Whether this agent is the default. The default agent handles messages that don’t match any binding.Only one agent can be marked as default.

[[agents]]
id = "main"
default = true

display_name

string

Human-readable name shown in the UI and topology graph.

[[agents]]
id = "support"
display_name = "Support Bot"

role

string

Description of the agent’s role (e.g., “handles tier 1 support”). Shown in the UI.

[[agents]]
id = "support"
role = "Handles customer support inquiries"

workspace

string

Custom workspace directory path. If not set, defaults to ~/.spacebot/agents/{id}/workspace.

[[agents]]
id = "dev"
workspace = "/home/user/projects/dev-workspace"

Routing Overrides

routing

object

Override model routing for this agent. See Routing Configuration for details.

[[agents]]
id = "coding"
routing = { worker = "anthropic/claude-sonnet-4" }

Concurrency Settings

max_concurrent_branches

integer

default:"5"

Maximum number of branches this agent can run simultaneously.

[[agents]]
id = "research"
max_concurrent_branches = 10

max_concurrent_workers

integer

default:"5"

Maximum number of workers this agent can run simultaneously.

[[agents]]
id = "coding"
max_concurrent_workers = 3

Turn Limits

max_turns

integer

default:"5"

Maximum LLM turns per channel interaction. The channel process typically uses 1-3 turns.

[[agents]]
id = "main"
max_turns = 10

branch_max_turns

integer

default:"50"

Maximum LLM turns per branch. Branches can iterate many times.

[[agents]]
id = "research"
branch_max_turns = 100

Context Settings

context_window

integer

default:"128000"

Context window size in tokens. Used for compaction thresholds.

[[agents]]
id = "main"
context_window = 200000

compaction

object

Compaction threshold overrides.

Show Properties

background_threshold

float

default:"0.80"

Context fullness (0.0-1.0) that triggers background compaction.

aggressive_threshold

float

default:"0.85"

Context fullness that triggers aggressive summarization.

emergency_threshold

float

default:"0.95"

Context fullness that triggers emergency truncation (no LLM).

[[agents]]
id = "main"
compaction = { background_threshold = 0.75, aggressive_threshold = 0.85 }

Memory Settings

memory_persistence

object

Auto-branching memory persistence configuration.

Show Properties

enabled

boolean

default:"true"

Whether automatic memory persistence branches are enabled.

message_interval

integer

default:"50"

Number of user messages between automatic memory persistence branches.

[[agents]]
id = "main"
memory_persistence = { enabled = true, message_interval = 30 }

Message Handling

coalesce

object

Message coalescing configuration for rapid-fire messages.

Show Properties

enabled

boolean

default:"true"

Enable message coalescing for multi-user channels.

debounce_ms

integer

default:"1500"

Initial debounce window after first message (milliseconds).

max_wait_ms

integer

default:"5000"

Maximum time to wait before flushing (milliseconds).

min_messages

integer

default:"2"

Minimum messages to trigger coalesce mode (1 = always, 2 = only on burst).

multi_user_only

boolean

default:"true"

Apply only to multi-user conversations (skip for DMs).

[[agents]]
id = "chat"
coalesce = { debounce_ms = 2000, max_wait_ms = 6000 }

File Ingestion

ingestion

object

File-based memory ingestion configuration.

Show Properties

enabled

boolean

default:"true"

Whether file-based memory ingestion is enabled.

poll_interval_secs

integer

default:"30"

How often to scan the ingest directory for new files (seconds).

chunk_size

integer

default:"4000"

Target chunk size in characters for file processing.

[[agents]]
id = "docs"
ingestion = { enabled = true, poll_interval_secs = 60, chunk_size = 8000 }

System Configuration

cortex

object

Cortex (system observer) configuration.

Show Properties

tick_interval_secs

integer

default:"30"

Cortex main loop interval (seconds).

worker_timeout_secs

integer

default:"300"

Worker timeout (seconds).

branch_timeout_secs

integer

default:"60"

Branch timeout (seconds).

circuit_breaker_threshold

integer

default:"3"

Consecutive failures before circuit breaker trips.

bulletin_interval_secs

integer

default:"3600"

Interval between memory bulletin refreshes (seconds).

bulletin_max_words

integer

default:"1500"

Target word count for the memory bulletin.

bulletin_max_turns

integer

default:"15"

Maximum LLM turns for bulletin generation.

association_interval_secs

integer

default:"300"

Interval between memory association passes (seconds).

association_similarity_threshold

float

default:"0.85"

Minimum cosine similarity to create a RelatedTo edge.

association_updates_threshold

float

default:"0.95"

Minimum cosine similarity to create an Updates edge (near-duplicate).

association_max_per_pass

integer

default:"100"

Maximum associations to create per pass (rate limit).

warmup

object

Warmup configuration for background model loading.

Show Properties

enabled

boolean

default:"true"

Enable background warmup passes.

eager_embedding_load

boolean

default:"true"

Force-load the embedding model before first recall/write workloads.

refresh_secs

integer

default:"900"

Interval between warmup refresh passes (seconds).

startup_delay_secs

integer

default:"5"

Startup delay before the first warmup pass (seconds).

Tool Configuration

browser

object

Browser automation configuration for workers.

Show Properties

enabled

boolean

default:"true"

Whether browser tools are available to workers.

headless

boolean

default:"true"

Run Chrome in headless mode.

evaluate_enabled

boolean

default:"false"

Allow JavaScript evaluation via the browser tool.

executable_path

string

Custom Chrome/Chromium executable path.

screenshot_dir

string

Directory for storing screenshots. Defaults to agent data directory.

[[agents]]
id = "research"
browser = { enabled = true, headless = false }

mcp

array

MCP server configuration for this agent. See MCP Configuration for details.

[[agents]]
id = "dev"

[[agents.mcp]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

brave_search_key

string

Brave Search API key for web search tool. Overrides the default setting. Supports env:VAR_NAME.

[[agents]]
id = "research"
brave_search_key = "env:BRAVE_SEARCH_API_KEY"

Timezone Settings

cron_timezone

string

Timezone for cron active-hours evaluation (e.g., America/New_York). Falls back to SPACEBOT_CRON_TIMEZONE env var or system local time.

[[agents]]
id = "support"
cron_timezone = "America/New_York"

user_timezone

string

Timezone for channel/worker temporal context (e.g., Europe/London). Falls back to SPACEBOT_USER_TIMEZONE env var, cron_timezone, or system local time.

[[agents]]
id = "assistant"
user_timezone = "Europe/London"

Cron Jobs

cron

array

Scheduled tasks for this agent.

Show Cron Job Properties

string

required

Unique identifier for this cron job.

prompt

string

required

Task prompt sent to the agent.

cron_expr

string

Cron expression in standard 5-field format (minute hour day month weekday). Takes precedence over interval_secs.

interval_secs

integer

Interval in seconds between runs (used if cron_expr is not set).

delivery_target

string

required

Delivery target in adapter:target format (e.g., discord:123456789).

active_start_hour

integer

Start of active hours window (0-23, 24-hour format).

active_end_hour

integer

End of active hours window (0-23, 24-hour format).

enabled

boolean

default:"true"

Whether this cron job is enabled.

run_once

boolean

default:"false"

Run only once at startup, then disable.

timeout_secs

integer

default:"120"

Maximum wall-clock seconds to wait for job completion.

[[agents]]
id = "monitor"

[[agents.cron]]
id = "daily_summary"
prompt = "Generate a daily activity summary"
cron_expr = "0 9 * * *"  # Every day at 9 AM
delivery_target = "discord:987654321"
active_start_hour = 8
active_end_hour = 18

Examples

Basic Agent

[[agents]]
id = "main"
default = true
display_name = "Main Assistant"
role = "General purpose assistant"

Agent with Custom Routing

[[agents]]
id = "coding"
display_name = "Code Assistant"
role = "Handles coding tasks"

[agents.routing]
worker = "anthropic/claude-sonnet-4"
branch = "anthropic/claude-sonnet-4"

[agents.routing.task_overrides]
coding = "anthropic/claude-sonnet-4"

Agent with High Concurrency

[[agents]]
id = "research"
display_name = "Research Bot"
max_concurrent_branches = 20
max_concurrent_workers = 10
branch_max_turns = 100

Agent with Custom Workspace

[[agents]]
id = "dev"
display_name = "Dev Assistant"
workspace = "/home/user/projects/dev-workspace"
brave_search_key = "env:BRAVE_SEARCH_API_KEY"

[[agents.mcp]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

Agent with Scheduled Tasks

[[agents]]
id = "monitor"
display_name = "System Monitor"
cron_timezone = "America/New_York"

[[agents.cron]]
id = "hourly_check"
prompt = "Check system status and report any issues"
interval_secs = 3600
delivery_target = "discord:123456789"
active_start_hour = 8
active_end_hour = 18

[[agents.cron]]
id = "daily_summary"
prompt = "Generate daily activity summary"
cron_expr = "0 17 * * *"  # 5 PM every day
delivery_target = "discord:123456789"

CLI Commands

Configuration

Tools

Agent Configuration

Agent Definition

Routing Overrides

Concurrency Settings

Turn Limits

Context Settings

Memory Settings

Message Handling

File Ingestion

System Configuration

Tool Configuration

Timezone Settings

Cron Jobs

Examples

Basic Agent

Agent with Custom Routing

Agent with High Concurrency

Agent with Custom Workspace

Agent with Scheduled Tasks

Build docs developers (and LLMs) love

CLI Commands

Configuration

Tools

​Agent Definition

​Routing Overrides

​Concurrency Settings

​Turn Limits

​Context Settings

​Memory Settings

​Message Handling

​File Ingestion

​System Configuration

​Tool Configuration

​Timezone Settings

​Cron Jobs

​Examples

​Basic Agent

​Agent with Custom Routing

​Agent with High Concurrency

​Agent with Custom Workspace

​Agent with Scheduled Tasks

Build docs developers (and LLMs) love

Agent Definition

Routing Overrides

Concurrency Settings

Turn Limits

Context Settings

Memory Settings

Message Handling

File Ingestion

System Configuration

Tool Configuration

Timezone Settings

Cron Jobs

Examples

Basic Agent

Agent with Custom Routing

Agent with High Concurrency

Agent with Custom Workspace

Agent with Scheduled Tasks