Documentation v0.30.0
Home GitHub

Configuration

File layout

~/.config/agenvoy/
├── config.json                       Main config — models, limits, channel flags, policy overrides
├── daemon.log                        Daemon log
├── mcp.json                          Global MCP servers
├── tasks.json                        One-shot scheduled tasks
├── crons.json                        Recurring cron tasks
├── allow_skill                       Global skill always-allow list (one name per line)
├── .telegram / .discord              Authorized chat IDs (one per line, written after OTP success)
├── .store/                           ToriiDB store — history, summaries, error memory, config flags
├── prompts/                          User prompt overrides
├── skills/                           Skill storage (git-versioned)
│   ├── .system/                      Bundled skills
│   ├── scheduler/                    Scheduler skill dirs (<short>-<hash8>/SKILL.md)
│   └── .Trash/                       Removed skills (restore_revision recoverable)
├── tools/                            Tool storage (git-versioned)
│   ├── api/                          API tools (single JSON each)
│   ├── script/                       Script tools (tool.json + script.py)
│   ├── .system/                      Bundled tools
│   └── .extension/                   Extension-installed tools
├── errors/                           Error-memory artifacts
├── download/                         Inbound chat attachments and downloaded files
└── sessions/
    └── <sid>/
        ├── bot.md                    Agent persona (frontmatter + body)
        ├── status.json               Active task list / state
        ├── action.log                Tool call audit trail (foreign-process lines prefixed)
        ├── summary.json              Rolling summary
        ├── summary.meta.json         Incremental summary cursor
        ├── usage.log                 Per-model token usage records
        ├── input_history             Per-session TUI input history
        └── mcp.json                  Session-scoped MCP servers

~/.config/kuradb/
├── endpoint                          Plaintext URL (random port), written by KuraDB on spawn
└── runtime.uid                       KuraDB singleton lock

<project-root>/.config/agenvoy/       Project-scoped tools and skills
├── tools/{api,script}/
└── skills/
<project-root>/.agenvoy/allow_skill   Project-scoped skill always-allow list (union with global)

config.json

Beyond model and channel settings, config.json carries the runtime limits and optional policy overrides. Missing limit fields are filled with defaults and written back on startup.

Key Default Description
limits.port 17989 Local HTTP daemon port
limits.max_tool_iterations 128 Maximum tool iterations per run
limits.agent_send_timeout_seconds 600 Model-request timeout
limits.max_history_messages 24 Recent history messages retained
limits.max_history_bytes 5242880 History-size ceiling

Package defaults that are not read from config.json:

Constant Default Description
MaxSessionTasks NumCPU × 4 Concurrent tasks per session; further tasks queue rather than fail
MaxSubagentTimeoutMin 30 Subagent timeout in minutes
MaxResumeWaitMin 60 How long a pending resume waits for answers

Policy arrays in config.json are merged with the values embedded in the binary (user entries add to, never replace, the defaults):

Key Embedded source Purpose
denied_map configs/jsons/denied_map.json Paths the sandbox refuses to expose
white_list configs/jsons/white_list.json Binaries run_command may execute
read_only_command configs/jsons/read_only_command.json Commands that skip the confirm gate (git status, ls, cat, …)
net_white_list configs/jsons/net_white_list.json Hosts exempt from the send_http_request SSRF guard

There are no environment variables for runtime limits — env-based overrides were removed; config.json is the only knob.

Project configs

configs/
├── jsons/
│   ├── denied_map.json               Sandbox denied paths
│   ├── exclude_list.json             Listing/walking exclude paths
│   ├── white_list.json               Allowed command binaries
│   ├── read_only_command.json        Commands that skip confirmation
│   ├── net_white_list.json           SSRF-guard exemptions
│   ├── never_open.json               System dirs that never open
│   └── tui_tools.json                TUI tool display metadata
└── prompts/                          System prompt templates, reasoning guides, channel prompts

Provider and model catalogs no longer ship in the repository — model lists are fetched live from each provider's API.

bot.md format

***
name: <session display name>     # used by :name routing and invoke_subagent name param
***

<persona content as free-form markdown>

The body is rendered into the system prompt's ## Bot Persona block on every turn. Frontmatter name defaults to the session id when not set. Create and rename sessions from the TUI (/new, /bot) or the local API (POST / PUT /v1/session).

Permission mode

The active permission mode (single-confirm vs always-allow) is decided by entry point:

Entry Mode
agen cli single-confirm (AllowAll=false)
agen run always-allow (AllowAll=true)
TUI single-confirm, toggled per session with Shift+Tab
Discord / REST always-allow
Telegram single-confirm (confirm gate uses Telegram inline-keyboard select)
Subagent Inherits parent ctx

The mode is rendered into the system prompt under ## Permission Mode. Commands on the read-only list skip the gate in every mode.

MCP config

Two layers; session overrides global. See the MCP Client page for the full schema and ${VAR} expansion behavior.

KuraDB

Enabled state is kuradb_enabled in config.json. Toggle via /kuradb in the TUI, or POST /v1/kuradb for start/stop of an already-installed instance (install still needs a real TTY for sudo).

Key Location
kuradb_enabled config.json
OPENAI_API_KEY keychain (agenvoy service) — shared with semantic search
Endpoint URL (runtime) ~/.config/kuradb/endpoint (plaintext, random port per spawn)
Binary /usr/local/bin/kura

Telegram / Discord enablement

Key Location
telegram_enabled / discord_enabled config.json
TELEGRAM_TOKEN / DISCORD_TOKEN keychain (agenvoy service)
Authorized chat IDs ~/.config/agenvoy/.telegram, ~/.config/agenvoy/.discord (written after 6-digit OTP verification succeeds)
Verification-code relay target admin_channel in config.json (/admin-channel in the TUI)

Where things deliberately do not live

中文