Getting Started

Prerequisites

• An LLM API key from any supported provider
• Recommended tools for best performance:
  • ripgrep (rg) — fast code search that UGENT uses for search_files
  • fd (fd) — fast file finder that UGENT uses for find_files

Install recommended tools:

# macOS
brew install ripgrep fd

# Ubuntu/Debian
sudo apt install ripgrep fd-find

# Cargo
cargo install ripgrep fd-find

Install UGENT

Use the installation script to download the binary and initialize the config:

curl -fsSL https://ugent.dev/install.sh | bash

Or manually download the binary and add it to your PATH.

First Configuration

Create ~/.ugent/ugent.toml:

[agent]
name = "ugent"
max_iterations = 500
auto_checkpoint = true

[llm]
default_instance = "openai"

[llm.instances.openai]
type = "openai"
api_key = "$OPENAI_API_KEY"
default_model = "gpt-5.4-mini"

Set the API key:

export OPENAI_API_KEY="sk-..."

Run

TUI Mode (default)

ugent

Interactive terminal interface with streaming, code blocks, sub-agent panel, and debug panel.

REPL Mode

ugent --repl

Line-oriented REPL for scripting and piping.

Execute Mode

ugent --execute "Explain the architecture of this project"

Single-shot execution — returns the answer and exits. Combine with --show-assistant for real-time streaming.

Daemon Mode

ugent daemon --workspace /srv/ugent/workspace

Runs the full runtime as a foreground process for systemd supervision.

Config File Locations

UGENT discovers config files in this order (first found wins):

1. <workspace>/ugent.toml
2. <workspace>/.ugent/ugent.toml
3. ~/.ugent/ugent.toml

Dedicated config files (discovered the same way):

File	Purpose
cron.toml	Scheduled jobs
routing.toml	Message routing pipeline
rules.toml	Rule engine
plugins.toml	Plugin registration
firewall.toml	Injection firewall
external_agents.toml	Claude Code / Codex monitors

Next Steps

• Configure LLM providers — multi-model setup, failover, reasoning
• Configure memory — full-text search, embeddings, compaction
• Configure MCP servers — connect external tools
• Configure skills — Claude Code compatible skill files
• Security & firewall — injection firewall, taint tracking