Configuration¶

Upgrading from pre-1.3.14? Read Upgrading from pre-1.3.14 before restarting the bot — the security hardening changed a few defaults and your admin/Telegram access may stop working until you complete the migration.

Runtime config file: ~/.sygen/config/config.json.

Seed source: <repo>/config.example.json (source checkout) or packaged fallback sygen_bot/_config_example.json (installed mode).

Config Creation¶

Primary path: sygen onboarding (interactive wizard) writes config.json with user-provided values merged into AgentConfig defaults.

Load & Merge Behavior¶

Config is merged in two places:

1. sygen_bot/__main__.py::load_config()
2. creates config on first start (copy from config.example.json or Pydantic defaults),
3. deep-merges runtime file with AgentConfig defaults,
4. writes back only when new keys were added.
5. sygen_bot/workspace/init.py::_smart_merge_config()
6. shallow merge {**defaults, **existing} with config.example.json,
7. preserves existing user top-level keys,
8. fills missing top-level keys from config.example.json.

Normalization detail:

• onboarding and runtime config load normalize gemini_api_key default to string "null" in persisted JSON for backward compatibility.
• AgentConfig validator converts null-like text ("", "null", "none") to None at runtime.

Runtime edits persisted through config helpers include /model changes (model/provider/reasoning), webhook token auto-generation, and API token auto-generation.

API config persistence note:

• load_config() intentionally does not auto-add the api block during default deep-merge (beta gating).
• sygen api enable writes the api block (including generated token) into config.json.

External API Secrets (~/.sygen/.env)¶

User-defined environment secrets for external APIs (e.g. PPLX_API_KEY, DEEPSEEK_API_KEY).

Standard dotenv syntax:

PPLX_API_KEY=sk-xxx
DEEPSEEK_API_KEY=sk-yyy
export MY_VAR="quoted value"

Propagation:

• host CLI execution: merged into subprocess env via _build_subprocess_env()
• Docker exec: injected as -e flags via docker_wrap()
• Docker container creation: injected as -e flags via _start_container()
• sub-agents and background tasks: inherited through the same execution paths

Priority (highest to lowest):

1. existing host environment variables (never overridden)
2. provider-specific config (e.g. gemini_api_key in config.json)
3. .env values (fill gaps only)

Changes take effect on the next CLI invocation (mtime-based cache invalidation, no restart needed).

AgentConfig (sygen_bot/config.py)¶

Multi-transport behavior¶

When transports is empty (default), the single transport value is used. When transports contains multiple entries (e.g. ["telegram", "matrix"]), MultiBotAdapter starts all listed transports in parallel and transport is auto-set to the first entry. A model validator normalizes both fields at load time so they stay consistent.

Per-role permission modes¶

The permission_mode_by_role field maps user roles to CLI --permission-mode values. When a CLI session is started on behalf of a user, the resolver looks the user's role up in this map and passes the corresponding mode to the Claude CLI. System-initiated calls (cron, webhooks, background observers) run with the "admin" role.

Resolution order:

1. If the caller provides a role and the role is present in permission_mode_by_role, use the mapped value.
2. Otherwise, fall back to the top-level permission_mode field (legacy behaviour).

Recommended defaults:

Valid values are the same as the Claude CLI's --permission-mode flag: acceptEdits, auto, bypassPermissions, default, dontAsk, plan. Unknown values fail config validation at load time.

To opt out of per-role resolution entirely (legacy behaviour), set permission_mode_by_role to {} — the resolver then always returns the top-level permission_mode.

Role sources (who resolves the role)¶

The role threaded into permission_mode_by_role can come from four places:

Per-user access control (users.json)¶

~/.sygen/_secrets/users.json stores user accounts used by the admin panel, the Telegram role resolver, and the inter-agent ACL. Each user record supports the following fields relevant to authorization:

Unknown users (no matching record) fall through to legacy behaviour so rolling deployments do not break in-flight sessions.

Example:

{
  "users": [
    {
      "username": "alice",
      "role": "operator",
      "active": true,
      "allowed_agents": ["main", "research"],
      "telegram_user_ids": [1234567]
    }
  ]
}

MatrixConfig¶

Notes:

