Runtime & CLI Flags

Thread Pool Configuration

[runtime]
worker_threads = "auto"           # or a fixed integer
max_blocking_threads = 512
thread_keep_alive_secs = 60

The two-phase bootstrap reads [runtime] before the tokio runtime is created, so thread pool tuning takes effect immediately at startup.

HTTP Connection Pool

[runtime]
http_pool_max_idle_per_host = 16
http_pool_idle_timeout_secs = 90
http_tcp_keepalive_secs = 60
http_connect_timeout_secs = 15
enable_http2 = true               # set false to force HTTP/1.1

These apply to all real provider clients (OpenAI, Anthropic, Google, Ollama, OpenRouter, DashScope, OpenAI-compatible).

Parallel Tool Execution

[agent]
max_concurrent_tools = 8           # default: 8
enable_parallel_tool_calls = true

Parallelism is conflict-aware — independent reads batch together, while writers and shell commands serialize.

CLI Flags

Mode Selection

Flag	Mode
(none)	TUI (interactive terminal)
--repl	REPL (line-oriented)
--execute "query"	Execute (single-shot, exits on completion)
daemon --workspace <path>	Daemon (systemd foreground process)

Execute Mode Options

ugent --execute "query" [options]

Flag	Description
--show-assistant	Stream assistant chunks to stdout in real time
--verbose	Show diagnostic stderr output (INFO, WARN, BOOT)
--output json	Machine-readable JSON output
--output json-seq	JSON-Seq event stream
--continue	Resume the latest session for this workspace
--resume <session-id>	Resume a specific session by ID

Disable Flags

Flag	Effect
--disable-mcp	Skip loading all MCP servers
--disable-skills	Skip loading skills from disk
--disable-memory	Disable long-term memory for this session
--disable-bash	Omit the bash tool (agent cannot run commands)
--disable-firewall	Disable injection firewall (debugging only)

Security Flags

Flag	Effect
--allow-dangerous-action	Relax dangerous-action confirmation
--allow-sensitive-read	Relax sensitive-file-read guard
--auto-confirm-bash	Auto-approve all bash commands
--sandbox	Force the OS sandbox to auto (contain when a backend works)
--no-sandbox	Force the OS sandbox off — escape hatch, outranks sandbox.toml
--sandbox-required	Refuse to start unless the OS sandbox is enforcing

The sandbox flags are mutually exclusive and outrank sandbox.toml in both directions. See OS Sandbox.

Context Engine

ugent --enable-context-engine

Persists context_client.enabled = true to the config file. Use /context enable from inside TUI/REPL for the interactive path with preflight validation.

Hot Reload

UGENT watches ugent.toml and all overlay files (cron.toml, routing.toml, etc.) for changes. On modification:

• Config reloads and overlays re-apply
• Cron restarts in place
• Routing changes force a full agent rebuild (routing hooks are frozen into the orchestrator chain at build time)

A Reload Stops the Old Runtime

Before anything replaces it, a reload stops the running orchestrator — the daemon's reload after a config change, the REPL's rebuild and the TUI's /reload alike — and so does a daemon or REPL shutdown:

• Every loop the orchestrator runs ends, and a delegated worker's turn in progress is cut short.
• A task check in progress is stopped with its process group and its working copy removed, and nothing is accepted for it.
• The task is left as it stood. A web or channel conversation waiting on it is told by the replacement that it was interrupted, as after a restart. A REPL or cron turn still waiting on it ends, saying the orchestrator stopped, and is not resumed.
• The stop waits up to 20 seconds. Work still running after that can no longer change the saved state.
• The stopped runtime's last act is one save. On a reload it keeps this process's claim on the saved work, so the replacement recovers it and another instance in the same workspace leaves it alone. On a shutdown it releases the claim, so the next start recovers the work at once instead of waiting out the three-minute staleness window.

The log says the orchestrator stopped; the runtime that replaces it takes over its saved state on a reload, and the orchestrator stopped and released its saved state on a shutdown. A runtime that had delegated nothing logs the orchestrator stopped; it had no state to save instead. Quitting the TUI simply ends the process; a later start recovers its saved work once the three-minute window has passed.

systemd

systemctl stop runs the same orderly stop only with KillMode=mixed, the shipped unit's setting: SIGTERM goes to the daemon alone, and whatever is left is killed once it exits or at TimeoutStopSec. With KillMode=control-group, systemd's SIGTERM reaches a running check at once and it is recorded as a failed check. On an older install, apply it with a drop-in — systemctl edit ugent, then [Service] and KillMode=mixed — and systemctl daemon-reload.

Setup Hub

# Inside TUI or REPL:
/setup                    # Show available tracks
/setup llm                # Configure LLM providers
/setup audio              # Configure audio/live session
/setup embedding          # Configure memory embeddings
/setup context            # Configure context engine
/setup doctor             # Non-mutating health audit

The setup wizard guides through configuration with preflight validation.