• first successful login persists credentials to ~/.sygen/<store_path>/credentials.json (mode 0o600), not back into config.json
• when access_token and device_id are explicitly present in config.json, runtime restores from them and also mirrors them into the credentials store
• The bot supports end-to-end encrypted rooms via matrix-nio[e2e].
• allowed_rooms and allowed_users together form the Matrix auth model.

CLIParametersConfig¶

Used by CLIServiceConfig for main-chat calls.

Argument shape note:

• each list element is passed as one CLI argument; do not combine multiple shell flags into one string such as "--verbose --chrome"

Automation note:

• cron/webhook cron_task runs use task-level cli_parameters from cron_jobs.json / webhooks.json (no merge with global cli_parameters).

TimeoutConfig¶

Runtime sync behavior:

• AgentConfig keeps backward compatibility with cli_timeout.
• If cli_timeout != 600.0 and timeouts.normal is still default, runtime validation copies cli_timeout into timeouts.normal.
• If timeouts.normal is explicitly set, it wins over cli_timeout.

Current execution-path usage:

• foreground chat turns: resolve_timeout(config, "normal") -> timeouts.normal
• named background sessions (/session): timeouts.background
• delegated background tasks (TaskHub): tasks.timeout_seconds
• cron + webhook cron_task: still config.cli_timeout
• inter-agent turns: still config.cli_timeout
• stale-process cleanup threshold: config.cli_timeout * 2

Implementation status note:

• cli/timeout_controller.py and warning/extension config are implemented and tested.
• provider wrappers and executor support TimeoutController in production paths.
• normal/streaming/named-session/heartbeat flows create controllers via flows._make_timeout_controller(...).
• timeout warning/extension callbacks are not yet wired to Telegram/API system-status output, so user-visible timeout status labels are not emitted by default.

TasksConfig¶

Task-Level Automation Overrides¶

Stored outside config.json in:

• ~/.sygen/cron_jobs.json (CronJob)
• ~/.sygen/webhooks.json (WebhookEntry, cron_task mode)

Common per-task fields:

• execution: provider, model, reasoning_effort, cli_parameters
• scheduling guards: quiet_start, quiet_end, dependency

Cron-only field:

• timezone (per-job timezone override)

Behavior notes:

• missing execution fields fall back to global config via resolve_cli_config(),
• dependency is global across cron + webhook cron_task runs (shared DependencyQueue),
• quiet-hour checks run only when per-task quiet fields are set (no fallback to global heartbeat quiet settings).

StreamingConfig¶

DockerConfig¶

Orchestrator.create() calls DockerManager.setup() when enabled. If setup fails, sygen logs warning and falls back to host execution.

mount_host_cache¶

Mounts the host's platform-specific cache directory into the container at /home/node/.cache:

Use case: browser-based skills (e.g. google-ai-mode) that use patchright/playwright need access to persistent browser profiles and browser binaries stored in the host cache. Without this, each container start requires a fresh CAPTCHA solve and Chrome download.

Disabled by default because it exposes the host cache directory to the sandbox.

mounts¶

User-defined directory mounts for project/data access inside Docker sandbox.

• each entry is expanded (~, env vars), resolved, and validated as an existing directory
• each entry is just a host directory path (for example "/home/you/projects"), not Docker host:container[:mode] syntax
• invalid or missing entries are skipped with warnings
• container target path is derived from host basename: /mnt/<sanitized-name>
• duplicate target names are disambiguated as /mnt/name_2, /mnt/name_3, ...

Runtime note:

• updates are typically managed via sygen docker mount|unmount
• changing mounts requires bot restart (or sygen docker rebuild) to affect container run flags

extras¶

Optional AI/ML packages installed into the Docker sandbox image at build time. Each entry is an ID from the extras registry (sygen_bot/infra/docker_extras.py).

Available extras:

Dependency resolution:

• whisper depends on ffmpeg
• easyocr and transformers depend on pytorch-cpu
• dependencies are auto-resolved at build time

Managed via sygen docker extras-add|extras-remove or during onboarding wizard. Changes require sygen docker rebuild to take effect.

When extras are configured, the supervisor startup timeout is dynamically extended to accommodate longer Docker build times.

HeartbeatConfig¶

HeartbeatTarget¶

Each entry in group_targets identifies a specific group chat (and optional topic) to send heartbeat checks to. All optional fields override the global HeartbeatConfig when set; unset fields fall back to global values.

ImageConfig¶

Applied to incoming images across all transports (Telegram, Matrix, API). See files/image_processor.py for implementation details.

TranscriptionConfig¶

Controls audio/video transcription behavior for voice messages and video notes.

Strategy chain¶

Transcription tries backends in this order:

1. Custom command (only when command is set) — receives audio file path as argument, prints transcript to stdout
2. OpenAI Whisper API — requires OPENAI_API_KEY in environment or .env
3. Local whisper CLI — Python openai-whisper package
4. whisper-cli — whisper.cpp (C++ implementation, 5-10x faster than Python on CPU)

First successful backend wins. If all fail, an error with installation hints is returned.

Custom command interface¶

When command is set, it is called as:

/path/to/your/command /path/to/audio.ogg

Environment variables passed to the command:

• TRANSCRIPTION_LANGUAGE — configured language (e.g. "auto", "en")
• TRANSCRIPTION_MODEL — configured model size (e.g. "small")

The command must print the transcript text to stdout and exit with code 0. On non-zero exit or empty output, the next strategy in the chain is tried.

Model sizes¶

Quick setup¶

Fastest path for new users — cloud API (no local install):

# ~/.sygen/.env
OPENAI_API_KEY=sk-xxx

Fastest local path — whisper.cpp:

# Install whisper.cpp, then download model:
# https://github.com/ggerganov/whisper.cpp
whisper-cli --help  # verify installation

Hot-reloadable: yes (changes apply without restart).

SceneConfig¶

CleanupConfig¶

Cleanup implementation detail:

• cleanup is recursive (_delete_old_files walks nested files via rglob("*")),
• after file deletion, empty subdirectories are pruned,
• dated upload folders (.../YYYY-MM-DD/...) are cleaned when contained files exceed retention and directories become empty.

MemoryConfig¶

Memory injection behavior¶

Memory modules are injected into the agent's context at two points:

1. Session start — full content of selected modules is injected via --append-system-prompt
2. Every 6 messages — MAINMEMORY_REMINDER hook re-injects module content (truncated to hook_compact_lines per module) to prevent knowledge loss after context compaction

Which modules are injected depends on inject_all_modules:

• false (default) — only modules listed in the "Always Load" table in MAINMEMORY.md (typically user.md and decisions.md)
• true — all .md files in memory_system/modules/ are injected

Token cost estimates¶

With 2 Always Load modules (~25 lines each): - Session start: ~1.5K tokens (one-time) - Hook (every 6 msgs): ~600 tokens with hook_compact_lines=20

With 5 modules and inject_all_modules=true: - Session start: ~3K tokens (one-time) - Hook (every 6 msgs): ~1.2K tokens with hook_compact_lines=20

For users with high-tier API plans who prioritize agent knowledge over token cost, set inject_all_modules=true and increase hook_compact_lines (e.g. 50 or 100).

Vector search (semantic memory)¶

Optional feature for semantic search over memory facts. Instead of injecting entire modules, the hook searches for facts relevant to the current conversation.

Installation:

pip install sygen[vector]    # ChromaDB + sentence-transformers (multilingual, ~500MB)

Enable:

"memory": {
  "vector_search": true
}

How it works:

1. Memory module facts (list items) are automatically indexed as embeddings
2. On each hook trigger, the user's message is used as a search query
3. Top-N semantically relevant facts are injected instead of full modules
4. Falls back to module-based injection if vector search returns no results

Model priority:

1. sentence-transformers multilingual model (if installed) — best for non-English
2. ChromaDB built-in ONNX model — English-focused, no extra dependencies
3. Custom model via vector_model config option

Vector search complements (not replaces) the module-based system. Both can be active simultaneously — vector search provides targeted facts while Always Load ensures core context.

WebhookConfig¶

FileshareConfig¶

When enabled, sets FILESHARE_URL and FILESHARE_DOWNLOADS environment variables for agent tools (used by send_large_file.py). See fileshare.md for full details.

ApiConfig¶

Runtime note (Orchestrator._start_api_server + ApiServer._authenticate):

• config.api.chat_id is used via truthiness (0 falls back),
• fallback default comes from first allowed_user_ids entry (fallback 1),
• per-connection auth payload may override via:
• {"type":"auth","chat_id":...} (positive int),
• optional channel_id (positive int) for per-channel session isolation (SessionKey.topic_id),
• clients can override only for that connection; persisted default stays in config.

InteragentConfig¶

Configurable via config.json:

"interagent": {
    "sync_timeout": 600.0,
    "async_timeout": 3600.0
}

Runtime hot-reload (config_reload.py)¶

Orchestrator.create() starts ConfigReloader, which polls config.json every 5 seconds, validates it with AgentConfig, diffs top-level fields, and applies safe changes without restart.

Hot-reloadable top-level fields:

• model, provider, reasoning_effort
• cli_timeout, max_budget_usd, max_turns, max_session_messages
• idle_timeout_minutes, session_age_warning_hours, daily_reset_hour, daily_reset_enabled
• permission_mode, permission_mode_by_role, file_access, user_timezone
• streaming, heartbeat, cleanup, cli_parameters
• allowed_user_ids, allowed_group_ids, group_mention_only
• transcription
• timeouts is currently restart-required (not in hot-reloadable set)

Observer lifecycle caveat:

• heartbeat/cleanup values hot-reload into config
• observer start/stop is not hot-toggled
• enabling heartbeat/cleanup after startup requires restart if the observer was not started initially

Restart-required top-level fields:

• transport, telegram_token, matrix
• docker, api, webhooks
• sygen_home, log_level, gemini_api_key, timeouts, tasks

Restart classification is computed from AgentConfig top-level schema fields.

Model Resolution¶

ModelRegistry (sygen_bot/config.py):

• Claude models are hardcoded: haiku, sonnet, opus.
• Gemini aliases are hardcoded: auto, pro, flash, flash-lite.
• Runtime Gemini models are discovered from local Gemini CLI files at startup.
• Provider resolution (provider_for(model_id)):
• Claude when in CLAUDE_MODELS,
• Gemini when in aliases/discovered set or when model looks like gemini-*/auto-gemini-*,
• otherwise Codex.

Timezone Resolution¶

resolve_user_timezone(configured) in sygen_bot/config.py:

1. valid configured IANA timezone,
2. $TZ env var,
3. host system detection:
4. Windows: local datetime tzinfo,
5. POSIX: /etc/localtime symlink,
6. fallback UTC.

Returns ZoneInfo when available, otherwise a UTC tzinfo fallback object with key="UTC" on systems without timezone data. Used by cron scheduling, session daily-reset checks, heartbeat quiet hours, and cleanup scheduling.

reasoning_effort¶

UI values: low, medium, high, xhigh.

Main-chat flow:

AgentConfig -> CLIServiceConfig -> CLIConfig -> CodexCLI (-c model_reasoning_effort=<value> when relevant).

Automation flow:

• resolve_cli_config() applies reasoning effort only for Codex models that support the requested effort.

Codex Model Cache¶

Path: ~/.sygen/config/codex_models.json.

Behavior:

• loaded at orchestrator startup (CodexCacheObserver.start()),
• startup load is forced refresh (force_refresh=True),
• checked hourly in background,
• load_or_refresh() uses cache if <24h old, otherwise re-discovers via Codex app server,
• consumed by /model wizard, resolve_cli_config() for cron/webhook validation, and /diagnose output.

Gemini Model Cache¶

Path: ~/.sygen/config/gemini_models.json.

Behavior:

• loaded at orchestrator startup (GeminiCacheObserver.start()),
• startup load uses cached data when fresh and refreshes only when stale/missing,
• refreshed hourly in background,
• refresh callback updates runtime Gemini model registry (set_gemini_models(...)) used by directives and model selector.

agents.json (Multi-Agent Registry)¶

Path: ~/.sygen/agents.json.

Top-level JSON array of SubAgentConfig objects. Each entry defines a sub-agent that runs alongside the main agent.

Managed via:

• sygen agents add <name> (interactive CLI, currently Telegram-focused)
• sygen agents remove <name> (CLI)
• create_agent.py / remove_agent.py tool scripts (from within a CLI session)
• manual file editing (auto-detected by FileWatcher)

SubAgentConfig fields¶

"inherited" means the value comes from the main agent's config.json when omitted.

Timeout nuance:

• SubAgentConfig currently has no dedicated timeouts field.
• SubAgentConfig currently has no dedicated tasks field.
• sub-agents inherit the main agent timeouts block through merge base.
• sub-agents inherit the main agent tasks block through merge base.

Example:

[
  {
    "name": "researcher",
    "telegram_token": "123456:ABC...",
    "allowed_user_ids": [12345678],
    "provider": "claude",
    "model": "sonnet"
  },
  {
    "name": "coder",
    "transport": "matrix",
    "matrix": {
      "homeserver": "https://matrix.example.com",
      "user_id": "@coder:example.com",
      "password": "...",
      "allowed_rooms": ["!room:example.com"],
      "allowed_users": ["@user:example.com"]
    },
    "provider": "codex",
    "reasoning_effort": "high"
  }
]

Sub-agent runtime merge behavior¶

merge_sub_agent_config(main, sub, agent_home) builds the effective sub-agent AgentConfig with this priority:

1. main agent config (config.json) as base
2. sub-agent's own config/config.json (if present)
3. explicit non-null overrides from agents.json (highest priority)

Then it always forces:

• sygen_home = ~/.sygen/agents/<name>/
• transport, telegram_token, matrix, allowed_user_ids, and allowed_group_ids from the sub-agent entry
• api.enabled = false when no explicit api block is provided
• additional_directories = [] reset before layers 2 and 3 — sub-agents never inherit the main agent's extra paths (see Sub-agent sandbox)

Notes:

• /model changes in a sub-agent chat are written back to agents.json, so restart/reload uses the updated values from that registry file

Sub-agent sandbox¶

Sub-agent filesystem access is enforced by two independent layers:

1. Claude CLI --add-dir — baseline sandbox when the CLI runs in permission_mode="default" / "acceptEdits". The allowed roots are cwd plus the paths in additional_directories.
2. PreToolUse hook (~/.sygen/agents/<name>/workspace/.claude/ file_sandbox.py, since 1.3.45) — blocks Read, Edit, Write, MultiEdit, NotebookEdit, Grep, Glob calls whose target is outside the sub-agent's workspace plus additional_directories. Bash and other tools pass through so Gradle, Xcode, docker, and git keep working. The hook is required because admin-role sub-agents run with permission_mode="bypassPermissions", which skips the --add-dir check entirely — without the hook, a bypass-permissions sub-agent could read anywhere the user process can.

The hook reads additional_directories directly from ~/.sygen/_secrets/agents.json on every call, so changes from the admin UI take effect on the next CLI invocation with no redeploy. The agent identity comes from the SYGEN_AGENT_NAME env var injected by sygen_bot.cli.executor._build_subprocess_env, so cd into an allowlist directory cannot disable the sandbox.

_ensure_sandbox_hook in sygen_bot/workspace/init.py installs the hook on every init_workspace() call for any path of the form ~/.sygen/agents/<name>/workspace/. The main agent (~/.sygen/workspace/) is skipped — it runs as the admin user with full file access.

For the main agent, the CLI sandbox is sygen_home + config.additional_directories, which typically includes the Sygen source checkout and the admin panel.

Sub-agents are untrusted delegates: each gets its own ~/.sygen/agents/<name>/ workspace and nothing else.

• Default: additional_directories = [] (workspace-only).
• Main's additional_directories is not inherited by sub-agents.
• Admin grants extra paths per sub-agent via:
• the admin panel (Agents → select agent → Sandbox), or
• editing the additional_directories field on the agent's entry in ~/.sygen/_secrets/agents.json, or
• the sub-agent's own config/config.json (useful when the sub-agent runs on a different host that was provisioned separately).
• Sub-agents cannot extend their own sandbox from inside a chat session. They can ask the main agent or the admin; granting is a privileged action.

REST API: PUT /api/agents/{name} with body {"additional_directories": ["/abs/path", ...]} (admin-only). Paths are validated (absolute, must exist as directories) and de-duplicated.

agents.json watcher behavior¶

AgentSupervisor watches agents.json (mtime poll every 5s):

• new entry -> start sub-agent
• removed entry -> stop sub-agent
• restart triggers for running agents:
• transport changed
• Telegram identity changed (telegram_token)
• Matrix identity changed (matrix.homeserver or matrix.user_id)
• other field changes currently do not auto-restart running agents

For non-token field updates on a running agent, use /agent_restart <name> (or restart the bot) to apply them immediately.

Upgrading from pre-1.3.14¶

Version 1.3.14 landed a security hardening pass that changes defaults a pre-1.3.14 install was silently relying on. After pip install -U sygen (or /upgrade), walk through the steps below before restarting the bot. Skipping them typically manifests as: "Claude CLI approval popups for every file edit and shell command, but there is no popup UI in Telegram."

1. Secrets moved to ~/.sygen/_secrets/¶

Files that used to live directly in ~/.sygen/ now live in ~/.sygen/_secrets/ (mode 0700, files 0600):

• users.json
• agents.json
• main_agent_token.json

The framework reads both locations during the 1.3.x line — the legacy path keeps working. But all new writes go to _secrets/, so if you have tooling that edits ~/.sygen/users.json directly, point it at ~/.sygen/_secrets/users.json or use the admin API.

2. Telegram users need telegram_user_ids mapping¶

The CLI permission mode is now chosen from permission_mode_by_role:

"permission_mode_by_role": {
  "admin": "bypassPermissions",
  "operator": "acceptEdits",
  "viewer": "default"
}

For a Telegram message, the bot looks up the sender's numeric from_user.id in every record's telegram_user_ids list in users.json. If no record matches, the role resolves to None and the CLI is started with permission_mode="default" — Claude will ask for approval on every write and tool call, and Telegram has no UI to answer those prompts, so the session hangs.

Fix: make sure every human who talks to the bot has a record in users.json whose telegram_user_ids contains their Telegram ID. The admin panel's Users page exposes this field (since admin 0.3.3); or edit ~/.sygen/_secrets/users.json directly.

Tip: send a message to the bot from a machine you can tail logs on — the bot logs the unknown sender's ID on the first message, which you can then paste into the admin form.

Fresh installs from 1.3.23+: the bootstrap admin's telegram_user_ids is seeded automatically from config.allowed_user_ids on first run, so the setup wizard's single "your Telegram ID" prompt now populates both ACL gates. Upgrades from earlier versions still need a one-time manual edit if the admin record was created before this behavior existed.

3. Inter-agent calls require caller_token¶

Each sub-agent's record in agents.json gained an interagent_token field. The Sygen CLI writes it automatically when a sub-agent is created after 1.3.14; for older sub-agents the framework still accepts token-less requests but logs a warning ("running in legacy mode"). You can regenerate the token by recreating the sub-agent, or edit _secrets/agents.json by hand and add a 32+ char random string as "interagent_token".

4. The --user-id flag is gone¶

ask_agent.py and ask_agent_async.py no longer accept --user-id — the caller identity is taken only from the SYGEN_CALLER_USER_ID env var, which the framework sets from the authenticated transport. Passing the flag now exits with code 2 and a message explaining the change. Cron scripts and workflow steps that pass --user-id must be edited. Rationale: the flag let a prompt-injected LLM tool call impersonate any user and bypass per-user ACLs.

5. Additional directories for the Claude sandbox¶

If Sygen now lives at a non-default path (e.g. you develop it outside ~/.sygen/), add it to cli.additional_directories so Claude can read files from the source checkout:

"cli": {
  "additional_directories": [
    "/Users/you/Agents/sygen",
    "/Users/you/sygen-admin"
  ]
}

Validation rejects relative paths and non-existent directories at startup — you'll see a clear error rather than a silent bypass.

6. Sub-agents are now workspace-only by default¶

Starting with the current release, sub-agents no longer inherit the main agent's additional_directories. On upgrade, every existing sub-agent is silently narrowed to its own ~/.sygen/agents/<name>/ workspace. No config migration is required.

If an existing sub-agent genuinely needs access outside its workspace (for example, a "builder" agent that touches the Sygen source), grant the paths explicitly:

• Admin panel → Agents → open the agent → Sandbox → add the path and save
• Or edit additional_directories on the agent's entry in ~/.sygen/_secrets/agents.json.

The main agent is unaffected — its sandbox continues to come from config.json and still covers the full set of admin-granted paths.